Skip to content

for-developers.md

Latest commit

 

History

History
197 lines (135 loc) · 7.87 KB

for-developers.md

File metadata and controls

197 lines (135 loc) · 7.87 KB
summary Developer map: dispatch model, adding components, shipping changes.
read_when
adding or changing a component
learning the dispatch model

For Developers

You cloned the repo. You want to understand the dispatch model, add a component, or ship a change. This is the map.

The payoff for extending: anything you add gets wired into the router. Users never learn your component's name; they describe work and your agent, skill, or hook fires automatically.

Architecture in 60 Seconds

The system has one path. Every request passes through four layers.

User request → Router (/do) → Agent (*.md) → Skill (SKILL.md) → Script (*.py)

The router classifies intent. It selects an agent and pairs it with a skill when the task type demands methodology. Agents carry domain knowledge. Skills carry workflow structure. Scripts do mechanical work where you want deterministic behavior, not judgment calls. Hooks fire at lifecycle events to inject context, learn from errors, and enforce gates.

This is the entire execution model. There is nothing else.

Directory Structure

agents/              Domain experts. One .md per agent, optional references/ subdirectory
  INDEX.json         Generated routing index (don't hand-edit)

skills/              Workflow methodologies. One directory per skill, each with SKILL.md
  INDEX.json         Generated skill index

hooks/               Event-driven Python scripts. Fire on lifecycle events
  lib/               Shared utilities (hook_utils.py, learning_db_v2.py, feedback_tracker.py)
  tests/             Hook-specific tests

scripts/             Deterministic CLI tools. Python scripts for mechanical operations
  tests/             Script-specific tests

commands/            Slash command definitions

templates/           Scaffolding templates for new components

adr/                 Architecture Decision Records (gitignored, local working documents)

Three things the listing does not communicate. INDEX.json files in agents/ and skills/ are generated by scripts (scripts/generate-agent-index.py, scripts/generate-skill-index.py). Hooks import shared code from hooks/lib/, never from each other. The eval system spans two locations: skills/meta/skill-eval/ for methodology, scripts/skill_eval/ for runner scripts.

Private Skills

Skills you write but keep out of the public repo. Create a separate private git repository at ~/private-skills/ using the same category structure:

~/private-skills/
├── content/
│   └── my-custom-skill/
│       ├── SKILL.md
│       └── references/
├── engineering/
│   └── internal-tool/
│       ├── SKILL.md
│       └── references/

The sync hook discovers ~/private-skills/ automatically: any directory with a SKILL.md inside a category folder gets deployed to ~/.claude/skills/ alongside public skills. No configuration needed.

Setup:

mkdir -p ~/private-skills
cd ~/private-skills
git init
# Create your category/skill/SKILL.md structure
git add -A && git commit -m "initial private skills"
# Optional: push to a private GitHub repo
gh repo create my-private-skills --private --source=. --push

How it works:

What you do What happens
Create ~/private-skills/content/my-skill/SKILL.md Sync deploys it as ~/.claude/skills/my-skill
Create ~/private-skills/engineering/my-tool/SKILL.md Sync deploys it as ~/.claude/skills/my-tool
Delete a skill directory Next sync removes it from ~/.claude/skills/

Skills in ~/private-skills/ follow the same conventions as public skills: YAML frontmatter, workflow phases, reference files. The sync hook runs on every session start, so new private skills are available immediately.

Creating Components

Tell /do what you want. Describe the domain and purpose. The creator agent handles structure, registration, and routing integration.

Agents

/do create an agent for [your domain]

Example prompts:

  • /do create an agent for Terraform infrastructure management that knows HCL, state management, and module patterns
  • /do create an agent for Redis caching that specializes in data structures, eviction policies, and cluster management

Skills

/do create a skill for [your workflow]

Example prompts:

  • /do create a skill for database migration safety with pre-migration checks, rollback validation, and post-migration verification
  • /do create a skill for API contract testing that validates OpenAPI specs against implementation

Hooks

/do create a hook for [your purpose]

Example prompts:

  • /do create a hook that warns when test files are modified without updating test fixtures
  • /do create a PostToolUse hook that detects when a git merge conflict marker is written to a file

Key Architecture Points

The constraint that governs all component design: each type has exactly one job.

  • Agents (agents/*.md) know what to do. Domain expertise, patterns, failure modes.
  • Skills (skills/*/*/SKILL.md) know how to structure work. Phases, gates, methodology.
  • Hooks (hooks/*.py) respond to events. JSON in, JSON out, 50ms budget.
  • Scripts (scripts/*.py) perform deterministic operations. Indexing, validation, linting.

If a process is mechanical and measurable, it belongs in a script. If it requires contextual judgment, it belongs in an agent or skill. The boundary is not negotiable.

The /do router connects everything. After creating any component, test routing:

/do [request that should trigger your new component]

PR Workflow

The full cycle, in order:

  1. Branch from main (feature/, fix/, refactor/ prefix)
  2. Implement changes
  3. Wave review via parallel reviewer agents
  4. Fix findings (up to 3 review-fix iterations)
  5. Retro captures learnings into the learning database
  6. Graduate validated learnings into agent/skill files
  7. Commit in conventional format
  8. Push to remote with tracking
  9. PR creation via gh pr create
  10. CI must pass
  11. Merge after CI and human review

The pr-workflow skill automates steps 3 through 10.

Testing

Framework: pytest.

pytest -v                            # all tests
pytest hooks/tests/ -v               # hook tests
pytest scripts/tests/ -v             # script tests
pytest hooks/tests/test_learning_system.py -v   # single file

What to test by component type:

Component Approach
Hooks Feed JSON input, assert JSON output. Test happy path and silent path. Mock external deps.
Scripts Test CLI interface. Deterministic: input X always produces output Y.
Agents/Skills Use skills/meta/skill-eval/ methodology and scripts/skill_eval/ runner for quality assessment.

Fixtures: scripts/tests/fixtures/ for script test data. Hook tests inline their fixtures.

Key Conventions

Conventional commits. type(scope): description. Types: feat, fix, refactor, docs, test, chore. Focus on what and why.

No AI attribution. Omit "Generated with Claude Code" and co-author lines from all commits.

Branch safety. Create feature branches for all work. The pretool-branch-safety.py hook enforces this by blocking commits to protected branches.

Wabi-sabi in docs. Sentence fragments where they're clear. Varied length. No "delve", "leverage", "comprehensive", "robust", "streamline", "empower." The scripts/scan-ai-patterns.py script catches these.

INDEX.json is generated. Run the generation scripts. They parse frontmatter and build the index. Hand-edits get overwritten.

Hooks live in hooks/. Write there. The sync hook deploys to ~/.claude/hooks/ on session start.

Scripts are deterministic. No LLM calls. No judgment. If it involves reasoning, it is an agent or skill.

50ms hook budget. Hooks fire on every tool call or prompt. Keep them fast. Profile with scripts/benchmark-hooks.py if uncertain.