playbooks

v0.1.10

Published

15 hours ago

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

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

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 find skill
npx playbooks list skill
npx playbooks manage skill
npx playbooks update skill [skill-names...]
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 [email protected]: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)

| Option | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | -g, --global | Install to user directory instead of project | | -a, --agent <agents...> | Target specific agents (e.g., claude-code, codex). See Available Agents | | -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

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.

| Agent | --agent | Project Path | Global Path | |-------|-----------|--------------|-------------| | AdaL | adal | .adal/skills/ | ~/.adal/skills/ | | Amp | amp | .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/ | | Clawdbot | clawdbot | skills/ | ~/.clawdbot/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/ | | 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/ | ~/.config/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/ | | OpenClaude IDE | openclaude | .openclaude/skills/ | ~/.openclaude/skills/ | | OpenClaw | openclaw | skills/ | ~/.openclaw/skills/ | | OpenCode | opencode | .opencode/skills/ | ~/.config/opencode/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 | .agent/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/ |

[!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/
.agent/skills/
.agents/skills/
.augment/rules/
.claude/skills/
.cline/skills/
.codebuddy/skills/
.codex/skills/
.commandcode/skills/
.continue/skills/
.crush/skills/
.cursor/skills/
.factory/skills/
.gemini/skills/
.github/skills/
.goose/skills/
.iflow/skills/
.junie/skills/
.kilocode/skills/
.kiro/skills/
.kode/skills/
.mcpjam/skills/
.mux/skills/
.neovate/skills/
.openclaude/skills/
.opencode/skills/
.openhands/skills/
.pi/skills/
.pochi/skills/
.qoder/skills/
.qwen/skills/
.roo/skills/
.trae/skills/
.vibe/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:

| Agent | Basic Skills | allowed-tools | context: fork | Hooks | |-------|:------------:|:---------------:|:---------------:|:-----:| | AdaL | ✓ | ✓ | | | | Amp | ✓ | ✓ | | | | Antigravity | ✓ | ✓ | | | | Augment | ✓ | ✓ | | | | Claude Code | ✓ | ✓ | ✓ | ✓ | | Clawdbot | ✓ | ✓ | | | | 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 | ✓ | ✓ | | | | OpenClaude IDE | ✓ | ✓ | | | | OpenClaw | ✓ | ✓ | | | | OpenCode | ✓ | ✓ | | | | OpenHands | ✓ | ✓ | | | | Pi | ✓ | ✓ | | | | Pochi | ✓ | ✓ | | | | Qoder | ✓ | ✓ | | | | Qwen Code | ✓ | ✓ | | | | Replit | ✓ | ✓ | | | | Roo Code | ✓ | ✓ | | | | Trae | ✓ | ✓ | | | | Trae CN | ✓ | ✓ | | | | Windsurf | ✓ | ✓ | | | | Zencoder | ✓ | | | |

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.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

playbooks

Quick start

What are agent skills?

Usage

Fetch a URL as markdown

Source formats

Well-known skills discovery (RFC 8615)

Options (add skill)

Examples

Manage installed skills

Marketplace.json support

Available agents

Agent detection

Creating skills

Required fields

Skill discovery

Compatibility

Linting

Troubleshooting

"No skills found"

Skill not loading in agent

Permission errors

Telemetry

Related links

License