Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zhaono1--agent-playbook/badge.svg)](/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

i

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)

  1. # Agent Playbook
  2. > Local-first Behavior CI for coding agents
  3. English | [简体中文](./README.zh-CN.md)
  4. ## Overview
  5. Agent Playbook turns repeated coding-agent corrections into reviewed, executable,
  6. and reversible behavior changes. Its local CLI provides a Behavior Inbox,
  7. baseline/candidate Eval Artifacts, durable-owner suggestions, and Behavior Change
  8. Proposals for Claude Code, Codex, Gemini, and DeepSeek Harness workflows.
  9. Everything in this repository is intended to stay portable and abstract. Private operating details, company-specific workflows, and sensitive business context should live elsewhere.
  10. ## What you get
  11. - A Behavior Inbox that prioritizes repeated corrections and regressions
  12. - Executable baseline/candidate evals that gate validation
  13. - Durable-owner suggestions and local Behavior Change Proposal generation
  14. - Reusable skills and installation lifecycle tooling through `@codeharbor/agent-playbook`
  15. - An MCP server for skill discovery
  16. - Workflow docs for planning, self-improvement, automation, and context design
  17. ## Design Principles
  18. The repository is evolving around a few portable agent design rules:
  19. - Keep hard constraints always-on, but keep them short
  20. - Turn reusable methods into skills
  21. - Keep detailed facts and examples retrievable from references and docs
  22. - Persist long-running task state outside chat so recovery is reliable
  23. Further reading:
  24. - [Context Layering for Agent Playbooks](./docs/context-layering-for-agent-playbooks.md)
  25. - [Skill Ecosystem References](./docs/skill-ecosystem-references.md)
  26. - [Host Conformance](./docs/host-conformance.md)
  27. - [Integrations and Product Roadmap](./docs/integrations-and-product-roadmap.md)
  28. - [long-task-coordinator](./skills/long-task-coordinator/)
  29. ## Who this is for
  30. - Builders creating their own reusable agent skills
  31. - Teams standardizing how agents plan, review, and recover work
  32. - Power users who want local-first tooling instead of SaaS-heavy orchestration
  33. - Small AI-native teams that want Agent behavior changes reviewed like code
  34. ## Installation
  35. ### Method 0: One-Command Installer (PNPM/NPM)
  36. 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.
  37. ```bash
  38. pnpm dlx @codeharbor/agent-playbook init
  39. # or
  40. npm exec -- @codeharbor/agent-playbook init
  41. ```
  42. Explicitly enable Claude Code session and failure hooks:
  43. ```bash
  44. pnpm dlx @codeharbor/agent-playbook init --hooks
  45. ```
  46. Inspect the installed local contracts without claiming an unobserved host run:
  47. ```bash
  48. apb conformance
  49. apb conformance --format json
  50. ```
  51. Project-only setup:
  52. ```bash
  53. pnpm dlx @codeharbor/agent-playbook init --project
  54. ```
  55. ### Method 1: Symbolic Links (Recommended)
  56. Link the skills to your global skills directories:
  57. ```bash
  58. mkdir -p ~/.claude/skills ~/.codex/skills ~/.gemini/skills ~/.dsh/skills
  59. for skill in /path/to/agent-playbook/skills/*; do
  60. [ -f "$skill/SKILL.md" ] || continue
  61. ln -s "$skill" ~/.claude/skills/
  62. ln -s "$skill" ~/.codex/skills/
  63. ln -s "$skill" ~/.gemini/skills/
  64. ln -s "$skill" ~/.dsh/skills/
  65. done
  66. ```
  67. Example:
  68. ```bash
  69. # Link individual skills
  70. ln -s /path/to/agent-playbook/skills/skill-router ~/.claude/skills/skill-router
  71. ln -s /path/to/agent-playbook/skills/architecting-solutions ~/.claude/skills/architecting-solutions
  72. ln -s /path/to/agent-playbook/skills/planning-with-files ~/.claude/skills/planning-with-files
  73. ```
  74. ### Method 2: Copy Skills
  75. Copy the skills directly to your global skills directories:
  76. ```bash
  77. mkdir -p ~/.claude/skills ~/.codex/skills ~/.gemini/skills ~/.dsh/skills
  78. for skill in /path/to/agent-playbook/skills/*; do
  79. [ -f "$skill/SKILL.md" ] || continue
  80. cp -R "$skill" ~/.claude/skills/
  81. cp -R "$skill" ~/.codex/skills/
  82. cp -R "$skill" ~/.gemini/skills/
  83. cp -R "$skill" ~/.dsh/skills/
  84. done
  85. ```
  86. ### Method 3: Add to Project-Specific Skills
  87. For project-specific usage, create host skill directories in your project:
  88. ```bash
  89. mkdir -p .claude/skills .codex/skills .gemini/skills .dsh/skills
  90. for skill in /path/to/agent-playbook/skills/*; do
  91. [ -f "$skill/SKILL.md" ] || continue
  92. cp -R "$skill" .claude/skills/
  93. cp -R "$skill" .codex/skills/
  94. cp -R "$skill" .gemini/skills/
  95. cp -R "$skill" .dsh/skills/
  96. done
  97. ```
  98. ### Verify Installation
  99. List your installed skills:
  100. ```bash
  101. ls -la ~/.claude/skills/
  102. ls -la ~/.codex/skills/
  103. ls -la ~/.gemini/skills/
  104. ls -la ~/.dsh/skills/
  105. ```
  106. ## Skills Manager
  107. Use the local-only skills manager to inspect and manage skills across project and global scopes:
  108. ```bash
  109. apb skills list --scope both --target all
  110. apb skills add ./skills/my-skill --scope project --target claude
  111. apb skills add ./skills/my-skill --scope project --target deepseek
  112. ```
  113. `apb` is a short alias for `agent-playbook`.
  114. ## Validated Self-Improvement
  115. Capture a reusable correction, validate it with representative evidence, and
  116. record application only after one durable owner actually changes:
  117. ```bash
  118. apb self-improve capture --kind correction --summary "Verify the current source before using cached state" --evidence "focused-test"
  119. apb behavior inbox
  120. apb behavior owners cand-... --repo .
  121. apb behavior eval cand-... --artifact behavior-eval.json
  122. apb behavior review cand-... --decision validate --reason "regression scenarios pass" --eval-result /path/to/eval-result.json
  123. apb behavior proposal cand-... --owner "skill:self-improving-agent" --output behavior-proposal.md
  124. apb behavior review cand-... --decision apply --reason "installed in owner" --owner "skill:self-improving-agent" --change-ref "commit:abc123"
  125. ```
  126. Eval artifacts run explicit command arrays without a shell. Passing results store
  127. assertion outcomes and hashes, not raw stdout or stderr. See the
  128. [Eval Artifact contract](./skills/self-improving-agent/references/eval-artifact.md).
  129. Export the reviewed notebook to Obsidian or another local Markdown system:
  130. ```bash
  131. apb self-improve export --output /path/to/vault/Agent/Learning.md
  132. ```
  133. When explicitly enabled with `apb init --hooks`, automatic Claude capture observes
  134. failed tool events only and never stores raw tool input or output. See
  135. [Self-Improvement Example](./docs/self-improvement-example.md).
  136. ## Platform support
  137. | Platform | Local distribution | Lifecycle adapter | Runtime proof |
  138. |----------|--------------------|-------------------|---------------|
  139. | Claude Code | Skill files | Optional SessionEnd and PostToolUseFailure hooks (`--hooks`) | Unverified until an observed host run |
  140. | Codex | Skill files plus Agent Playbook's local metadata marker | Not provided | Unverified until an observed host run |
  141. | Gemini | Skill files | Not provided | Unverified until an observed host run |
  142. | DeepSeek Harness | Skill files | Not provided | Unverified until an observed host run |
  143. `apb conformance` proves local filesystem and configuration contracts only. See
  144. [Host Conformance](./docs/host-conformance.md) for the status vocabulary and
  145. evidence boundary.
  146. The MCP server is a separate optional integration. Claude Code is the setup
  147. example, while the stdio tool contract is usable by any compatible MCP client.
  148. ## Project Structure
  149. ```text
  150. agent-playbook/
  151. ├── prompts/ # Prompt templates and examples
  152. ├── skills/ # Custom skills documentation
  153. ├── docs/ # Automation best practices and examples
  154. ├── mcp-server/ # MCP server for skill discovery
  155. └── README.md # Project documentation
  156. ```
  157. ## Skills Catalog
  158. ### Meta Skills (Workflow & Coordination)
  159. | Skill | Description | Follow-up |
  160. |-------|-------------|--------------|
  161. | **[skill-router](./skills/skill-router/)** | Intelligently routes user requests to the most appropriate skill | Manual |
  162. | **[create-pr](./skills/create-pr/)** | Creates PRs with bilingual documentation checks | On submission |
  163. | **[session-logger](./skills/session-logger/)** | Saves conversation history to session log files | Host-supported hook |
  164. | **[auto-trigger](./skills/auto-trigger/)** | Documents follow-up hook metadata between skills | Config only |
  165. | **[workflow-orchestrator](./skills/workflow-orchestrator/)** | Coordinates multi-skill workflows and records supported follow-ups | Manual / host-supported hook |
  166. | **[self-improving-agent](./skills/self-improving-agent/)** | Captures bounded redacted candidates and separates validation from application | Failure hook / manual review |
  167. ### Core Development
  168. | Skill | Description | Follow-up |
  169. |-------|-------------|--------------|
  170. | **[commit-helper](./skills/commit-helper/)** | Git commit messages following Conventional Commits specification | Manual |
  171. | **[code-reviewer](./skills/code-reviewer/)** | Comprehensive code review for quality, security, and best practices | Manual / After implementation |
  172. | **[debugger](./skills/debugger/)** | Systematic debugging and issue resolution | Manual |
  173. | **[refactoring-specialist](./skills/refactoring-specialist/)** | Code refactoring and technical debt reduction | Manual |
  174. ### Documentation & Testing
  175. | Skill | Description | Follow-up |
  176. |-------|-------------|--------------|
  177. | **[documentation-engineer](./skills/documentation-engineer/)** | Technical documentation and README creation | Manual |
  178. | **[api-documenter](./skills/api-documenter/)** | OpenAPI/Swagger API documentation | Manual |
  179. | **[test-automator](./skills/test-automator/)** | Automated testing framework setup and test creation | Manual |
  180. | **[qa-expert](./skills/qa-expert/)** | Quality assurance strategy and quality gates | Manual |
  181. ### Architecture & DevOps
  182. | Skill | Description | Follow-up |
  183. |-------|-------------|--------------|
  184. | **[api-designer](./skills/api-designer/)** | REST and GraphQL API architecture design | Manual |
  185. | **[security-auditor](./skills/security-auditor/)** | Security audit covering OWASP Top 10 | Manual |
  186. | **[performance-engineer](./skills/performance-engineer/)** | Performance optimization and analysis | Manual |
  187. | **[deployment-engineer](./skills/deployment-engineer/)** | CI/CD pipelines and deployment automation | Manual |
  188. ### Planning & Architecture
  189. | Skill | Description | Follow-up |
  190. |-------|-------------|--------------|
  191. | **[prd-planner](./skills/prd-planner/)** | Creates PRDs using persistent file-based planning | Manual (keyword: "PRD") |
  192. | **[prd-implementation-precheck](./skills/prd-implementation-precheck/)** | Performs preflight review before implementing PRDs | Manual |
  193. | **[architecting-solutions](./skills/architecting-solutions/)** | Technical solution and architecture design | Manual (keyword: "design solution") |
  194. | **[planning-with-files](./skills/planning-with-files/)** | General file-based planning for multi-step tasks | Manual |
  195. | **[long-task-coordinator](./skills/long-task-coordinator/)** | Coordinates multi-session or delegated work with persistent state and recovery rules | Manual |
  196. ### Design & Creative
  197. | Skill | Description | Follow-up |
  198. |-------|-------------|--------------|
  199. | **[figma-designer](./skills/figma-designer/)** | Analyzes Figma designs and generates implementation-ready PRDs with visual specifications | Manual (Figma URL) |
  200. ## How Hook Follow-ups Work
  201. Skills can declare follow-up intent in `metadata.hooks`. A host runtime or agent
  202. may use that metadata to run low-risk actions, record pending follow-ups, or ask
  203. before taking external actions such as PR creation.
  204. ```
  205. ┌──────────────┐
  206. │ prd-planner │ completes
  207. └──────┬───────┘
  208. │
  209. ├──→ self-improving-agent (declared background follow-up; host-dependent)
  210. │ └──→ create-pr (ask first) ──→ session-logger (if supported)
  211. │
  212. └──→ session-logger (if supported)
  213. ```
  214. ### Follow-up Modes
  215. | Mode | Behavior |
  216. |------|----------|
  217. | `auto` | Host may run or record a low-risk follow-up |
  218. | `background` | Host may record non-blocking analysis or proposal work |
  219. | `ask_first` | Asks user before executing |
  220. ## Usage
  221. Once installed, supported hosts can discover the skills according to their own
  222. runtime rules. Explicit invocation is the portable behavior:
  223. 1. **Host discovery** - A host may select a skill from its description and context
  224. 2. **Explicit invocation** - Ask the current agent to use a specific skill
  225. Example:
  226. ```
  227. You: Create a PRD for a new authentication feature
  228. ```
  229. Use `prd-planner` for this request. Automatic activation is host-dependent.
  230. ## Workflow Example
  231. Full PRD-to-implementation workflow:
  232. ```
  233. User: "Create a PRD for user authentication"
  234. ↓
  235. prd-planner executes
  236. ↓
  237. Phase complete → declared follow-up intent (host-dependent):
  238. ├──→ self-improving-agent (background) - may write a proposal
  239. └──→ session-logger (if supported) - saves session
  240. ↓
  241. User: "Implement this PRD"
  242. ↓
  243. prd-implementation-precheck → implementation
  244. ↓
  245. code-reviewer → optional learning candidate
  246. ↓
  247. create-pr (only when the user requested submission)
  248. ```
  249. ## AI Agent Learning Path
  250. **[docs/ai-agent-learning-path.md](./docs/ai-agent-learning-path.md)** - A progressive learning path for building portable, validated agent workflows:
  251. | Level | Topic | Time | Outcome |
  252. |-------|------|------|------|
  253. | 1 | Prompt engineering fundamentals | 1 week | Complete a single-task workflow |
  254. | 2 | Skill development | 1 week | Ship a first reusable skill |
  255. | 3 | Workflow orchestration | 2 weeks | Build a complete automated workflow |
  256. | 4 | Validated learning systems | 2-3 weeks | Turn evidence into reviewed behavior changes |
  257. | 5 | Cross-harness improvement | 2-3 weeks | Share one lifecycle across thin host adapters |
  258. ## Complete Workflow Example
  259. **[docs/complete-workflow-example.md](./docs/complete-workflow-example.md)** - An end-to-end example from input or design reference to final delivery:
  260. 1. **Input** → Upload an image or describe the request
  261. 2. **PRD** → `prd-planner` creates the PRD and can record a `self-improving-agent` follow-up
  262. 3. **Review** → Review and refine the plan
  263. 4. **Implement** → Build against the PRD
  264. 5. **Review** → `code-reviewer` checks quality
  265. 6. **Feedback** → `self-improving-agent` captures learning artifacts and proposes updates
  266. 7. **Submit** → `create-pr` opens a PR and keeps bilingual docs aligned
  267. ## Updating Skills
  268. When you update skills in agent-playbook, the symbolic links ensure you always have the latest version. To update:
  269. ```bash
  270. cd /path/to/agent-playbook
  271. git pull origin main
  272. ```
  273. If using copied skills, refresh through the CLI so all selected targets stay aligned:
  274. ```bash
  275. apb skills upgrade --scope both --target all
  276. ```
  277. ## Contributing
  278. Contributions are welcome! Feel free to submit PRs with your own prompts, skills, or use cases.
  279. When contributing skills:
  280. 1. Add your skill to the appropriate category in the Skills Catalog above
  281. 2. Include `SKILL.md` with proper front matter (name, description, allowed-tools, hooks)
  282. 3. Add `README.md` with usage examples
  283. 4. Keep `SKILL.md` lean and move long procedures or templates into `references/`
  284. 5. Prefer abstract, portable guidance over private or business-specific knowledge
  285. 6. Add explicit acceptance criteria so the skill has a clear definition of done
  286. 7. Add lightweight eval prompts or scenario checks for new skills when practical
  287. 8. Follow the structure and guidance from [Anthropic's skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)
  288. 9. Check [Skill Ecosystem References](./docs/skill-ecosystem-references.md) before adding new skill infrastructure
  289. 10. Update both README.md and README.zh-CN.md when bilingual parity is part of the change
  290. 11. Validate skill structure: `python3 scripts/validate_skills.py`
  291. 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>`
  292. ## License
  293. MIT License

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.