creating-expert

name	Creating Expert
description	Create new domain expert with expertise file and workflows. Use when adding new technology or domain area.
tools	Read, Grep, Glob, Write, Edit
model	inherit

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