agent-playbook
> Local-first Behavior CI for coding agents
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/zhaono1--agent-playbook)HTML
<a href="/listings/zhaono1--agent-playbook"><img src="/api/listings/zhaono1--agent-playbook/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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/
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 392 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Agent Playbook
- > Local-first Behavior CI for coding agents
- English | [简体中文](./README.zh-CN.md)
- ## 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](./docs/context-layering-for-agent-playbooks.md)
- - [Skill Ecosystem References](./docs/skill-ecosystem-references.md)
- - [Host Conformance](./docs/host-conformance.md)
- - [Integrations and Product Roadmap](./docs/integrations-and-product-roadmap.md)
- - [long-task-coordinator](./skills/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.
- ```bash
- pnpm dlx @codeharbor/agent-playbook init
- # or
- npm exec -- @codeharbor/agent-playbook init
- ```
- Explicitly enable Claude Code session and failure hooks:
- ```bash
- pnpm dlx @codeharbor/agent-playbook init --hooks
- ```
- Inspect the installed local contracts without claiming an unobserved host run:
- ```bash
- apb conformance
- apb conformance --format json
- ```
- Project-only setup:
- ```bash
- pnpm dlx @codeharbor/agent-playbook init --project
- ```
- ### Method 1: Symbolic Links (Recommended)
- Link the skills to your global skills directories:
- ```bash
- 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:
- ```bash
- # 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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](./skills/self-improving-agent/references/eval-artifact.md).
- Export the reviewed notebook to Obsidian or another local Markdown system:
- ```bash
- 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](./docs/self-improvement-example.md).
- ## 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](./docs/host-conformance.md) 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
- ```text
- 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](./skills/skill-router/)** | Intelligently routes user requests to the most appropriate skill | Manual |
- | **[create-pr](./skills/create-pr/)** | Creates PRs with bilingual documentation checks | On submission |
- | **[session-logger](./skills/session-logger/)** | Saves conversation history to session log files | Host-supported hook |
- | **[auto-trigger](./skills/auto-trigger/)** | Documents follow-up hook metadata between skills | Config only |
- | **[workflow-orchestrator](./skills/workflow-orchestrator/)** | Coordinates multi-skill workflows and records supported follow-ups | Manual / host-supported hook |
- | **[self-improving-agent](./skills/self-improving-agent/)** | Captures bounded redacted candidates and separates validation from application | Failure hook / manual review |
- ### Core Development
- | Skill | Description | Follow-up |
- |-------|-------------|--------------|
- | **[commit-helper](./skills/commit-helper/)** | Git commit messages following Conventional Commits specification | Manual |
- | **[code-reviewer](./skills/code-reviewer/)** | Comprehensive code review for quality, security, and best practices | Manual / After implementation |
- | **[debugger](./skills/debugger/)** | Systematic debugging and issue resolution | Manual |
- | **[refactoring-specialist](./skills/refactoring-specialist/)** | Code refactoring and technical debt reduction | Manual |
- ### Documentation & Testing
- | Skill | Description | Follow-up |
- |-------|-------------|--------------|
- | **[documentation-engineer](./skills/documentation-engineer/)** | Technical documentation and README creation | Manual |
- | **[api-documenter](./skills/api-documenter/)** | OpenAPI/Swagger API documentation | Manual |
- | **[test-automator](./skills/test-automator/)** | Automated testing framework setup and test creation | Manual |
- | **[qa-expert](./skills/qa-expert/)** | Quality assurance strategy and quality gates | Manual |
- ### Architecture & DevOps
- | Skill | Description | Follow-up |
- |-------|-------------|--------------|
- | **[api-designer](./skills/api-designer/)** | REST and GraphQL API architecture design | Manual |
- | **[security-auditor](./skills/security-auditor/)** | Security audit covering OWASP Top 10 | Manual |
- | **[performance-engineer](./skills/performance-engineer/)** | Performance optimization and analysis | Manual |
- | **[deployment-engineer](./skills/deployment-engineer/)** | CI/CD pipelines and deployment automation | Manual |
- ### Planning & Architecture
- | Skill | Description | Follow-up |
- |-------|-------------|--------------|
- | **[prd-planner](./skills/prd-planner/)** | Creates PRDs using persistent file-based planning | Manual (keyword: "PRD") |
- | **[prd-implementation-precheck](./skills/prd-implementation-precheck/)** | Performs preflight review before implementing PRDs | Manual |
- | **[architecting-solutions](./skills/architecting-solutions/)** | Technical solution and architecture design | Manual (keyword: "design solution") |
- | **[planning-with-files](./skills/planning-with-files/)** | General file-based planning for multi-step tasks | Manual |
- | **[long-task-coordinator](./skills/long-task-coordinator/)** | Coordinates multi-session or delegated work with persistent state and recovery rules | Manual |
- ### Design & Creative
- | Skill | Description | Follow-up |
- |-------|-------------|--------------|
- | **[figma-designer](./skills/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](./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](./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:
- ```bash
- cd /path/to/agent-playbook
- git pull origin main
- ```
- If using copied skills, refresh through the CLI so all selected targets stay aligned:
- ```bash
- 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](https://github.com/anthropics/skills/tree/main/skills/skill-creator)
- 9. Check [Skill Ecosystem References](./docs/skill-ecosystem-references.md) 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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.