{
  "markdown": "# Agent Playbook\n\n> Local-first Behavior CI for coding agents\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Overview\n\nAgent Playbook turns repeated coding-agent corrections into reviewed, executable,\nand reversible behavior changes. Its local CLI provides a Behavior Inbox,\nbaseline/candidate Eval Artifacts, durable-owner suggestions, and Behavior Change\nProposals for Claude Code, Codex, Gemini, and DeepSeek Harness workflows.\n\nEverything in this repository is intended to stay portable and abstract. Private operating details, company-specific workflows, and sensitive business context should live elsewhere.\n\n## What you get\n\n- A Behavior Inbox that prioritizes repeated corrections and regressions\n- Executable baseline/candidate evals that gate validation\n- Durable-owner suggestions and local Behavior Change Proposal generation\n- Reusable skills and installation lifecycle tooling through `@codeharbor/agent-playbook`\n- An MCP server for skill discovery\n- Workflow docs for planning, self-improvement, automation, and context design\n\n## Design Principles\n\nThe repository is evolving around a few portable agent design rules:\n\n- Keep hard constraints always-on, but keep them short\n- Turn reusable methods into skills\n- Keep detailed facts and examples retrievable from references and docs\n- Persist long-running task state outside chat so recovery is reliable\n\nFurther reading:\n\n- [Context Layering for Agent Playbooks](./docs/context-layering-for-agent-playbooks.md)\n- [Skill Ecosystem References](./docs/skill-ecosystem-references.md)\n- [Host Conformance](./docs/host-conformance.md)\n- [Integrations and Product Roadmap](./docs/integrations-and-product-roadmap.md)\n- [long-task-coordinator](./skills/long-task-coordinator/)\n\n## Who this is for\n\n- Builders creating their own reusable agent skills\n- Teams standardizing how agents plan, review, and recover work\n- Power users who want local-first tooling instead of SaaS-heavy orchestration\n- Small AI-native teams that want Agent behavior changes reviewed like code\n\n## Installation\n\n### Method 0: One-Command Installer (PNPM/NPM)\n\nSets 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.\n\n```bash\npnpm dlx @codeharbor/agent-playbook init\n# or\nnpm exec -- @codeharbor/agent-playbook init\n```\n\nExplicitly enable Claude Code session and failure hooks:\n\n```bash\npnpm dlx @codeharbor/agent-playbook init --hooks\n```\n\nInspect the installed local contracts without claiming an unobserved host run:\n\n```bash\napb conformance\napb conformance --format json\n```\n\nProject-only setup:\n\n```bash\npnpm dlx @codeharbor/agent-playbook init --project\n```\n\n### Method 1: Symbolic Links (Recommended)\n\nLink the skills to your global skills directories:\n\n```bash\nmkdir -p ~/.claude/skills ~/.codex/skills ~/.gemini/skills ~/.dsh/skills\nfor skill in /path/to/agent-playbook/skills/*; do\n  [ -f \"$skill/SKILL.md\" ] || continue\n  ln -s \"$skill\" ~/.claude/skills/\n  ln -s \"$skill\" ~/.codex/skills/\n  ln -s \"$skill\" ~/.gemini/skills/\n  ln -s \"$skill\" ~/.dsh/skills/\ndone\n```\n\nExample:\n\n```bash\n# Link individual skills\nln -s /path/to/agent-playbook/skills/skill-router ~/.claude/skills/skill-router\nln -s /path/to/agent-playbook/skills/architecting-solutions ~/.claude/skills/architecting-solutions\nln -s /path/to/agent-playbook/skills/planning-with-files ~/.claude/skills/planning-with-files\n```\n\n### Method 2: Copy Skills\n\nCopy the skills directly to your global skills directories:\n\n```bash\nmkdir -p ~/.claude/skills ~/.codex/skills ~/.gemini/skills ~/.dsh/skills\nfor skill in /path/to/agent-playbook/skills/*; do\n  [ -f \"$skill/SKILL.md\" ] || continue\n  cp -R \"$skill\" ~/.claude/skills/\n  cp -R \"$skill\" ~/.codex/skills/\n  cp -R \"$skill\" ~/.gemini/skills/\n  cp -R \"$skill\" ~/.dsh/skills/\ndone\n```\n\n### Method 3: Add to Project-Specific Skills\n\nFor project-specific usage, create host skill directories in your project:\n\n```bash\nmkdir -p .claude/skills .codex/skills .gemini/skills .dsh/skills\nfor skill in /path/to/agent-playbook/skills/*; do\n  [ -f \"$skill/SKILL.md\" ] || continue\n  cp -R \"$skill\" .claude/skills/\n  cp -R \"$skill\" .codex/skills/\n  cp -R \"$skill\" .gemini/skills/\n  cp -R \"$skill\" .dsh/skills/\ndone\n```\n\n### Verify Installation\n\nList your installed skills:\n\n```bash\nls -la ~/.claude/skills/\nls -la ~/.codex/skills/\nls -la ~/.gemini/skills/\nls -la ~/.dsh/skills/\n```\n\n## Skills Manager\n\nUse the local-only skills manager to inspect and manage skills across project and global scopes:\n\n```bash\napb skills list --scope both --target all\napb skills add ./skills/my-skill --scope project --target claude\napb skills add ./skills/my-skill --scope project --target deepseek\n```\n\n`apb` is a short alias for `agent-playbook`.\n\n## Validated Self-Improvement\n\nCapture a reusable correction, validate it with representative evidence, and\nrecord application only after one durable owner actually changes:\n\n```bash\napb self-improve capture --kind correction --summary \"Verify the current source before using cached state\" --evidence \"focused-test\"\napb behavior inbox\napb behavior owners cand-... --repo .\napb behavior eval cand-... --artifact behavior-eval.json\napb behavior review cand-... --decision validate --reason \"regression scenarios pass\" --eval-result /path/to/eval-result.json\napb behavior proposal cand-... --owner \"skill:self-improving-agent\" --output behavior-proposal.md\napb behavior review cand-... --decision apply --reason \"installed in owner\" --owner \"skill:self-improving-agent\" --change-ref \"commit:abc123\"\n```\n\nEval artifacts run explicit command arrays without a shell. Passing results store\nassertion outcomes and hashes, not raw stdout or stderr. See the\n[Eval Artifact contract](./skills/self-improving-agent/references/eval-artifact.md).\n\nExport the reviewed notebook to Obsidian or another local Markdown system:\n\n```bash\napb self-improve export --output /path/to/vault/Agent/Learning.md\n```\n\nWhen explicitly enabled with `apb init --hooks`, automatic Claude capture observes\nfailed tool events only and never stores raw tool input or output. See\n[Self-Improvement Example](./docs/self-improvement-example.md).\n\n## Platform support\n\n| Platform | Local distribution | Lifecycle adapter | Runtime proof |\n|----------|--------------------|-------------------|---------------|\n| Claude Code | Skill files | Optional SessionEnd and PostToolUseFailure hooks (`--hooks`) | Unverified until an observed host run |\n| Codex | Skill files plus Agent Playbook's local metadata marker | Not provided | Unverified until an observed host run |\n| Gemini | Skill files | Not provided | Unverified until an observed host run |\n| DeepSeek Harness | Skill files | Not provided | Unverified until an observed host run |\n\n`apb conformance` proves local filesystem and configuration contracts only. See\n[Host Conformance](./docs/host-conformance.md) for the status vocabulary and\nevidence boundary.\n\nThe MCP server is a separate optional integration. Claude Code is the setup\nexample, while the stdio tool contract is usable by any compatible MCP client.\n\n## Project Structure\n\n```text\nagent-playbook/\n├── prompts/       # Prompt templates and examples\n├── skills/        # Custom skills documentation\n├── docs/          # Automation best practices and examples\n├── mcp-server/    # MCP server for skill discovery\n└── README.md      # Project documentation\n```\n\n## Skills Catalog\n\n### Meta Skills (Workflow & Coordination)\n\n| Skill | Description | Follow-up |\n|-------|-------------|--------------|\n| **[skill-router](./skills/skill-router/)** | Intelligently routes user requests to the most appropriate skill | Manual |\n| **[create-pr](./skills/create-pr/)** | Creates PRs with bilingual documentation checks | On submission |\n| **[session-logger](./skills/session-logger/)** | Saves conversation history to session log files | Host-supported hook |\n| **[auto-trigger](./skills/auto-trigger/)** | Documents follow-up hook metadata between skills | Config only |\n| **[workflow-orchestrator](./skills/workflow-orchestrator/)** | Coordinates multi-skill workflows and records supported follow-ups | Manual / host-supported hook |\n| **[self-improving-agent](./skills/self-improving-agent/)** | Captures bounded redacted candidates and separates validation from application | Failure hook / manual review |\n\n### Core Development\n\n| Skill | Description | Follow-up |\n|-------|-------------|--------------|\n| **[commit-helper](./skills/commit-helper/)** | Git commit messages following Conventional Commits specification | Manual |\n| **[code-reviewer](./skills/code-reviewer/)** | Comprehensive code review for quality, security, and best practices | Manual / After implementation |\n| **[debugger](./skills/debugger/)** | Systematic debugging and issue resolution | Manual |\n| **[refactoring-specialist](./skills/refactoring-specialist/)** | Code refactoring and technical debt reduction | Manual |\n\n### Documentation & Testing\n\n| Skill | Description | Follow-up |\n|-------|-------------|--------------|\n| **[documentation-engineer](./skills/documentation-engineer/)** | Technical documentation and README creation | Manual |\n| **[api-documenter](./skills/api-documenter/)** | OpenAPI/Swagger API documentation | Manual |\n| **[test-automator](./skills/test-automator/)** | Automated testing framework setup and test creation | Manual |\n| **[qa-expert](./skills/qa-expert/)** | Quality assurance strategy and quality gates | Manual |\n\n### Architecture & DevOps\n\n| Skill | Description | Follow-up |\n|-------|-------------|--------------|\n| **[api-designer](./skills/api-designer/)** | REST and GraphQL API architecture design | Manual |\n| **[security-auditor](./skills/security-auditor/)** | Security audit covering OWASP Top 10 | Manual |\n| **[performance-engineer](./skills/performance-engineer/)** | Performance optimization and analysis | Manual |\n| **[deployment-engineer](./skills/deployment-engineer/)** | CI/CD pipelines and deployment automation | Manual |\n\n### Planning & Architecture\n\n| Skill | Description | Follow-up |\n|-------|-------------|--------------|\n| **[prd-planner](./skills/prd-planner/)** | Creates PRDs using persistent file-based planning | Manual (keyword: \"PRD\") |\n| **[prd-implementation-precheck](./skills/prd-implementation-precheck/)** | Performs preflight review before implementing PRDs | Manual |\n| **[architecting-solutions](./skills/architecting-solutions/)** | Technical solution and architecture design | Manual (keyword: \"design solution\") |\n| **[planning-with-files](./skills/planning-with-files/)** | General file-based planning for multi-step tasks | Manual |\n| **[long-task-coordinator](./skills/long-task-coordinator/)** | Coordinates multi-session or delegated work with persistent state and recovery rules | Manual |\n\n### Design & Creative\n\n| Skill | Description | Follow-up |\n|-------|-------------|--------------|\n| **[figma-designer](./skills/figma-designer/)** | Analyzes Figma designs and generates implementation-ready PRDs with visual specifications | Manual (Figma URL) |\n\n## How Hook Follow-ups Work\n\nSkills can declare follow-up intent in `metadata.hooks`. A host runtime or agent\nmay use that metadata to run low-risk actions, record pending follow-ups, or ask\nbefore taking external actions such as PR creation.\n\n```\n┌──────────────┐\n│  prd-planner │ completes\n└──────┬───────┘\n       │\n       ├──→ self-improving-agent (declared background follow-up; host-dependent)\n       │         └──→ create-pr (ask first) ──→ session-logger (if supported)\n       │\n       └──→ session-logger (if supported)\n```\n\n### Follow-up Modes\n\n| Mode | Behavior |\n|------|----------|\n| `auto` | Host may run or record a low-risk follow-up |\n| `background` | Host may record non-blocking analysis or proposal work |\n| `ask_first` | Asks user before executing |\n\n## Usage\n\nOnce installed, supported hosts can discover the skills according to their own\nruntime rules. Explicit invocation is the portable behavior:\n\n1. **Host discovery** - A host may select a skill from its description and context\n2. **Explicit invocation** - Ask the current agent to use a specific skill\n\nExample:\n\n```\nYou: Create a PRD for a new authentication feature\n```\n\nUse `prd-planner` for this request. Automatic activation is host-dependent.\n\n## Workflow Example\n\nFull PRD-to-implementation workflow:\n\n```\nUser: \"Create a PRD for user authentication\"\n       ↓\nprd-planner executes\n       ↓\nPhase complete → declared follow-up intent (host-dependent):\n       ├──→ self-improving-agent (background) - may write a proposal\n       └──→ session-logger (if supported) - saves session\n       ↓\nUser: \"Implement this PRD\"\n       ↓\nprd-implementation-precheck → implementation\n       ↓\ncode-reviewer → optional learning candidate\n       ↓\ncreate-pr (only when the user requested submission)\n```\n\n## AI Agent Learning Path\n\n**[docs/ai-agent-learning-path.md](./docs/ai-agent-learning-path.md)** - A progressive learning path for building portable, validated agent workflows:\n\n| Level | Topic | Time | Outcome |\n|-------|------|------|------|\n| 1 | Prompt engineering fundamentals | 1 week | Complete a single-task workflow |\n| 2 | Skill development | 1 week | Ship a first reusable skill |\n| 3 | Workflow orchestration | 2 weeks | Build a complete automated workflow |\n| 4 | Validated learning systems | 2-3 weeks | Turn evidence into reviewed behavior changes |\n| 5 | Cross-harness improvement | 2-3 weeks | Share one lifecycle across thin host adapters |\n\n## Complete Workflow Example\n\n**[docs/complete-workflow-example.md](./docs/complete-workflow-example.md)** - An end-to-end example from input or design reference to final delivery:\n\n1. **Input** → Upload an image or describe the request\n2. **PRD** → `prd-planner` creates the PRD and can record a `self-improving-agent` follow-up\n3. **Review** → Review and refine the plan\n4. **Implement** → Build against the PRD\n5. **Review** → `code-reviewer` checks quality\n6. **Feedback** → `self-improving-agent` captures learning artifacts and proposes updates\n7. **Submit** → `create-pr` opens a PR and keeps bilingual docs aligned\n\n## Updating Skills\n\nWhen you update skills in agent-playbook, the symbolic links ensure you always have the latest version. To update:\n\n```bash\ncd /path/to/agent-playbook\ngit pull origin main\n```\n\nIf using copied skills, refresh through the CLI so all selected targets stay aligned:\n\n```bash\napb skills upgrade --scope both --target all\n```\n\n## Contributing\n\nContributions are welcome! Feel free to submit PRs with your own prompts, skills, or use cases.\n\nWhen contributing skills:\n\n1. Add your skill to the appropriate category in the Skills Catalog above\n2. Include `SKILL.md` with proper front matter (name, description, allowed-tools, hooks)\n3. Add `README.md` with usage examples\n4. Keep `SKILL.md` lean and move long procedures or templates into `references/`\n5. Prefer abstract, portable guidance over private or business-specific knowledge\n6. Add explicit acceptance criteria so the skill has a clear definition of done\n7. Add lightweight eval prompts or scenario checks for new skills when practical\n8. Follow the structure and guidance from [Anthropic's skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)\n9. Check [Skill Ecosystem References](./docs/skill-ecosystem-references.md) before adding new skill infrastructure\n10. Update both README.md and README.zh-CN.md when bilingual parity is part of the change\n11. Validate skill structure: `python3 scripts/validate_skills.py`\n12. 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>`\n\n## License\n\nMIT License\n",
  "bytes": 15957,
  "sha": "e30836f05be757e6b753a6a43a7000d58b18a579a014d01414a1f02b2b44c428",
  "repo_slug": "zhaono1/agent-playbook",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_zhaono1_agent_playbook_self_improving_ag_d0af9bef/readme"
}