Expert SDD Creator

Create SDD experts from domain documentation in a single prompt.

Required Input

1. Domain docs (required): Path to markdown file with domain knowledge
2. Steering (optional but recommended): What to focus on, specific use cases

Example prompt:

Create an expert for my custom testing framework.
Docs: /path/to/custom-docs.md
Focus on: component testing, live dependency testing, Cucumber BDD patterns

Creation Process

1. Analyze Input

Read the markdown file and steering context to determine:

• Expert name (kebab-case, prefixed with expert-)
• Triggers (keywords that invoke this expert)
• Key topics for reference files
• Signal validation approach

2. Generate Expert Structure

Create directory at .claude/skills/expert-{name}/ (sibling to this skill's directory):

expert-{name}/
├── SKILL.md                    # Frontmatter + Expert Mode + Signal Mode
├── references/
│   ├── {topic-1}.md            # Synthesized from input docs
│   ├── {topic-N}.md
│   └── signal-workflow.md      # How signal validates behavior
└── scripts/
    ├── run_signal.sh           # Main signal execution
    └── {helper}.sh             # Additional helpers as needed

3. Synthesize References

From the input markdown:

• Extract key topics and organize into separate reference files
• Keep each file focused on one topic
• Include practical examples and patterns
• Create signal-workflow.md describing validation approach

4. Generate Signal Scripts

Analyze domain to determine appropriate signal approach:

Generate run_signal.sh with domain-specific checks and TODOs for customization.

5. Write SKILL.md

Structure the expert's SKILL.md:

---
name: expert-{name}
description: {domain} expertise with signal capability. {what it provides}. Triggers: {trigger-list} (project)
---

Body includes:

• Expert Mode: Quick reference table, navigation to references
• Signal Mode: Quick commands, reference to signal-workflow.md

6. Validate & Register

Run validation:

scripts/validate_expert.sh /path/to/expert-{name}

If valid, register:

scripts/register_expert.sh /path/to/expert-{name}

7. Report Results

Output to user:

• Created directory structure
• List of synthesized reference files
• Signal approach explanation
• Registration locations (line numbers in experts.md/signals.md)
• Path to expert for tweaking
• Any clarifying questions about signal scripts

Expert Structure Requirements

Every expert must have:

1. SKILL.md with valid YAML frontmatter:

   • name: expert-{name} format
   • description: includes triggers and "(project)" suffix

2. references/ directory with:

   • At least one domain knowledge file
   • signal-workflow.md describing validation approach

3. scripts/ directory with:

   • run_signal.sh (executable)
   • Helper scripts as needed

→ See references/expert-structure.md for detailed patterns

Signal Mode

Validate and register created experts.

Quick Commands

Validation Checks

• Directory structure complete (SKILL.md, references/, scripts/)
• YAML frontmatter valid (name, description)
• references/ contains files
• scripts/run_signal.sh exists and is executable
• signal-workflow.md present

Registration

• Parses expert metadata from SKILL.md
• Generates entries for experts.md and signals.md
• Inserts at end of Expert Entries / Signal Entries section
• Reports line numbers of insertions

→ See references/catalog-formats.md for entry formats → See references/signal-patterns.md for signal script patterns