Agent Playbook

Local-first Behavior CI for coding agents

English | 简体中文

Overview

Agent Playbook turns repeated coding-agent corrections into reviewed, executable, and reversible behavior changes. Its local CLI provides a Behavior Inbox, baseline/candidate Eval Artifacts, durable-owner suggestions, and Behavior Change Proposals for Claude Code, Codex, Gemini, and DeepSeek Harness workflows.

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

• A Behavior Inbox that prioritizes repeated corrections and regressions
• Executable baseline/candidate evals that gate validation
• Durable-owner suggestions and local Behavior Change Proposal generation
• Reusable skills and installation 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
• Host Conformance
• Integrations and Product Roadmap
• 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
• Small AI-native teams that want Agent behavior changes reviewed like code

Installation

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

Sets up skills for Claude Code, Codex, Gemini, and DeepSeek Harness. Fresh installs leave Claude hooks disabled; pass --hooks to explicitly enable bounded, redacted private session summaries and failure capture. The installer records an agent_playbook metadata block for Codex and prepares the other hosts' skill directories.

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

Explicitly enable Claude Code session and failure hooks:

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

Inspect the installed local contracts without claiming an unobserved host run:

apb conformance
apb conformance --format json

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 ~/.dsh/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/
  ln -s "$skill" ~/.dsh/skills/
done

Example:

# Link individual skills
ln -s /path/to/agent-playbook/skills/skill-router ~/.claude/skills/skill-router
ln -s /path/to/agent-playbook/skills/architecting-solutions ~/.claude/skills/architecting-solutions
ln -s /path/to/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 ~/.dsh/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/
  cp -R "$skill" ~/.dsh/skills/
done

Method 3: Add to Project-Specific Skills

For project-specific usage, create host skill directories in your project:

mkdir -p .claude/skills .codex/skills .gemini/skills .dsh/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/
  cp -R "$skill" .dsh/skills/
done

Verify Installation

List your installed skills:

ls -la ~/.claude/skills/
ls -la ~/.codex/skills/
ls -la ~/.gemini/skills/
ls -la ~/.dsh/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 skills add ./skills/my-skill --scope project --target deepseek

apb is a short alias for agent-playbook.

Validated Self-Improvement

Capture a reusable correction, validate it with representative evidence, and record application only after one durable owner actually changes:

apb self-improve capture --kind correction --summary "Verify the current source before using cached state" --evidence "focused-test"
apb behavior inbox
apb behavior owners cand-... --repo .
apb behavior eval cand-... --artifact behavior-eval.json
apb behavior review cand-... --decision validate --reason "regression scenarios pass" --eval-result /path/to/eval-result.json
apb behavior proposal cand-... --owner "skill:self-improving-agent" --output behavior-proposal.md
apb behavior review cand-... --decision apply --reason "installed in owner" --owner "skill:self-improving-agent" --change-ref "commit:abc123"

Eval artifacts run explicit command arrays without a shell. Passing results store assertion outcomes and hashes, not raw stdout or stderr. See the Eval Artifact contract.

Export the reviewed notebook to Obsidian or another local Markdown system:

apb self-improve export --output /path/to/vault/Agent/Learning.md

When explicitly enabled with apb init --hooks, automatic Claude capture observes failed tool events only and never stores raw tool input or output. See Self-Improvement Example.

Platform support

Platform	Local distribution	Lifecycle adapter	Runtime proof
Claude Code	Skill files	Optional SessionEnd and PostToolUseFailure hooks (--hooks)	Unverified until an observed host run
Codex	Skill files plus Agent Playbook's local metadata marker	Not provided	Unverified until an observed host run
Gemini	Skill files	Not provided	Unverified until an observed host run
DeepSeek Harness	Skill files	Not provided	Unverified until an observed host run

apb conformance proves local filesystem and configuration contracts only. See Host Conformance for the status vocabulary and evidence boundary.

The MCP server is a separate optional integration. Claude Code is the setup example, while the stdio tool contract is usable by any compatible MCP client.

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)

Skill	Description	Follow-up
skill-router	Intelligently routes user requests to the most appropriate skill	Manual
create-pr	Creates PRs with bilingual documentation checks	On submission
session-logger	Saves conversation history to session log files	Host-supported hook
auto-trigger	Documents follow-up hook metadata between skills	Config only
workflow-orchestrator	Coordinates multi-skill workflows and records supported follow-ups	Manual / host-supported hook
self-improving-agent	Captures bounded redacted candidates and separates validation from application	Failure hook / manual review

Core Development

Skill	Description	Follow-up
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	Follow-up
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	Follow-up
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	Follow-up
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	Follow-up
figma-designer	Analyzes Figma designs and generates implementation-ready PRDs with visual specifications	Manual (Figma URL)

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 (declared background follow-up; host-dependent)
       │         └──→ create-pr (ask first) ──→ session-logger (if supported)
       │
       └──→ session-logger (if supported)

Follow-up Modes

Mode	Behavior
auto	Host may run or record a low-risk follow-up
background	Host may record non-blocking analysis or proposal work
ask_first	Asks user before executing

Usage

Once installed, supported hosts can discover the skills according to their own runtime rules. Explicit invocation is the portable behavior:

1. Host discovery - A host may select a skill from its description and context
2. Explicit invocation - Ask the current agent to use a specific skill

Example:

You: Create a PRD for a new authentication feature

Use prd-planner for this request. Automatic activation is host-dependent.

Workflow Example

Full PRD-to-implementation workflow:

User: "Create a PRD for user authentication"
       ↓
prd-planner executes
       ↓
Phase complete → declared follow-up intent (host-dependent):
       ├──→ self-improving-agent (background) - may write a proposal
       └──→ session-logger (if supported) - saves session
       ↓
User: "Implement this PRD"
       ↓
prd-implementation-precheck → implementation
       ↓
code-reviewer → optional learning candidate
       ↓
create-pr (only when the user requested submission)

AI Agent Learning Path

docs/ai-agent-learning-path.md - A progressive learning path for building portable, validated agent workflows:

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	Validated learning systems	2-3 weeks	Turn evidence into reviewed behavior changes
5	Cross-harness improvement	2-3 weeks	Share one lifecycle across thin host adapters

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