Agent Playbook

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

Overview

This repository organizes and stores practical resources for working with AI Agents like Claude Code, including prompt templates, custom skills, usage examples, and best practices.

Installation

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

Sets up skills for Claude Code, Codex, and Gemini, and wires hooks for session logging and self-improvement.

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.

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 |

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 - 适用于 Claude、GLM、Codex 的 Agent 开发学习路径：

| Level | 主题 | 时间 | 产出 | |-------|------|------|------| | 1 | 基础提示工程 | 1 周 | 完成单一任务 | | 2 | Skill 技能开发 | 1 周 | 第一个可复用 Skill | | 3 | 工作流编排 | 2 周 | 完整自动化流程 | | 4 | 自我学习系统 | 2-3 周 | 从经验中学习的 Agent | | 5 | 自进化 Agent | 2-3 周 | 完全自主进化 |

Complete Workflow Example

docs/complete-workflow-example.md - 从图片/需求到交付的完整流程演示：

Input → 上传图片或描述需求
PRD → prd-planner 创建 PRD（自动触发 self-improving-agent）
Review → 自我审核和改进
Implement → 根据 PRD 编写代码
Review → code-reviewer 检查质量
Feedback → self-improving-agent 从经验中学习
Submit → create-pr 提交并同步中英文 README

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
Update both README.md and README.zh-CN.md
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

agent-playbook

💡 摘要

🎯 适合人群