Agent Playbook

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

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

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:

# Create symbolic links for each skill
ln -s /path/to/agent-playbook/skills/* ~/.claude/skills/
ln -s /path/to/agent-playbook/skills/* ~/.codex/skills/
ln -s /path/to/agent-playbook/skills/* ~/.gemini/skills/

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:

cp -r /path/to/agent-playbook/skills/* ~/.claude/skills/
cp -r /path/to/agent-playbook/skills/* ~/.codex/skills/
cp -r /path/to/agent-playbook/skills/* ~/.gemini/skills/

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
cp -r /path/to/agent-playbook/skills/* .claude/skills/
cp -r /path/to/agent-playbook/skills/* .codex/skills/
cp -r /path/to/agent-playbook/skills/* .gemini/skills/

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

Platform	Skill install	Hooks/config automation	Current status
Claude Code	Yes	Installs SessionEnd and PostToolUse hooks	Full
Codex	Yes	Writes `agent_playbook` metadata block to `~/.codex/config.toml`	Partial
Gemini	Yes	No hook wiring yet	Skill distribution only

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 & Automation)

Skill	Description	Auto-Trigger
skill-router	Intelligently routes user requests to the most appropriate skill	Manual
create-pr	Creates PRs with automatic bilingual documentation updates	After skill updates
session-logger	Saves conversation history to session log files	Auto (after any skill)
auto-trigger	Defines automatic trigger relationships between skills	Config only
workflow-orchestrator	Coordinates multi-skill workflows and triggers follow-up actions	Auto
self-improving-agent	Universal self-improvement that learns from ALL skill experiences	Background

Core Development

Skill	Description	Auto-Trigger
commit-helper	Git commit messages following Conventional Commits specification	Manual
code-reviewer	Comprehensive code review for quality, security, and best practices	Manual / After implementation
debugger	Systematic debugging and issue resolution	Manual
refactoring-specialist	Code refactoring and technical debt reduction	Manual

Documentation & Testing

Skill	Description	Auto-Trigger
documentation-engineer	Technical documentation and README creation	Manual
api-documenter	OpenAPI/Swagger API documentation	Manual
test-automator	Automated testing framework setup and test creation	Manual
qa-expert	Quality assurance strategy and quality gates	Manual

Architecture & DevOps

Skill	Description	Auto-Trigger
api-designer	REST and GraphQL API architecture design	Manual
security-auditor	Security audit covering OWASP Top 10	Manual
performance-engineer	Performance optimization and analysis	Manual
deployment-engineer	CI/CD pipelines and deployment automation	Manual

Planning & Architecture

Skill	Description	Auto-Trigger
prd-planner	Creates PRDs using persistent file-based planning	Manual (keyword: "PRD")
prd-implementation-precheck	Performs preflight review before implementing PRDs	Manual
architecting-solutions	Technical solution and architecture design	Manual (keyword: "design solution")
planning-with-files	General file-based planning for multi-step tasks	Manual
long-task-coordinator	Coordinates multi-session or delegated work with persistent state and recovery rules	Manual

Design & Creative

Skill	Description	Auto-Trigger
figma-designer	Analyzes Figma designs and generates implementation-ready PRDs with visual specifications	Manual (Figma URL)

How Auto-Triggers Work

Skills can automatically trigger other skills when they complete. This creates workflows:

┌──────────────┐
│  prd-planner │ completes
└──────┬───────┘
       │
       ├──→ self-improving-agent (background) → learns from PRD patterns
       │         └──→ create-pr (ask first) ──→ session-logger (auto)
       │
       └──→ session-logger (auto)

Auto-Trigger Modes

Mode	Behavior
`auto`	Executes immediately, blocks until complete
`background`	Runs without blocking, no wait for result
`ask_first`	Asks user before executing

Usage

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

Direct activation - The skill activates based on context (e.g., mentioning "PRD", "planning")
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 → Auto-triggers:
       ├──→ self-improving-agent (background) - extracts patterns
       └──→ session-logger (auto) - 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:

Level	Topic	Time	Outcome
1	Prompt engineering fundamentals	1 week	Complete a single-task workflow
2	Skill development	1 week	Ship a first reusable skill
3	Workflow orchestration	2 weeks	Build a complete automated workflow
4	Self-learning systems	2-3 weeks	Create an agent that learns from experience
5	Self-evolving agents	2-3 weeks	Build a more autonomous improvement loop

Complete Workflow Example

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

Input → Upload an image or describe the request
PRD → prd-planner creates the PRD and can trigger self-improving-agent
Review → Review and refine the plan
Implement → Build against the PRD
Review → code-reviewer checks quality
Feedback → self-improving-agent learns from the result
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, re-copy the updated files:

cp -r /path/to/agent-playbook/skills/* ~/.claude/skills/

Contributing

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

When contributing skills:

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

License

MIT License