@voidagency/skills 1.0.0

package/README.md

@@ -0,0 +1,502 @@
+# skills
+
+The CLI for the open agent skills ecosystem.
+
+<!-- agent-list:start -->
+Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [37 more](#available-agents).
+<!-- agent-list:end -->
+
+## Install a Skill
+
+```bash
+npx @voidagency/skills add vercel-labs/agent-skills
+```
+
+### Source Formats
+
+```bash
+# GitHub shorthand (owner/repo)
+npx @voidagency/skills add vercel-labs/agent-skills
+
+# Full GitHub URL
+npx @voidagency/skills add https://github.com/vercel-labs/agent-skills
+
+# Direct path to a skill in a repo
+npx @voidagency/skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
+
+# GitLab URL
+npx @voidagency/skills add https://gitlab.com/org/repo
+
+# Any git URL
+npx @voidagency/skills add git@github.com:vercel-labs/agent-skills.git
+
+# Local path
+npx @voidagency/skills add ./my-local-skills
+```
+
+### 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                                                                                                   |
+
+### Examples
+
+```bash
+# List skills in a repository
+npx @voidagency/skills add vercel-labs/agent-skills --list
+
+# Install specific skills
+npx @voidagency/skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator
+
+# Install a skill with spaces in the name (must be quoted)
+npx @voidagency/skills add owner/repo --skill "Convex Best Practices"
+
+# Install to specific agents
+npx @voidagency/skills add vercel-labs/agent-skills -a claude-code -a opencode
+
+# Non-interactive installation (CI/CD friendly)
+npx @voidagency/skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y
+
+# Install all skills from a repo to all agents
+npx @voidagency/skills add vercel-labs/agent-skills --all
+
+# Install all skills to specific agents
+npx @voidagency/skills add vercel-labs/agent-skills --skill '*' -a claude-code
+
+# Install specific skills to all agents
+npx @voidagency/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 @voidagency/skills list`            | List installed skills (alias: `ls`)            |
+| `npx @voidagency/skills find [query]`    | Search for skills interactively or by keyword  |
+| `npx @voidagency/skills remove [skills]` | Remove installed skills from agents            |
+| `npx @voidagency/skills check`           | Check for available skill updates              |
+| `npx @voidagency/skills update`          | Update all installed skills to latest versions |
+| `npx @voidagency/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 @voidagency/skills list
+
+# List only global skills
+npx @voidagency/skills ls -g
+
+# Filter by specific agents
+npx @voidagency/skills ls -a claude-code -a cursor
+```
+
+### `skills find`
+
+Search for skills interactively or by keyword.
+
+```bash
+# Interactive search (fzf-style)
+npx @voidagency/skills find
+
+# Search by keyword
+npx @voidagency/skills find typescript
+```
+
+### `skills check` / `skills update`
+
+```bash
+# Check if any installed skills have updates
+npx @voidagency/skills check
+
+# Update all skills to latest versions
+npx @voidagency/skills update
+```
+
+### `skills init`
+
+```bash
+# Create SKILL.md in current directory
+npx @voidagency/skills init
+
+# Create a new skill in a subdirectory
+npx @voidagency/skills init my-skill
+```
+
+### `skills remove`
+
+Remove installed skills from agents.
+
+```bash
+# Remove interactively (select from installed skills)
+npx @voidagency/skills remove
+
+# Remove specific skill by name
+npx @voidagency/skills remove web-design-guidelines
+
+# Remove multiple skills
+npx @voidagency/skills remove frontend-design web-design-guidelines
+
+# Remove from global scope
+npx @voidagency/skills remove --global web-design-guidelines
+
+# Remove from specific agents only
+npx @voidagency/skills remove --agent claude-code cursor my-skill
+
+# Remove all installed skills without confirmation
+npx @voidagency/skills remove --all
+
+# Remove all skills from a specific agent
+npx @voidagency/skills remove --skill '*' -a cursor
+
+# Remove a specific skill from all agents
+npx @voidagency/skills remove my-skill --agent '*'
+
+# Use 'rm' alias
+npx @voidagency/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 your skills directory (or set SKILLS_API_URL for search)
+
+## 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` | `.agents/skills/` | `~/.agents/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/`
+- `.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 @voidagency/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.
+
+## Build & Publish to npm
+
+The CLI is published as `@voidagency/skills` on npm. Source: [Bitbucket — adminvoid/void-skills](https://bitbucket.org/adminvoid/void-skills).
+
+### Prerequisites
+
+- Node.js ≥ 18
+- npm account with access to the `@voidagency` scope
+- Logged in: `npm login`
+
+### Build
+
+From the **monorepo root**:
+
+```bash
+yarn install
+yarn workspace @voidagency/skills build
+```
+
+Or from the CLI package:
+
+```bash
+cd packages/cli
+npm install
+npm run build
+```
+
+The build outputs to `packages/cli/dist` and runs the license generator. `prepublishOnly` runs the build automatically before `npm publish`.
+
+### Publish
+
+1. **Bump version** in `packages/cli/package.json` (e.g. `1.4.4` → `1.4.5` or `1.5.0`).
+2. **Build** (see above).
+3. **Dry run** (optional): `cd packages/cli && npm publish --dry-run` to see what would be uploaded.
+4. **Publish**:
+   ```bash
+   cd packages/cli
+   npm publish
+   ```
+   For a prerelease tag (e.g. `snapshot`): `npm run publish:snapshot` (bumps a prerelease version and publishes with `--tag snapshot`).
+
+Scoped packages (`@voidagency/skills`) use `"publishConfig": { "access": "public" }` so the package is public on npm.
+
+### Troubleshooting
+
+- **404 Not Found on publish** — The `@voidagency` scope must exist on npm and you must have permission to publish under it. Create the organization at [npm — Create Organization](https://www.npmjs.com/org/create) (name: `voidagency`), or get added as a member if it already exists. Until then, npm will return 404 for `PUT @voidagency/skills`.
+- **"bin script name was cleaned"** — Run `npm pkg fix` in `packages/cli` to let npm correct any package.json issues it reported.
+
+## Related Links
+
+- [Agent Skills Specification](https://agentskills.io)
+- Skills directory (configure via SKILLS_API_URL)
+- [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

package/ThirdPartyNoticeText.txt

@@ -0,0 +1,12 @@
+/*!----------------- Skills CLI ThirdPartyNotices -------------------------------------------------------
+
+The Skills CLI incorporates third party material from the projects listed below.
+The original copyright notice and the license under which this material was received
+are set forth below. These licenses and notices are provided for informational purposes only.
+
+---------------------------------------------
+Third Party Code Components
+--------------------------------------------
+
+================================================================================
+*/

package/bin/cli.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import module from 'node:module';
+
+// https://nodejs.org/api/module.html#module-compile-cache
+if (module.enableCompileCache && !process.env.NODE_DISABLE_COMPILE_CACHE) {
+  try {
+    module.enableCompileCache();
+  } catch {
+    // Ignore errors
+  }
+}
+
+await import('../dist/cli.mjs');