playbooks

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

Find skills to add at playbooks.com.

Works with OpenCode, Claude Code, Codex, Cursor, plus many more.

Quick start

Launch the interactive menu:

npx playbooks

Find skills in the playbooks directory (Enter = fast search, Tab = semantic):

npx playbooks find skill

Install skills directly from a repo:

npx playbooks add skill anthropics/skills

Install a single skill:

npx playbooks add skill anthropics/skills --skill frontend-design

Add curated documentation repos to .agents/docs:

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

# 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

npx playbooks add skill anthropics/skills

• Full GitHub URL

npx playbooks add skill https://github.com/anthropics/skills

• Direct path to a skill in a repo

npx playbooks add skill https://github.com/anthropics/skills/tree/main/skills/release-notes

• GitLab URL

npx playbooks add skill https://gitlab.com/org/repo

• Any git URL

npx playbooks add skill git@github.com:anthropics/skills.git

• Direct SKILL.md URL

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

• Docs URL (well-known skills discovery)

npx playbooks add skill https://mintlify.com/docs
npx playbooks add skill mintlify.com/docs

• Marketplace.json (path)

npx playbooks add skill ./path/to/.claude-plugin/marketplace.json

• Marketplace.json (URL)

npx playbooks add skill https://raw.githubusercontent.com/org/repo/main/.claude-plugin/marketplace.json

• Marketplace.json (owner/repo path)

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:

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

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

{
  "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:

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)

Examples

• List skills in a repository

npx playbooks add skill anthropics/skills --list

• Install multiple specific skills

npx playbooks add skill anthropics/skills --skill release-notes --skill incident-summary

• Install to specific agents

npx playbooks add skill anthropics/skills -a claude-code -a opencode

• Non-interactive installation (CI/CD friendly)

npx playbooks add skill anthropics/skills --skill release-notes -g -a claude-code -y

• Install all skills from a repo

npx playbooks add skill anthropics/skills -y -g

Manage installed skills

• List installed skills (interactive)

npx playbooks list skill

• Update installed skills

npx playbooks update skill

• Remove skills (interactive)

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):

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

Example with overrides:

{
  "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.

[!NOTE] Kiro CLI users: After installing skills, you need to manually add them to your custom agent's resources in .kiro/agents/<agent>.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:

---
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:

• 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/
• .crush/skills/
• .cursor/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/

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.

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:

npm approve-builds

Skills are generally compatible across agents since they follow a shared Agent Skills specification. However, some features may be agent-specific:

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:

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
• Amp Skills Documentation
• Antigravity Skills Documentation
• Claude Code Skills Documentation
• Cline Skills Documentation
• Codex Skills Documentation
• Command Code Skills Documentation
• Crush Skills Documentation
• Cursor Skills Documentation
• Gemini CLI Skills Documentation
• GitHub Copilot Agent Skills
• Kiro CLI Skills Documentation
• OpenCode Skills Documentation
• Qwen Code Skills Documentation
• OpenHands Skills Documentation
• Pi Skills Documentation
• Qoder Skills Documentation
• Roo Code Skills Documentation
• Trae Skills Documentation
• Vercel Agent Skills Repository

License

MIT