Creating Expert

Skill: Creating Expert

Generate complete expert structure for a new domain. This is a meta-skill - a tool that builds tools.

When to Use

• Adding new tech to stack (e.g., "postgres-expert" for Postgres database)
• Creating domain specialist (e.g., "auth-expert" for authentication patterns)
• Splitting existing expert into sub-domains
• Expanding beyond the 4 core experts (convex, nextjs, shadcn, vercel)

Workflow

1. Interview User

Ask clarifying questions:

• Expert name: What domain? (kebab-case, e.g., "postgres-expert")
• Domain description: One-line summary
• Initial knowledge sources: Docs? Agent files? Existing code?
• Related existing agents: Build on existing agents?

2. Create Directory Structure

mkdir -p .claude/experts/{expert-name}-expert

Create three files:

• expertise.yaml - Mental model (initially low confidence)
• question.md - Question workflow
• self-improve.md - Self-improvement workflow

3. Generate Expertise File

Use template from .claude/experts/_shared/expertise-schema.yaml:

---
expert: "{name}-expert"
domain: "{Domain Description}"
last_updated: "{current-date}"
version: "0.1.0"
confidence: "low"
---

{domain}_patterns:
  - pattern: "{initial pattern from docs/agent}"
    context: "{when this applies}"
    evidence: "{source}"
    learned_from: "Initial setup"
    importance: "medium"
    confidence: "low"

common_issues: []  # To be discovered

key_files:
  primary: "{main config/entry file}"
  common_patterns: []

codebase_conventions: []  # To be discovered

evolution_log:
  - date: "{current-date}"
    change: "Expert created"
    confidence_before: "none"
    confidence_after: "low"
    trigger: "manual creation"

metadata:
  created: "{current-date}"
  self_improve_runs: 0
  last_self_improve: "never"
  questions_answered: 0

Fill with initial patterns from:

• Existing agent documentation (if exists)
• Official tech docs
• Common best practices
• User-provided knowledge

4. Generate Question Prompt

Adapt from existing experts (use convex-expert/question.md as template):

---
name: Question {Name} Expert
description: Ask questions about {domain} patterns
argument-hint: [Your question about {domain}]
tools: Read, Grep, Glob
model: inherit
---

# Question: {Name} Expert

Answer questions using accumulated expertise validated against codebase.

## Workflow

### 1. Read Expertise

Read: .claude/experts/{name}-expert/expertise.yaml

### 2. Validate Against Codebase
```bash
# Domain-specific search patterns
Glob: {domain-files}/*
Grep: {domain-keywords}
Read: {key-files}

3. Provide Structured Answer

• Direct answer
• Evidence from codebase (file:line)
• Related patterns from expertise
• Confidence level
• Recommendations

**Customize:**
- Search patterns for domain (Glob/Grep targets)
- Key files to check
- Domain-specific validation steps

### 5. Generate Self-Improve Prompt

Adapt from convex-expert/self-improve.md:

```markdown
---
name: Self-Improve {Name} Expert
description: Sync {domain} expertise with current codebase
tools: Read, Grep, Glob, Edit
model: inherit
---

# Self-Improve: {Name} Expert

## Workflow

### 1. Read Current Expertise

Read: .claude/experts/{name}-expert/expertise.yaml

### 2. Explore Codebase
```bash
Glob: {domain-files}/**/*
Read: {key-files}
Grep: {domain-patterns}

3. Validate Patterns

• Count occurrences (3+ = add/keep)
• Update confidence levels
• Discover new patterns
• Remove obsolete patterns

4. Update Expertise

Edit expertise.yaml:

• Add new patterns found
• Update confidence based on validation
• Update file locations
• Add codebase conventions discovered
• Increment version
• Add evolution log entry

**Customize:**
- File patterns to explore
- Keywords to search for
- Pattern detection criteria

### 6. Update Dispatcher

Add new expert to `.claude/commands/ask-expert.md`:

```markdown
### {name}
**Domain:** {Domain Description}
**Expertise:** {key areas}
**Use for:** {when to use this expert}

Also update expertMap in implementation section.

7. Run Initial Self-Improvement

Execute the self-improve prompt to populate initial expertise:

# This will explore codebase and populate expertise.yaml
# with real patterns discovered

8. Create Agent Reference (Optional)

If there's a corresponding agent, enhance it:

---
expertise_file: .claude/experts/{name}-expert/expertise.yaml
---

## Before Starting Any Task
1. Read expertise file
2. Apply patterns
3. Validate & extend

Success Criteria

New expert should have:

• Directory: .claude/experts/{name}-expert/
• File: expertise.yaml with initial patterns
• File: question.md with domain-specific workflow
• File: self-improve.md with exploration logic
• Updated: ask-expert.md dispatcher
• Tested: Can answer basic questions
• Populated: Initial self-improve run completed

Example: Creating "testing-expert"

# User request: "Create expert for testing patterns"

# 1. Interview
Expert name: testing-expert
Domain: Test automation and quality assurance
Sources: Existing test files, Jest/Vitest docs
Related: Quality checks, CI/CD

# 2. Create structure
mkdir -p .claude/experts/testing-expert

# 3. Generate expertise.yaml
testing_patterns:
  - pattern: "Use describe/it for test structure"
    confidence: "low"
  - pattern: "Mock external dependencies"
    confidence: "low"

key_files:
  config: "vitest.config.ts"
  test_utils: "test/utils.ts"

# 4. Generate question.md
# Customize for test file patterns (Glob: **/*.test.ts)

# 5. Generate self-improve.md
# Customize for test discovery (Grep: "describe(", "test(")

# 6. Update ask-expert.md
Add "testing" to expert map

# 7. Run self-improvement
Execute: testing-expert/self-improve.md
Result: Discovers actual test patterns in codebase

# 8. Test
/ask-expert testing "How should I structure unit tests?"
Returns: Answer based on discovered patterns

Tips

Start Simple:

• Begin with 3-5 initial patterns
• Low confidence initially
• Let self-improvement discover rest

Use Templates:

• Copy structure from similar expert
• Customize domain-specific parts
• Keep workflow patterns consistent

Test Early:

• Run self-improve immediately after creation
• Ask test question to verify it works
• Iterate on search patterns if needed

Documentation:

• Add expert to project documentation
• Update CLAUDE.md if significant
• Note what domain it covers

Common Issues

Expert doesn't find patterns:

• Check Glob/Grep patterns in self-improve
• Verify file paths are correct
• Adjust pattern detection thresholds

Questions return low confidence:

• Normal for new experts
• Improve with self-improvement runs
• Add more initial patterns if needed

Duplicate coverage with existing expert:

• Consider if new expert needed
• Or enhance existing expert instead
• Or split existing expert's domain

Output Template

After creating expert, provide summary:

## Created: {Name} Expert

**Domain:** {description}
**Location:** `.claude/experts/{name}-expert/`

**Files Created:**
- expertise.yaml (version 0.1.0, {N} initial patterns)
- question.md (customized for {domain})
- self-improve.md (explores {file-patterns})

**Initial Self-Improvement:**
- Explored {N} files
- Discovered {M} patterns
- Confidence: low → {updated}

**Usage:**
- Ask questions: `/ask-expert {name} "your question"`
- Update expertise: `/sync-expertise {name}`

**Next Steps:**
- Test with sample questions
- Run self-improvement after domain changes
- Enhance patterns as they're validated