@bud-fe/skills 0.0.1

package/README.md

@@ -0,0 +1,563 @@
+# skills-x
+
+The CLI for the open agent skills, commands ecosystem.
+
+Forked from [vercel-labs/skills](https://github.com/vercel-labs/skills), **recent spec changes**:
+
+- `skills add` now supports implicit default-registry source resolution when flags are provided without a source (for example `--list` and `--all`).
+- `skills add` maps simple identifiers (for example `code-review`) to the curated default registry, while explicit sources (`owner/repo`, URLs, local paths) keep their existing behavior.
+- `skills add-c` installs command markdown files from the default registry `commands/` directory by command name.
+- `skills find` is provider-scoped:
+  - default mode searches the curated registry
+  - `-g` / `--global` searches [skills.sh](https://skills.sh)
+  - the CLI does not silently fall back to another provider if the selected provider fails
+
+---
+
+<!-- agent-list:start -->
+
+Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [37 more](#available-agents).
+
+<!-- agent-list:end -->
+
+## Install a Skill
+
+```bash
+# Install a curated skill by name
+npx @bud-fe/skills add code-review
+
+# Install from a specific repository
+npx @bud-fe/skills add vercel-labs/agent-skills
+```
+
+### Source Formats
+
+```bash
+# Curated skill name (from default registry)
+npx @bud-fe/skills add code-review
+
+# GitHub shorthand (owner/repo)
+npx @bud-fe/skills add vercel-labs/agent-skills
+
+# Full GitHub URL
+npx @bud-fe/skills add https://github.com/vercel-labs/agent-skills
+
+# Direct path to a skill in a repo
+npx @bud-fe/skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
+
+# GitLab URL
+npx @bud-fe/skills add https://gitlab.com/org/repo
+
+# Any git URL
+npx @bud-fe/skills add git@github.com:vercel-labs/agent-skills.git
+
+# Local path
+npx @bud-fe/skills add ./my-local-skills
+```
+
+### Source Resolution Rules
+
+- Simple identifier input (letters, numbers, hyphens only) resolves to the curated default registry:
+  - `npx @bud-fe/skills add code-review`
+- Explicit sources are always preserved (no default-registry remap):
+  - `owner/repo`
+  - full URLs
+  - local paths
+- No source + options uses the default registry:
+  - `npx @bud-fe/skills add --list`
+  - `npx @bud-fe/skills add --all`
+- No source + no options returns an error:
+  - `npx @bud-fe/skills add`
+
+### Options
+
+| 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 [Available Agents](#available-agents)<!-- agent-names:end --> |
+| `-s, --skill <skills...>` | Install specific skills by name (use `'*'` for all skills)                                                                                         |
+| `-l, --list`              | List available skills without installing                                                                                                           |
+| `--copy`                  | Copy files instead of symlinking to agent directories                                                                                              |
+| `-y, --yes`               | Skip all confirmation prompts                                                                                                                      |
+| `--all`                   | Install all skills to all agents without prompts (defaults to curated registry if no source provided)                                              |
+
+### Examples
+
+```bash
+# List all skills in the default curated registry
+npx @bud-fe/skills add --list
+
+# List skills in a specific repository
+npx @bud-fe/skills add vercel-labs/agent-skills --list
+
+# Install a curated skill
+npx @bud-fe/skills add code-review
+
+# Install specific skills from a repo
+npx @bud-fe/skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator
+
+# Install a skill with spaces in the name (must be quoted)
+npx @bud-fe/skills add owner/repo --skill "Convex Best Practices"
+
+# Install to specific agents
+npx @bud-fe/skills add vercel-labs/agent-skills -a claude-code -a opencode
+
+# Non-interactive installation (CI/CD friendly)
+npx @bud-fe/skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y
+
+# Install all skills from a repo to all agents
+npx @bud-fe/skills add vercel-labs/agent-skills --all
+
+# Install all skills to specific agents
+npx @bud-fe/skills add vercel-labs/agent-skills --skill '*' -a claude-code
+
+# Install specific skills to all agents
+npx @bud-fe/skills add vercel-labs/agent-skills --agent '*' --skill frontend-design
+
+# Install all curated skills to all agents
+npx @bud-fe/skills add --all
+
+# Install all skills from a repo to all agents
+npx @bud-fe/skills add vercel-labs/agent-skills --all
+```
+
+### 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 @bud-fe/skills add-c [command]` | Install command files from default registry                     |
+| `npx @bud-fe/skills list`            | List installed skills (alias: `ls`)                             |
+| `npx @bud-fe/skills find [query]`    | Search curated registry by default (`-g` for global API search) |
+| `npx @bud-fe/skills remove [skills]` | Remove installed skills from agents                             |
+| `npx @bud-fe/skills check`           | Check for available skill updates                               |
+| `npx @bud-fe/skills update`          | Update all installed skills to latest versions                  |
+| `npx @bud-fe/skills init [name]`     | Create a new SKILL.md template                                  |
+
+### `skills list`
+
+List all installed skills. Similar to `npm ls`.
+
+```bash
+# List all installed skills (project and global)
+npx @bud-fe/skills list
+
+# List only global skills
+npx @bud-fe/skills ls -g
+
+# Filter by specific agents
+npx @bud-fe/skills ls -a claude-code -a cursor
+```
+
+### `skills add-c`
+
+Install command markdown files from the default registry `commands/` directory.
+
+`add-c` only accepts command names (not repository URLs, `owner/repo`, or local paths).
+
+- Command discovery is filename-based from `commands/**/*.md` (command name = filename without `.md`).
+- `--list` shows command descriptions from YAML frontmatter when a `description` field is present.
+- Commands are installed as `<name>.md` files into each selected agent's command/workflow path.
+- Interactive agent selection for `add-c` only includes command-capable agents.
+
+```bash
+# Install one command by name
+npx @bud-fe/skills add-c my-command
+
+# Install specific commands
+npx @bud-fe/skills add-c -c my-command -c another-command
+
+# List available commands
+npx @bud-fe/skills add-c --list
+
+# Install all commands to all supported agents without prompts
+npx @bud-fe/skills add-c --all
+
+# Install globally
+npx @bud-fe/skills add-c my-command --global
+```
+
+| Option                     | Description                                                          |
+| -------------------------- | -------------------------------------------------------------------- |
+| `-g, --global`             | Install to user directory instead of project                         |
+| `-a, --agent <agents...>`  | Install to specific command-capable agents (`'*'` for all supported) |
+| `-c, --command <names...>` | Install specific commands by name (`'*'` for all commands)           |
+| `-l, --list`               | List available commands without installing                           |
+| `-y, --yes`                | Skip confirmation prompts                                            |
+| `--all`                    | Shorthand for `--command '*' --agent '*' -y`                         |
+
+Supported command-capable agents:
+
+| Agent       | `--agent`     | Project Path             | Global Path                    |
+| ----------- | ------------- | ------------------------ | ------------------------------ |
+| Claude Code | `claude-code` | `.claude/commands/`      | `~/.claude/commands/`          |
+| OpenCode    | `opencode`    | `.opencode/commands/`    | `~/.opencode/commands/`        |
+| Cline       | `cline`       | `.clinerules/workflows/` | `~/Documents/Cline/Workflows/` |
+| Kilo Code   | `kilo`        | `.kilocode/workflows/`   | `~/.kilocode/workflows/`       |
+
+### `skills find`
+
+Search for skills by provider mode:
+
+- default mode (`npx @bud-fe/skills find ...`) searches the curated default registry
+- global mode (`npx @bud-fe/skills find -g ...`) searches `https://skills.sh`
+- default registry matching is case-insensitive substring matching on skill names
+- default-registry results include:
+  - install hint: `npx @bud-fe/skills add <name>`
+  - link to the skill directory in the default registry repository
+- results are scoped to the active provider only (no implicit cross-provider fallback)
+
+```bash
+# Interactive search in default registry (fzf-style)
+npx @bud-fe/skills find
+
+# Search default registry by keyword
+npx @bud-fe/skills find typescript
+
+# Search globally on skills.sh API
+npx @bud-fe/skills find -g typescript
+```
+
+### `skills check` / `skills update`
+
+```bash
+# Check if any installed skills have updates
+npx @bud-fe/skills check
+
+# Update all skills to latest versions
+npx @bud-fe/skills update
+```
+
+### `skills init`
+
+```bash
+# Create SKILL.md in current directory
+npx @bud-fe/skills init
+
+# Create a new skill in a subdirectory
+npx @bud-fe/skills init my-skill
+```
+
+### `skills remove`
+
+Remove installed skills from agents.
+
+```bash
+# Remove interactively (select from installed skills)
+npx @bud-fe/skills remove
+
+# Remove specific skill by name
+npx @bud-fe/skills remove web-design-guidelines
+
+# Remove multiple skills
+npx @bud-fe/skills remove frontend-design web-design-guidelines
+
+# Remove from global scope
+npx @bud-fe/skills remove --global web-design-guidelines
+
+# Remove from specific agents only
+npx @bud-fe/skills remove --agent claude-code cursor my-skill
+
+# Remove all installed skills without confirmation
+npx @bud-fe/skills remove --all
+
+# Remove all skills from a specific agent
+npx @bud-fe/skills remove --skill '*' -a cursor
+
+# Remove a specific skill from all agents
+npx @bud-fe/skills remove my-skill --agent '*'
+
+# Use 'rm' alias
+npx @bud-fe/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
+
+Skills can be installed to any of these agents:
+
+<!-- supported-agents:start -->
+
+| Agent                                 | `--agent`                                | Project Path           | Global Path                     |
+| ------------------------------------- | ---------------------------------------- | ---------------------- | ------------------------------- |
+| Amp, Kimi Code CLI, Replit, Universal | `amp`, `kimi-cli`, `replit`, `universal` | `.agents/skills/`      | `~/.config/agents/skills/`      |
+| Antigravity                           | `antigravity`                            | `.agent/skills/`       | `~/.gemini/antigravity/skills/` |
+| Augment                               | `augment`                                | `.augment/skills/`     | `~/.augment/skills/`            |
+| Claude Code                           | `claude-code`                            | `.claude/skills/`      | `~/.claude/skills/`             |
+| OpenClaw                              | `openclaw`                               | `skills/`              | `~/.openclaw/skills/`           |
+| Cline                                 | `cline`                                  | `.cline/skills/`       | `~/.cline/skills/`              |
+| CodeBuddy                             | `codebuddy`                              | `.codebuddy/skills/`   | `~/.codebuddy/skills/`          |
+| Codex                                 | `codex`                                  | `.agents/skills/`      | `~/.codex/skills/`              |
+| Command Code                          | `command-code`                           | `.commandcode/skills/` | `~/.commandcode/skills/`        |
+| Continue                              | `continue`                               | `.continue/skills/`    | `~/.continue/skills/`           |
+| Cortex Code                           | `cortex`                                 | `.cortex/skills/`      | `~/.snowflake/cortex/skills/`   |
+| Crush                                 | `crush`                                  | `.crush/skills/`       | `~/.config/crush/skills/`       |
+| Cursor                                | `cursor`                                 | `.agents/skills/`      | `~/.cursor/skills/`             |
+| Droid                                 | `droid`                                  | `.factory/skills/`     | `~/.factory/skills/`            |
+| Gemini CLI                            | `gemini-cli`                             | `.agents/skills/`      | `~/.gemini/skills/`             |
+| GitHub Copilot                        | `github-copilot`                         | `.agents/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`                               | `.agents/skills/`      | `~/.config/opencode/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/`               |
+| 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
+```
+
+### 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/skills/`
+- `.claude/skills/`
+- `./skills/`
+- `.cline/skills/`
+- `.codebuddy/skills/`
+- `.commandcode/skills/`
+- `.continue/skills/`
+- `.cortex/skills/`
+- `.crush/skills/`
+- `.factory/skills/`
+- `.goose/skills/`
+- `.junie/skills/`
+- `.iflow/skills/`
+- `.kilocode/skills/`
+- `.kiro/skills/`
+- `.kode/skills/`
+- `.mcpjam/skills/`
+- `.vibe/skills/`
+- `.mux/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 -->
+
+### Plugin Manifest Discovery
+
+If `.claude-plugin/marketplace.json` or `.claude-plugin/plugin.json` exists, skills declared in those files are also discovered:
+
+```json
+// .claude-plugin/marketplace.json
+{
+  "metadata": { "pluginRoot": "./plugins" },
+  "plugins": [
+    {
+      "name": "my-plugin",
+      "source": "my-plugin",
+      "skills": ["./skills/review", "./skills/test"]
+    }
+  ]
+}
+```
+
+This enables compatibility with the [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) ecosystem.
+
+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 | OpenClaw | 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 @bud-fe/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)
+- [OpenClaw Skills Documentation](https://docs.openclaw.ai/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
+
+MIT