Agent Playbook

A collection of practical guides, prompts, and skills for AI Agents (Claude Code)

English | 简体中文

Overview

This repository collects practical, public-facing building blocks for AI agents: reusable skills, prompt patterns, workflow docs, and tooling for Claude Code, Codex, and Gemini.

Everything in this repository is intended to stay portable and abstract. Private operating details, company-specific workflows, and sensitive business context should live elsewhere.

What you get

• Reusable skills with focused SKILL.md files and deeper references/ material
• Installation and lifecycle tooling through @codeharbor/agent-playbook
• An MCP server for skill discovery
• Workflow docs for planning, self-improvement, automation, and context design

Design Principles

The repository is evolving around a few portable agent design rules:

• Keep hard constraints always-on, but keep them short
• Turn reusable methods into skills
• Keep detailed facts and examples retrievable from references and docs
• Persist long-running task state outside chat so recovery is reliable

Further reading:

• Context Layering for Agent Playbooks
• Skill Ecosystem References
• long-task-coordinator

Who this is for

• Builders creating their own reusable agent skills
• Teams standardizing how agents plan, review, and recover work
• Power users who want local-first tooling instead of SaaS-heavy orchestration

Installation

Method 0: One-Command Installer (PNPM/NPM)

Sets up skills for Claude Code, Codex, and Gemini. It currently wires session logging and self-improvement hooks for Claude Code, records an agent_playbook metadata block for Codex, and prepares Gemini skill directories.

pnpm dlx @codeharbor/agent-playbook init
# or
npm exec -- @codeharbor/agent-playbook init

Project-only setup:

pnpm dlx @codeharbor/agent-playbook init --project

Method 1: Symbolic Links (Recommended)

Link the skills to your global skills directories:

mkdir -p ~/.claude/skills ~/.codex/skills ~/.gemini/skills
for skill in /path/to/agent-playbook/skills/*; do
  [ -f "$skill/SKILL.md" ] || continue
  ln -s "$skill" ~/.claude/skills/
  ln -s "$skill" ~/.codex/skills/
  ln -s "$skill" ~/.gemini/skills/
done

Example:

# Link individual skills
ln -s ~/Documents/code/GitHub/agent-playbook/skills/skill-router ~/.claude/skills/skill-router
ln -s ~/Documents/code/GitHub/agent-playbook/skills/architecting-solutions ~/.claude/skills/architecting-solutions
ln -s ~/Documents/code/GitHub/agent-playbook/skills/planning-with-files ~/.claude/skills/planning-with-files

Method 2: Copy Skills

Copy the skills directly to your global skills directories:

mkdir -p ~/.claude/skills ~/.codex/skills ~/.gemini/skills
for skill in /path/to/agent-playbook/skills/*; do
  [ -f "$skill/SKILL.md" ] || continue
  cp -R "$skill" ~/.claude/skills/
  cp -R "$skill" ~/.codex/skills/
  cp -R "$skill" ~/.gemini/skills/
done

Method 3: Add to Project-Specific Skills

For project-specific usage, create .claude/.codex/.gemini skills directories in your project:

mkdir -p .claude/skills .codex/skills .gemini/skills
for skill in /path/to/agent-playbook/skills/*; do
  [ -f "$skill/SKILL.md" ] || continue
  cp -R "$skill" .claude/skills/
  cp -R "$skill" .codex/skills/
  cp -R "$skill" .gemini/skills/
done

Verify Installation

List your installed skills:

ls -la ~/.claude/skills/
ls -la ~/.codex/skills/
ls -la ~/.gemini/skills/

Skills Manager

Use the local-only skills manager to inspect and manage skills across project and global scopes:

apb skills list --scope both --target all
apb skills add ./skills/my-skill --scope project --target claude

apb is a short alias for agent-playbook.

Platform support

The MCP server is a separate optional integration and is currently documented for Claude Code.

Project Structure

agent-playbook/
├── prompts/       # Prompt templates and examples
├── skills/        # Custom skills documentation
├── docs/          # Automation best practices and examples
├── mcp-server/    # MCP server for skill discovery
└── README.md      # Project documentation

Skills Catalog

Meta Skills (Workflow & Coordination)

Core Development

Documentation & Testing

Architecture & DevOps

Planning & Architecture

Design & Creative

How Hook Follow-ups Work

Skills can declare follow-up intent in metadata.hooks. A host runtime or agent may use that metadata to run low-risk actions, record pending follow-ups, or ask before taking external actions such as PR creation.

┌──────────────┐
│  prd-planner │ completes
└──────┬───────┘
       │
       ├──→ self-improving-agent (background) → writes learning proposal
       │         └──→ create-pr (ask first) ──→ session-logger (if supported)
       │
       └──→ session-logger (if supported)

Follow-up Modes

Usage

Once installed, skills are automatically available in any Claude Code session. You can invoke them by:

1. Direct activation - The skill activates based on context (e.g., mentioning "PRD", "planning")
2. Manual invocation - Explicitly ask Claude to use a specific skill

Example:

You: Create a PRD for a new authentication feature

The prd-planner skill will activate automatically.

Workflow Example

Full PRD-to-implementation workflow:

User: "Create a PRD for user authentication"
       ↓
prd-planner executes
       ↓
Phase complete → follow-ups:
       ├──→ self-improving-agent (background) - writes proposal
       └──→ session-logger (if supported) - saves session
       ↓
User: "Implement this PRD"
       ↓
prd-implementation-precheck → implementation
       ↓
code-reviewer → self-improving-agent → create-pr

AI Agent Learning Path

docs/ai-agent-learning-path.md - A progressive learning path for building agents with Claude, GLM, and Codex:

Complete Workflow Example

docs/complete-workflow-example.md - An end-to-end example from input or design reference to final delivery:

1. Input → Upload an image or describe the request
2. PRD → prd-planner creates the PRD and can record a self-improving-agent follow-up
3. Review → Review and refine the plan
4. Implement → Build against the PRD
5. Review → code-reviewer checks quality
6. Feedback → self-improving-agent captures learning artifacts and proposes updates
7. Submit → create-pr opens a PR and keeps bilingual docs aligned

Updating Skills

When you update skills in agent-playbook, the symbolic links ensure you always have the latest version. To update:

cd /path/to/agent-playbook
git pull origin main

If using copied skills, refresh through the CLI so all selected targets stay aligned:

apb skills upgrade --scope both --target all

Contributing

Contributions are welcome! Feel free to submit PRs with your own prompts, skills, or use cases.

When contributing skills:

1. Add your skill to the appropriate category in the Skills Catalog above
2. Include SKILL.md with proper front matter (name, description, allowed-tools, hooks)
3. Add README.md with usage examples
4. Keep SKILL.md lean and move long procedures or templates into references/
5. Prefer abstract, portable guidance over private or business-specific knowledge
6. Add explicit acceptance criteria so the skill has a clear definition of done
7. Add lightweight eval prompts or scenario checks for new skills when practical
8. Follow the structure and guidance from Anthropic's skill-creator
9. Check Skill Ecosystem References before adding new skill infrastructure
10. Update both README.md and README.zh-CN.md when bilingual parity is part of the change
11. Validate skill structure: python3 scripts/validate_skills.py
12. Optional: run skills-ref validation: python3 -m pip install "git+https://github.com/agentskills/agentskills.git@5d4c1fda3f786fff826c7f56b6cb3341e7f3a911#subdirectory=skills-ref" && skills-ref validate skills/<name>

License

MIT License