# playbooks

Install agent skills, MCPs and docs into your coding agents from any git repository.

Find skills to add at [playbooks.com](https://playbooks.com).

Works with **OpenCode**, **Claude Code**, **Codex**, **Cursor**, plus [many more](#available-agents).

## Quick start

Launch the interactive menu:
```bash
npx playbooks
```

Find skills in the playbooks directory (Enter = fast search, Tab = semantic):
```bash
npx playbooks find skill
```

Install skills directly from a repo:
```bash
npx playbooks add skill anthropics/skills
```

Install a single skill:
```bash
npx playbooks add skill anthropics/skills --skill frontend-design
```

Add curated documentation repos to `.agents/docs`:
```bash
npx playbooks add docs
```
The curated list lives in `data/docs-sources.yml` — PRs welcome.
## What are agent skills?

Agent skills are reusable instructions that teach your agent how to do things. It's a universal format that most AI coding tools now support, defined in a `SKILL.md` file with YAML frontmatter containing a `name` and `description`.

Skills let your 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.)

## Usage

playbooks uses an action/type command structure:
- `npx playbooks add skill <source>`
- `npx playbooks add docs`
- `npx playbooks find skill`
- `npx playbooks list skill`
- `npx playbooks manage skill`
- `npx playbooks update skill [skill-names...]`
- `npx playbooks update docs`
- `npx playbooks get <url> [out <path>]`

### Fetch a URL as markdown

```bash
# Output markdown to stdout
npx playbooks get https://example.com

# Save markdown to a file
npx playbooks get https://example.com out notes.md

# Output JSON metadata instead of raw markdown
npx playbooks get https://example.com --json
```

### Source formats

The `<source>` argument accepts multiple formats:

- GitHub shorthand
```bash
npx playbooks add skill anthropics/skills
```

- Full GitHub URL
```bash
npx playbooks add skill https://github.com/anthropics/skills
```

- Direct path to a skill in a repo
```bash
npx playbooks add skill https://github.com/anthropics/skills/tree/main/skills/release-notes
```

- GitLab URL
```bash
npx playbooks add skill https://gitlab.com/org/repo
```

- Any git URL
```bash
npx playbooks add skill git@github.com:anthropics/skills.git
```

- Direct SKILL.md URL
```bash
npx playbooks add skill https://docs.example.com/skills/my-skill/SKILL.md
```

- Docs URL (well-known skills discovery)
```bash
npx playbooks add skill https://mintlify.com/docs
npx playbooks add skill mintlify.com/docs
```

- Marketplace.json (path)
```bash
npx playbooks add skill ./path/to/.claude-plugin/marketplace.json
```

- Marketplace.json (URL)
```bash
npx playbooks add skill https://raw.githubusercontent.com/org/repo/main/.claude-plugin/marketplace.json
```

- Marketplace.json (owner/repo path)
```bash
npx playbooks add skill org/repo/.claude-plugin/marketplace.json
```

### Well-known skills discovery (RFC 8615)

If a docs site publishes a skills index at a predictable path, playbooks can discover and install skills from the site URL directly. The CLI looks for:

```text
https://example.com/docs/.well-known/skills/index.json
```

The index lists one or more skills and the files for each skill:

```json
{
  "skills": [
    {
      "name": "mintlify",
      "description": "Build and maintain documentation sites with Mintlify.",
      "files": ["SKILL.md"]
    }
  ]
}
```

When you run `npx playbooks add skill <docs-url>`, playbooks fetches the index and then downloads each skill from:

```text
https://example.com/docs/.well-known/skills/<skill-name>/SKILL.md
```

Multiple skills can be listed in the same index and will be shown in the selection screen.

### Options (add skill)

| 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                                                                                                                    |
| `-l, --list`              | List available skills without installing                                                                                                           |
| `-y, --yes`               | Skip all confirmation prompts                                                                                                                      |
| `-V, --version`           | Show version number                                                                                                                                |
| `-h, --help`              | Show help                                                                                                                                          |

### Examples

- List skills in a repository
```bash
npx playbooks add skill anthropics/skills --list
```

- Install multiple specific skills
```bash
npx playbooks add skill anthropics/skills --skill release-notes --skill incident-summary
```

- Install to specific agents
```bash
npx playbooks add skill anthropics/skills -a claude-code -a opencode
```

- Non-interactive installation (CI/CD friendly)
```bash
npx playbooks add skill anthropics/skills --skill release-notes -g -a claude-code -y
```

- Install all skills from a repo
```bash
npx playbooks add skill anthropics/skills -y -g
```

### Manage installed skills

- List installed skills (interactive)
```bash
npx playbooks list skill
```

- Update installed skills
```bash
npx playbooks update skill
```

- Remove skills (interactive)
```bash
npx playbooks manage skill
```

## Marketplace.json support

playbooks can ingest a Claude-style `marketplace.json` and pull skills from the plugins it lists.

What it scans:
- The plugin root (if it contains `SKILL.md`)
- Standard folders inside each plugin: `skills/`, `commands/`, `agents/`, `hooks/`
- Any explicit overrides in `marketplace.json` such as `skills`, `commands`, `agents`, `hooks`
- If nothing is found in the standard locations, it falls back to a recursive search

Example `marketplace.json` plugin entry (minimal):

```json
{
  "plugins": [
    {
      "name": "acme",
      "description": "Acme tools",
      "source": "plugins/acme"
    }
  ]
}
```

Example with overrides:

```json
{
  "plugins": [
    {
      "name": "acme",
      "source": "plugins/acme",
      "skills": "skills",
      "commands": "commands"
    }
  ]
}
```

## Available agents

Skills can be installed to any of these supported agents. Use `-g, --global` to install to the global path instead of project-level.

> [!TIP]
> **Universal agents** — Many agents now converge on `.agents/skills/` as a shared directory. Skills installed there are automatically available to Amp, Codex, Droid, Gemini CLI, GitHub Copilot, Kimi Code CLI, OpenCode, and Replit. When you install a skill, playbooks writes it once to `.agents/skills/` and symlinks it to any non-universal agents you've selected.

<!-- available-agents:start -->
| Agent | `--agent` | Project Path | Global Path |
|-------|-----------|--------------|-------------|
| AdaL | `adal` | `.adal/skills/` | `~/.adal/skills/` |
| Amp | `amp` | `.agents/skills/` | `~/.agents/skills/` |
| Antigravity | `antigravity` | `.agent/skills/` | `~/.gemini/antigravity/skills/` |
| Augment | `augment` | `.augment/rules/` | `~/.augment/rules/` |
| Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
| Cline | `cline` | `.cline/skills/` | `~/.cline/skills/` |
| CodeBuddy | `codebuddy` | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
| Codex | `codex` | `.agents/skills/` | `~/.agents/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` | `.agents/skills/` | `~/.agents/skills/` |
| Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.agents/skills/` |
| GitHub Copilot | `github-copilot` | `.agents/skills/` | `~/.agents/skills/` |
| Goose | `goose` | `.goose/skills/` | `~/.config/goose/skills/` |
| iFlow CLI | `iflow-cli` | `.iflow/skills/` | `~/.iflow/skills/` |
| Junie | `junie` | `.junie/skills/` | `~/.junie/skills/` |
| Kilo Code | `kilo` | `.kilocode/skills/` | `~/.kilocode/skills/` |
| Kimi Code CLI | `kimi-cli` | `.agents/skills/` | `~/.agents/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/` |
| Neovate | `neovate` | `.neovate/skills/` | `~/.neovate/skills/` |
| OpenClaw | `openclaw` | `skills/` | `~/.openclaw/skills/` |
| OpenCode | `opencode` | `.agents/skills/` | `~/.agents/skills/` |
| OpenHands | `openhands` | `.openhands/skills/` | `~/.openhands/skills/` |
| Pi | `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
| Pochi | `pochi` | `.pochi/skills/` | `~/.pochi/skills/` |
| Qoder | `qoder` | `.qoder/skills/` | `~/.qoder/skills/` |
| Qwen Code | `qwen-code` | `.qwen/skills/` | `~/.qwen/skills/` |
| Replit | `replit` | `.agents/skills/` | *(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/` |
| Universal | `universal` | `.agents/skills/` | `~/.agents/skills/` |
<!-- available-agents:end -->

> [!NOTE]
> **Kiro CLI users:** After installing skills, you need to manually add them to your custom agent's `resources` in `.kiro/agents/<agent>.json`:
>
> ```json
> {
>   "resources": ["skill://.kiro/skills/**/SKILL.md"]
> }
> ```

## Agent detection

The CLI automatically detects which coding agents you have installed by checking for their configuration directories. 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

### 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/`
- `.adal/skills/`
- `.agents/skills/`
- `.agent/skills/`
- `.augment/rules/`
- `.claude/skills/`
- `.cline/skills/`
- `.codebuddy/skills/`
- `.commandcode/skills/`
- `.continue/skills/`
- `.cortex/skills/`
- `.crush/skills/`
- `.goose/skills/`
- `.iflow/skills/`
- `.junie/skills/`
- `.kilocode/skills/`
- `.kiro/skills/`
- `.kode/skills/`
- `.mcpjam/skills/`
- `.vibe/skills/`
- `.mux/skills/`
- `.neovate/skills/`
- `./skills/`
- `.openhands/skills/`
- `.pi/skills/`
- `.pochi/skills/`
- `.qoder/skills/`
- `.qwen/skills/`
- `.roo/skills/`
- `.trae/skills/`
- `.windsurf/skills/`
- `.zencoder/skills/`
<!-- skill-discovery:end -->

If no skills are found in standard locations, a recursive search is performed.

## Compatibility

## Linting

This repo uses Biome plus a max‑file‑length guard.

```bash
npm run lint      # Biome check + max 400 lines per file
npm run lint:fix  # Biome auto-fix
```

If you see a warning about Biome’s install script being skipped, run:

```bash
npm approve-builds
```

Skills are generally compatible across agents since they follow a shared [Agent Skills specification](https://agentskills.io). However, some features may be agent-specific:

<!-- compatibility-table:start -->
| Agent | Basic Skills | `allowed-tools` | `context: fork` | Hooks |
|-------|:------------:|:---------------:|:---------------:|:-----:|
| AdaL | ✓ | ✓ | | |
| Amp | ✓ | ✓ | | |
| Antigravity | ✓ | ✓ | | |
| Augment | ✓ | ✓ | | |
| Claude Code | ✓ | ✓ | ✓ | ✓ |
| Cline | ✓ | ✓ | | ✓ |
| CodeBuddy | ✓ | ✓ | | |
| Codex | ✓ | ✓ | | |
| Command Code | ✓ | ✓ | | |
| Continue | ✓ | ✓ | | |
| Crush | ✓ | ✓ | | |
| Cursor | ✓ | ✓ | | |
| Droid | ✓ | ✓ | | ✓ |
| Gemini CLI | ✓ | ✓ | | |
| GitHub Copilot | ✓ | ✓ | | |
| Goose | ✓ | ✓ | | |
| iFlow CLI | ✓ | ✓ | | |
| Junie | ✓ | ✓ | | |
| Kilo Code | ✓ | ✓ | | |
| Kimi Code CLI | ✓ | ✓ | | |
| Kiro CLI | ✓ | | | |
| Kode | ✓ | ✓ | | |
| MCPJam | ✓ | ✓ | | |
| Mistral Vibe | ✓ | ✓ | | |
| Mux | ✓ | ✓ | | |
| Neovate | ✓ | ✓ | | |
| OpenClaw | ✓ | ✓ | | |
| OpenCode | ✓ | ✓ | | |
| OpenHands | ✓ | ✓ | | |
| Pi | ✓ | ✓ | | |
| Pochi | ✓ | ✓ | | |
| Qoder | ✓ | ✓ | | |
| Qwen Code | ✓ | ✓ | | |
| Replit | ✓ | ✓ | | |
| Roo Code | ✓ | ✓ | | |
| Trae | ✓ | ✓ | | |
| Trae CN | ✓ | ✓ | | |
| Windsurf | ✓ | ✓ | | |
| Zencoder | ✓ | | | |
<!-- compatibility-table:end -->

## 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.

## Telemetry

This CLI collects anonymous usage data to help improve the tool. No personal information is collected.

To disable telemetry, set any of these environment variables:

```bash
DISABLE_TELEMETRY=1 npx playbooks add skill anthropics/skills
# or
DO_NOT_TRACK=1 npx playbooks add skill anthropics/skills
# or
PLAYBOOKS_DISABLE_TELEMETRY=1 npx playbooks add skill anthropics/skills
```

Telemetry is also automatically disabled in CI environments.

## Related links

- [Agent Skills Specification](https://agentskills.io)
- [Amp Skills Documentation](https://ampcode.com/manual#agent-skills)
- [Antigravity Skills Documentation](https://antigravity.google/docs/skills)
- [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)
- [Cline Skills Documentation](https://docs.cline.bot/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)
- [Kiro CLI Skills Documentation](https://kiro.dev/docs/cli/custom-agents/configuration-reference/#skill-resources)
- [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)
- [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