agent-expert-creation

What this skill does

# Agent Expert Creation Skill

Create specialized agent experts that learn and maintain domain knowledge through the Act-Learn-Reuse pattern.

## Core Problem Solved

> "The massive problem with agents is this. Your agents forget. And that means your agents don't learn."

Generic agents execute and forget. Agent experts execute and learn by maintaining expertise files (mental models) that sync with the codebase.

## When to Use

- Repeated complex tasks in a domain (database, billing, WebSocket)
- High-risk systems where mistakes cascade (security, payments)
- Rapidly evolving code that needs tracked mental models
- Need consistent domain expertise across sessions
- Building plan-build-improve automation cycles

## The Act-Learn-Reuse Pattern

```text
┌─────────────────────────────────────────────────────────────┐
│                    ACT-LEARN-REUSE CYCLE                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ACT ──────────► LEARN ──────────► REUSE                   │
│    │                │                  │                    │
│    │                │                  │                    │
│    ▼                ▼                  ▼                    │
│  Take useful    Update expertise    Read expertise          │
│  action         file via            file FIRST on           │
│  (build, fix)   self-improve        next execution          │
│                 prompt                                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

| Step | Action | Purpose |
| --- | --- | --- |
| **ACT** | Take a useful action | Generate data to learn from (build, fix, answer) |
| **LEARN** | Store new information in expertise file | Build mental model automatically via self-improve prompt |
| **REUSE** | Read expertise first on next execution | Faster, more confident execution from mental model |

## Expertise Files (Mental Models)

> "The expertise file is the mental model of the problem space for your agent expert... This is not a source of truth. This is a working memory file, a mental model."

### Critical Distinction

| Concept | Is | Is NOT |
| --- | --- | --- |
| Expertise file | Mental model | Source of truth |
| Expertise file | Working memory | Documentation |
| Source of truth | The actual codebase | The expertise file |

### Expertise File Structure (YAML)

```yaml
overview:
  description: "High-level system description"
  tech_stack: "Key technologies"
  patterns: "Architectural patterns"

core_implementation:
  module_name:
    file: "path/to/file.py"
    lines: 400
    purpose: "What this module does"

schema_structure:  # For database experts
  tables:
    table_name:
      purpose: "What this table stores"
      key_columns: ["id", "created_at"]

key_operations:
  operation_category:
    operation_name:
      function: "function_name()"
      logic: "How it works"

best_practices:
  - "Practice 1"
  - "Practice 2"

known_issues:
  - "Issue 1 with workaround"
```

### Line Limits (Critical)

| Size | Lines | Use Case |
| --- | --- | --- |
| Small | ~300-500 | Simple domains, focused scope |
| Medium | ~600-800 | Complex domains, moderate scope |
| Maximum | ~1000 | Very complex domains (enforce limit) |

**Why limits matter:** Context window protection. Expertise files must remain scannable.

## Expert Creation Process

### Step 1: Define the Domain

Identify expertise areas based on risk and complexity:

| Risk Level | Domain Examples | Why Expert? |
| --- | --- | --- |
| **Critical** | Billing, Security | Revenue/security impact |
| **High** | Database, Auth | Foundation for everything |
| **Medium-High** | WebSocket, API | Complex event flows |
| **Medium** | DevOps, CI/CD | Infrastructure dependencies |

### Step 2: Design Expert Directory Structure

```text
.claude/commands/experts/{domain}/
  expertise.yaml        # Mental model (~600-1000 lines max)
  question.md           # REUSE: Query expertise without coding
  self-improve.md       # LEARN: Sync mental model with codebase
  plan.md               # REUSE: Create plan using expertise
  plan-build-improve.md # Full ACT→LEARN→REUSE workflow
```

### Step 3: Create the Self-Improve Prompt

> "Don't directly update this expertise file. Teach your agents how to directly update it so they can maintain it."

The self-improve prompt teaches agents HOW to learn:

```markdown
# {Domain} Expert - Self-Improve

Maintain expertise accuracy by comparing against actual codebase implementation.

## Workflow

1. **Check Git Diff** (if $1 is true)
   - Run `git diff HEAD~1` to see recent changes
   - Skip if no changes relevant to {domain}

2. **Read Current Expertise**
   - Load expertise.yaml mental model

3. **Validate Against Codebase**
   - Line-by-line verification against source files
   - Check file paths, line counts, function names

4. **Identify Discrepancies**
   - List what changed vs what expertise says
   - Prioritize significant changes

5. **Update Expertise File**
   - Sync mental model with actual code
   - Add new patterns discovered
   - Remove outdated information

6. **Enforce Line Limit (MAX_LINES: 1000)**
   - Condense if exceeding limit
   - Prioritize critical information

7. **Validation Check**
   - Ensure valid YAML syntax
   - Verify all file references exist
```

### Step 4: Create Expert Commands

The plan-build-improve triplet:

| Command | Purpose | Model | Tokens (Sub-agent) |
| --- | --- | --- | --- |
| {domain}/plan | Investigate and create specs | opus | ~80K (protected) |
| {domain}/build | Execute from specs | sonnet | Varies |
| {domain}/self-improve | Update mental model | opus | Passes git diff only |

## Expert Definition Template

### Sub-Agent Expert

```markdown
---
name: {domain}-expert
description: Expert in {domain} for {purpose}
tools: [focused tool list]
model: sonnet
color: blue
---

# {Domain} Expert

You are a {domain} expert specializing in {specific area}.

## Expertise

- Deep knowledge of {domain concepts}
- Experience with {common patterns}
- Understanding of {best practices}

## Workflow

1. Analyze the request
2. Apply domain expertise
3. Provide structured output

## Output Format

{Structured format for this expert's outputs}
```

### Plan Command

```markdown
---
description: Plan {domain} implementation with detailed specifications
argument-hint: <{domain}-request>
model: opus
allowed-tools: Read, Glob, Grep, WebFetch
---

# {Domain} Expert - Plan

You are a {domain} expert specializing in planning {domain} implementations.

## Expertise

[Pre-loaded domain knowledge here]

## Workflow

1. **Establish Expertise**
   - Read relevant documentation
   - Review existing implementations

2. **Analyze Request**
   - Understand requirements
   - Identify constraints

3. **Design Solution**
   - Architecture decisions
   - Implementation approach
   - Edge cases

4. **Create Specification**
   - Save to `specs/experts/{domain}/{name}-spec.md`
```

### Build Command

```markdown
---
description: Build {domain} implementation from specification
argument-hint: <spec-file-path>
model: sonnet
allowed-tools: Read, Write, Edit, Bash
---

# {Domain} Expert - Build

You are a {domain} expert specializing in implementing {domain} solutions.

## Workflow

1. Read the specification completely
2. Implement according to spec
3. Validate against requirements
4. Report changes made
```

### Improve Command

```markdown
---
description: Improve {domain} expert knowledge based on completed work
argument-hint: <work-summary>
model: sonnet
allowed-tools: Read, Write, Edit
---

# {Domain} Expert - Improve

Update expert knowledge based on work completed.

## Workflow

1. Analyze completed work
2. Identify new patterns learned
3. Update expert documentation
4. Capture lessons learned
```

## Example: Hook Expert

### Sub-Agent: hook-expert

```markdown
---
name: hoo