self-improving-agent
Use after a failure, user correction, repeated workflow problem, or validated success reveals a reusable lesson. Captures bounded redacted c
Open source Repository Open in the app JSON README (API)
About
Use after a failure, user correction, repeated workflow problem, or validated success reveals a reusable lesson. Captures bounded redacted candidates, runs executable behavior evals, and separates validation from application in durable guidance.
Details
- Kind
- Agent skills
- Topic
- No topic detected
- Publisher
- zhaono1
- Origin
- skillssh
- Category
- ferramentas
- Stars
- 77
- Forks
- 12
- Open pull requests
- 7
- Last push
- 2026-08-25T18:56:08Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-30 15:21:09
- Updated
- 2026-09-08 21:03:07
- Origin id
zhaono1/agent-playbook/self-improving-agent
README
# 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