@mcp-s/skills 1.0.2 → 1.3.1

package/README.md

@@ -1,137 +1,440 @@
-# @mcp-s/skills
+# skills
 
-Install skills onto coding agents from an MCP-S server. Supports Claude Code, Cline, Codex, Cursor, Windsurf, and many more AI coding agents.
+The CLI for the open agent skills ecosystem.
 
-## Usage
+<!-- agent-list:start -->
+Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [36 more](#supported-agents).
+<!-- agent-list:end -->
+
+## Install a Skill
 
 ```bash
-npx @mcp-s/skills --org <org> [options]
-# or
-npx @mcp-s/skills --base-url <url> [options]
+npx skills add vercel-labs/agent-skills
+```
+
+### Source Formats
+
+```bash
+# GitHub shorthand (owner/repo)
+npx skills add vercel-labs/agent-skills
+
+# Full GitHub URL
+npx skills add https://github.com/vercel-labs/agent-skills
+
+# Direct path to a skill in a repo
+npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
+
+# GitLab URL
+npx skills add https://gitlab.com/org/repo
+
+# Any git URL
+npx skills add git@github.com:vercel-labs/agent-skills.git
+
+# Local path
+npx skills add ./my-local-skills
 ```
 
 ### Options
 
-- `-o, --org <org>` - Organization name (builds URL as `https://<org>.mcp-s.com/skills`)
-- `-b, --base-url <url>` - Full base URL of the MCP-S skills server
-- `-g, --global` - Install skill globally (user-level) instead of project-level
-- `-a, --agent <agents...>` - Specify agents to install to (claude-code, cline, codex, cursor, etc.)
-- `-s, --skill <skills...>` - Specify skill slugs to install (skip selection prompt)
-- `-l, --list` - List available skills without installing
-- `-y, --yes` - Skip confirmation prompts
-- `--all` - Install all skills to all agents without any prompts (implies -y -g)
+| Option                    | Description                                                                                                                                        |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-g, --global`            | Install to user directory instead of project                                                                                                       |
+| `-a, --agent <agents...>` | <!-- agent-names:start -->Target specific agents (e.g., `claude-code`, `codex`). See [Supported Agents](#supported-agents)<!-- agent-names:end -->                  |
+| `-s, --skill <skills...>` | Install specific skills by name (use `'*'` for all skills)                                                                                         |
+| `-l, --list`              | List available skills without installing                                                                                                           |
+| `-y, --yes`               | Skip all confirmation prompts                                                                                                                      |
+| `--all`                   | Install all skills to all agents without prompts                                                                                                   |
+
+### Examples
+
+```bash
+# List skills in a repository
+npx skills add vercel-labs/agent-skills --list
+
+# Install specific skills
+npx skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator
 
-## Authentication
+# Install a skill with spaces in the name (must be quoted)
+npx skills add owner/repo --skill "Convex Best Practices"
 
-The CLI automatically handles authentication. On first run, it will:
-1. Generate authentication credentials
-2. Open your browser to complete authentication
-3. Save the credentials for future use
+# Install to specific agents
+npx skills add vercel-labs/agent-skills -a claude-code -a opencode
 
-Credentials are stored in `~/.mcp-s/skills-config.json`.
+# Non-interactive installation (CI/CD friendly)
+npx skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y
 
-## Examples
+# Install all skills from a repo to all agents
+npx skills add vercel-labs/agent-skills --all
 
-### List available skills
+# Install all skills to specific agents
+npx skills add vercel-labs/agent-skills --skill '*' -a claude-code
+
+# Install specific skills to all agents
+npx skills add vercel-labs/agent-skills --agent '*' --skill frontend-design
+```
+
+### Installation Scope
+
+| Scope       | Flag      | Location            | Use Case                                      |
+| ----------- | --------- | ------------------- | --------------------------------------------- |
+| **Project** | (default) | `./<agent>/skills/` | Committed with your project, shared with team |
+| **Global**  | `-g`      | `~/<agent>/skills/` | Available across all projects                 |
+
+### Installation Methods
+
+When installing interactively, you can choose:
+
+| Method                    | Description                                                                                 |
+| ------------------------- | ------------------------------------------------------------------------------------------- |
+| **Symlink** (Recommended) | Creates symlinks from each agent to a canonical copy. Single source of truth, easy updates. |
+| **Copy**                  | Creates independent copies for each agent. Use when symlinks aren't supported.              |
+
+## Other Commands
+
+| Command                      | Description                                             |
+| ---------------------------- | ------------------------------------------------------- |
+| `npx skills list`            | List installed skills (alias: `ls`)                     |
+| `npx skills find [query]`    | Search for skills interactively or by keyword           |
+| `npx skills remove [skills]` | Remove installed skills from agents                     |
+| `npx skills check`           | Check for available skill updates                       |
+| `npx skills update`          | Update all installed skills to latest versions          |
+| `npx skills init [name]`     | Create a new SKILL.md template                          |
+
+### `skills list`
+
+List all installed skills. Similar to `npm ls`.
 
 ```bash
-npx @mcp-s/skills --org mycompany --list
+# List all installed skills (project and global)
+npx skills list
+
+# List only global skills
+npx skills ls -g
+
+# Filter by specific agents
+npx skills ls -a claude-code -a cursor
 ```
 
-### Install specific skills
+### `skills find`
+
+Search for skills interactively or by keyword.
 
 ```bash
-npx @mcp-s/skills --org mycompany -s skill-1 skill-2
+# Interactive search (fzf-style)
+npx skills find
+
+# Search by keyword
+npx skills find typescript
 ```
 
-### Install to specific agents
+### `skills check` / `skills update`
 
 ```bash
-npx @mcp-s/skills --org mycompany -a cursor claude-code
+# Check if any installed skills have updates
+npx skills check
+
+# Update all skills to latest versions
+npx skills update
 ```
 
-### Install all skills globally without prompts
+### `skills init`
 
 ```bash
-npx @mcp-s/skills --org mycompany --all
+# Create SKILL.md in current directory
+npx skills init
+
+# Create a new skill in a subdirectory
+npx skills init my-skill
 ```
 
-### Using a custom base URL
+### `skills remove`
+
+Remove installed skills from agents.
 
 ```bash
-npx @mcp-s/skills --base-url https://custom.example.com/skills --list
+# Remove interactively (select from installed skills)
+npx skills remove
+
+# Remove specific skill by name
+npx skills remove web-design-guidelines
+
+# Remove multiple skills
+npx skills remove frontend-design web-design-guidelines
+
+# Remove from global scope
+npx skills remove --global web-design-guidelines
+
+# Remove from specific agents only
+npx skills remove --agent claude-code cursor my-skill
+
+# Remove all installed skills without confirmation
+npx skills remove --all
+
+# Remove all skills from a specific agent
+npx skills remove --skill '*' -a cursor
+
+# Remove a specific skill from all agents
+npx skills remove my-skill --agent '*'
+
+# Use 'rm' alias
+npx skills rm my-skill
 ```
 
+| Option              | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `-g, --global`      | Remove from global scope (~/) instead of project      |
+| `-a, --agent`       | Remove from specific agents (use `'*'` for all)      |
+| `-s, --skill`       | Specify skills to remove (use `'*'` for all)         |
+| `-y, --yes`         | Skip confirmation prompts                            |
+| `--all`             | Shorthand for `--skill '*' --agent '*' -y`           |
+
+## What are Agent Skills?
+
+Agent skills are reusable instruction sets that extend your coding agent's capabilities. They're defined in `SKILL.md`
+files with YAML frontmatter containing a `name` and `description`.
+
+Skills let agents perform specialized tasks like:
+
+- Generating release notes from git history
+- Creating PRs following your team's conventions
+- Integrating with external tools (Linear, Notion, etc.)
+
+Discover skills at **[skills.sh](https://skills.sh)**
+
 ## Supported Agents
 
-- Amp
-- Antigravity
-- Claude Code
-- Clawdbot
-- Cline
-- Codex
-- Command Code
-- Cursor
-- Droid
-- Gemini CLI
-- GitHub Copilot
-- Goose
-- Kilo Code
-- Kiro CLI
-- MCPJam
-- Neovate
-- OpenCode
-- OpenHands
-- Pi
-- Qoder
-- Qwen Code
-- Roo Code
-- Trae
-- Windsurf
-- Zencoder
-
-## Server API
-
-The skills library expects the server to implement the following endpoints:
-
-### POST /generate-auth-url
-
-Generates an authentication URL for the user.
-
-**Headers:**
-- `Authorization: <userAccessKey>:<userOTT>`
-
-**Response:**
-```json
-{
-  "data": {
-    "url": "https://..."
-  }
-}
+Skills can be installed to any of these agents:
+
+<!-- supported-agents:start -->
+| Agent | `--agent` | Project Path | Global Path |
+|-------|-----------|--------------|-------------|
+| Amp, Kimi Code CLI | `amp`, `kimi-cli` | `.agents/skills/` | `~/.config/agents/skills/` |
+| Antigravity | `antigravity` | `.agent/skills/` | `~/.gemini/antigravity/global_skills/` |
+| Augment | `augment` | `.augment/rules/` | `~/.augment/rules/` |
+| Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
+| OpenClaw | `openclaw` | `skills/` | `~/.moltbot/skills/` |
+| Cline | `cline` | `.cline/skills/` | `~/.cline/skills/` |
+| CodeBuddy | `codebuddy` | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
+| Codex | `codex` | `.codex/skills/` | `~/.codex/skills/` |
+| Command Code | `command-code` | `.commandcode/skills/` | `~/.commandcode/skills/` |
+| Continue | `continue` | `.continue/skills/` | `~/.continue/skills/` |
+| Crush | `crush` | `.crush/skills/` | `~/.config/crush/skills/` |
+| Cursor | `cursor` | `.cursor/skills/` | `~/.cursor/skills/` |
+| Droid | `droid` | `.factory/skills/` | `~/.factory/skills/` |
+| Gemini CLI | `gemini-cli` | `.gemini/skills/` | `~/.gemini/skills/` |
+| GitHub Copilot | `github-copilot` | `.github/skills/` | `~/.copilot/skills/` |
+| Goose | `goose` | `.goose/skills/` | `~/.config/goose/skills/` |
+| Junie | `junie` | `.junie/skills/` | `~/.junie/skills/` |
+| iFlow CLI | `iflow-cli` | `.iflow/skills/` | `~/.iflow/skills/` |
+| Kilo Code | `kilo` | `.kilocode/skills/` | `~/.kilocode/skills/` |
+| Kiro CLI | `kiro-cli` | `.kiro/skills/` | `~/.kiro/skills/` |
+| Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` |
+| MCPJam | `mcpjam` | `.mcpjam/skills/` | `~/.mcpjam/skills/` |
+| Mistral Vibe | `mistral-vibe` | `.vibe/skills/` | `~/.vibe/skills/` |
+| Mux | `mux` | `.mux/skills/` | `~/.mux/skills/` |
+| OpenCode | `opencode` | `.opencode/skills/` | `~/.config/opencode/skills/` |
+| OpenClaude IDE | `openclaude` | `.openclaude/skills/` | `~/.openclaude/skills/` |
+| OpenHands | `openhands` | `.openhands/skills/` | `~/.openhands/skills/` |
+| Pi | `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
+| Qoder | `qoder` | `.qoder/skills/` | `~/.qoder/skills/` |
+| Qwen Code | `qwen-code` | `.qwen/skills/` | `~/.qwen/skills/` |
+| Replit | `replit` | `.agent/skills/` | N/A (project-only) |
+| Roo Code | `roo` | `.roo/skills/` | `~/.roo/skills/` |
+| Trae | `trae` | `.trae/skills/` | `~/.trae/skills/` |
+| Trae CN | `trae-cn` | `.trae/skills/` | `~/.trae-cn/skills/` |
+| Windsurf | `windsurf` | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
+| Zencoder | `zencoder` | `.zencoder/skills/` | `~/.zencoder/skills/` |
+| Neovate | `neovate` | `.neovate/skills/` | `~/.neovate/skills/` |
+| Pochi | `pochi` | `.pochi/skills/` | `~/.pochi/skills/` |
+| AdaL | `adal` | `.adal/skills/` | `~/.adal/skills/` |
+<!-- supported-agents:end -->
+
+> [!NOTE]
+> **Kiro CLI users:** After installing skills, manually add them to your custom agent's `resources` in
+> `.kiro/agents/<agent>.json`:
+>
+> ```json
+> {
+>   "resources": ["skill://.kiro/skills/**/SKILL.md"]
+> }
+> ```
+
+The CLI automatically detects which coding agents you have installed. If none are detected, you'll be prompted to select
+which agents to install to.
+
+## Creating Skills
+
+Skills are directories containing a `SKILL.md` file with YAML frontmatter:
+
+```markdown
+---
+name: my-skill
+description: What this skill does and when to use it
+---
+
+# My Skill
+
+Instructions for the agent to follow when this skill is activated.
+
+## When to Use
+
+Describe the scenarios where this skill should be used.
+
+## Steps
+
+1. First, do this
+2. Then, do that
 ```
 
-### GET /skills
-
-Returns a list of available skills.
-
-**Headers:**
-- `Authorization: <userAccessKey>:<userOTT>`
-
-**Response:**
-```json
-{
-  "data": [
-    {
-      "name": "Skill Name",
-      "slug": "skill-slug",
-      "description": "Skill description",
-      "content": "# SKILL.md content...",
-      "category": "optional-category"
-    }
-  ]
-}
+### Required Fields
+
+- `name`: Unique identifier (lowercase, hyphens allowed)
+- `description`: Brief explanation of what the skill does
+
+### Optional Fields
+
+- `metadata.internal`: Set to `true` to hide the skill from normal discovery. Internal skills are only visible and
+  installable when `INSTALL_INTERNAL_SKILLS=1` is set. Useful for work-in-progress skills or skills meant only for
+  internal tooling.
+
+```markdown
+---
+name: my-internal-skill
+description: An internal skill not shown by default
+metadata:
+  internal: true
+---
+```
+
+### Skill Discovery
+
+The CLI searches for skills in these locations within a repository:
+
+<!-- skill-discovery:start -->
+- Root directory (if it contains `SKILL.md`)
+- `skills/`
+- `skills/.curated/`
+- `skills/.experimental/`
+- `skills/.system/`
+- `.agents/skills/`
+- `.agent/skills/`
+- `.augment/rules/`
+- `.claude/skills/`
+- `./skills/`
+- `.cline/skills/`
+- `.codebuddy/skills/`
+- `.codex/skills/`
+- `.commandcode/skills/`
+- `.continue/skills/`
+- `.crush/skills/`
+- `.cursor/skills/`
+- `.factory/skills/`
+- `.gemini/skills/`
+- `.github/skills/`
+- `.goose/skills/`
+- `.junie/skills/`
+- `.iflow/skills/`
+- `.kilocode/skills/`
+- `.kiro/skills/`
+- `.kode/skills/`
+- `.mcpjam/skills/`
+- `.vibe/skills/`
+- `.mux/skills/`
+- `.opencode/skills/`
+- `.openclaude/skills/`
+- `.openhands/skills/`
+- `.pi/skills/`
+- `.qoder/skills/`
+- `.qwen/skills/`
+- `.roo/skills/`
+- `.trae/skills/`
+- `.windsurf/skills/`
+- `.zencoder/skills/`
+- `.neovate/skills/`
+- `.pochi/skills/`
+- `.adal/skills/`
+<!-- skill-discovery:end -->
+
+If no skills are found in standard locations, a recursive search is performed.
+
+## Compatibility
+
+Skills are generally compatible across agents since they follow a
+shared [Agent Skills specification](https://agentskills.io). However, some features may be agent-specific:
+
+| Feature         | OpenCode | OpenHands | Claude Code | Cline | CodeBuddy | Codex | Command Code | Kiro CLI | Cursor | Antigravity | Roo Code | Github Copilot | Amp | Clawdbot | Neovate | Pi  | Qoder | Zencoder |
+| --------------- | -------- | --------- | ----------- | ----- | --------- | ----- | ------------ | -------- | ------ | ----------- | -------- | -------------- | --- | -------- | ------- | --- | ----- | -------- |
+| Basic skills    | Yes      | Yes       | Yes         | Yes   | Yes       | Yes   | Yes          | Yes      | Yes    | Yes         | Yes      | Yes            | Yes | Yes      | Yes     | Yes | Yes   | Yes      |
+| `allowed-tools` | Yes      | Yes       | Yes         | Yes   | Yes       | Yes   | Yes          | No       | Yes    | Yes         | Yes      | Yes            | Yes | Yes      | Yes     | Yes | Yes   | No       |
+| `context: fork` | No       | No        | Yes         | No    | No        | No    | No           | No       | No     | No          | No       | No             | No  | No       | No      | No  | No    | No       |
+| Hooks           | No       | No        | Yes         | Yes   | No        | No    | No           | No       | No     | No          | No       | No             | No  | No       | No      | No  | No    | No       |
+
+## Troubleshooting
+
+### "No skills found"
+
+Ensure the repository contains valid `SKILL.md` files with both `name` and `description` in the frontmatter.
+
+### Skill not loading in agent
+
+- Verify the skill was installed to the correct path
+- Check the agent's documentation for skill loading requirements
+- Ensure the `SKILL.md` frontmatter is valid YAML
+
+### Permission errors
+
+Ensure you have write access to the target directory.
+
+## Environment Variables
+
+| Variable                  | Description                                                                |
+| ------------------------- | -------------------------------------------------------------------------- |
+| `INSTALL_INTERNAL_SKILLS` | Set to `1` or `true` to show and install skills marked as `internal: true` |
+| `DISABLE_TELEMETRY`       | Set to disable anonymous usage telemetry                                   |
+| `DO_NOT_TRACK`            | Alternative way to disable telemetry                                       |
+
+```bash
+# Install internal skills
+INSTALL_INTERNAL_SKILLS=1 npx skills add vercel-labs/agent-skills --list
 ```
 
+## Telemetry
+
+This CLI collects anonymous usage data to help improve the tool. No personal information is collected.
+
+Telemetry is automatically disabled in CI environments.
+
+## Related Links
+
+- [Agent Skills Specification](https://agentskills.io)
+- [Skills Directory](https://skills.sh)
+- [Amp Skills Documentation](https://ampcode.com/manual#agent-skills)
+- [Antigravity Skills Documentation](https://antigravity.google/docs/skills)
+- [Factory AI / Droid Skills Documentation](https://docs.factory.ai/cli/configuration/skills)
+- [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)
+- [Clawdbot Skills Documentation](https://docs.clawd.bot/tools/skills)
+- [Cline Skills Documentation](https://docs.cline.bot/features/skills)
+- [CodeBuddy Skills Documentation](https://www.codebuddy.ai/docs/ide/Features/Skills)
+- [Codex Skills Documentation](https://developers.openai.com/codex/skills)
+- [Command Code Skills Documentation](https://commandcode.ai/docs/skills)
+- [Crush Skills Documentation](https://github.com/charmbracelet/crush?tab=readme-ov-file#agent-skills)
+- [Cursor Skills Documentation](https://cursor.com/docs/context/skills)
+- [Gemini CLI Skills Documentation](https://geminicli.com/docs/cli/skills/)
+- [GitHub Copilot Agent Skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)
+- [iFlow CLI Skills Documentation](https://platform.iflow.cn/en/cli/examples/skill)
+- [Kimi Code CLI Skills Documentation](https://moonshotai.github.io/kimi-cli/en/customization/skills.html)
+- [Kiro CLI Skills Documentation](https://kiro.dev/docs/cli/custom-agents/configuration-reference/#skill-resources)
+- [Kode Skills Documentation](https://github.com/shareAI-lab/kode/blob/main/docs/skills.md)
+- [OpenCode Skills Documentation](https://opencode.ai/docs/skills)
+- [Qwen Code Skills Documentation](https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/)
+- [OpenHands Skills Documentation](https://docs.openhands.ai/modules/usage/how-to/using-skills)
+- [Pi Skills Documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md)
+- [Qoder Skills Documentation](https://docs.qoder.com/cli/Skills)
+- [Replit Skills Documentation](https://docs.replit.com/replitai/skills)
+- [Roo Code Skills Documentation](https://docs.roocode.com/features/skills)
+- [Trae Skills Documentation](https://docs.trae.ai/ide/skills)
+- [Vercel Agent Skills Repository](https://github.com/vercel-labs/agent-skills)
+
 ## License
 
-ISC
+MIT