create-codebase-expert

Scaffold self-improving codebase expert agents with specs, memory files, and enforcement hooks.

Updated Apr 17, 2026
One-click install
npx skills add https://github.com/hpark0011/mirror --skill create-codebase-expert-hpark0011
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: create-codebase-expert
Source: https://github.com/hpark0011/mirror/tree/main/.agents/skills/create-codebase-expert
Command: npx skills add https://github.com/hpark0011/mirror --skill create-codebase-expert-hpark0011

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Creating a domain-focused coding agent that actually improves over time requires more than a prompt — it needs a bounded spec, persistent knowledge, and a mechanism that forces every session to leave the system better than it found it. This Skill scaffolds that entire structure so agents compound learning instead of starting from zero each session. ## Core Features & Use Cases - Agent scaffolding: Generates .claude/agents/<name>.md with a domain boundary, operating loop, guiding principles, and a scoped tool allowlist, plus knowledge.md and logs.md memory files. - Mechanical self-improvement enforcement: Installs a SubagentStop hook that blocks a domain expert from ending its session until it appends a log entry containing a Bottleneck, Counterfactual, and Patch. - Deterministic validation: Ships validate-scaffold.mjs to check frontmatter fields, unique colors, tool allowlists, memory files, and required spec sections before the agent is considered ready. - Use Case: You want an agent that owns only your chat backend. Run the skill with chat-backend-developer, define what it owns and does not own, and get a validated agent that patches its own knowledge after every task. ## Quick Start Ask the assistant to create a codebase expert for a specific subsystem, for example by invoking /create-codebase-expert chat-backend-developer and answering the boundary question when prompted.

Frequently Asked Questions about create-codebase-expert

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a codebase expert agent for a specific subsystem?▼

Invoke /create-codebase-expert with a kebab-case domain name like chat-backend-developer, then answer the boundary question defining what files and directories the agent owns and does not own. The skill writes the agent spec, memory files, installs the enforcement hook, and runs the scaffold validator.

How does the self-improving agent mechanism work?▼

Every session ends with a mandatory log entry containing a Bottleneck, Counterfactual, and Patch that edits either the agent spec or knowledge.md. A SubagentStop hook mechanically blocks the subagent from ending until logs.md contains a fresh entry with all three markers.

What files does the codebase expert scaffold create?▼

It creates .claude/agents/<name>.md as the agent spec, plus .claude/agent-memory/<name>/knowledge.md and logs.md as persistent memory. It also registers a SubagentStop hook in .claude/settings.json pointing to validate-session-log.mjs.

When should I not use a codebase expert agent?▼

Do not use it for one-off research agents, workflow-only sub-agents, or agents spanning the whole codebase without a clear boundary. The domain must have concrete owned files and directories, and multi-layer features must include the layer in the agent name.

Why does the scaffold validator fail after creating an agent?▼

Validation fails when required frontmatter fields are missing, the description does not start with "Use this agent when", the color duplicates another agent, tools fall outside the known allowlist, memory files are absent, or required H2 sections are missing. Fix the reported errors and re-run validate-scaffold.mjs until it exits 0.