Atomizer/docs/protocols/extensions/EXT_04_CREATE_SKILL.md

# EXT_04: Create New Skill

<!--
PROTOCOL: Create New Skill or Module
LAYER: Extensions
VERSION: 1.0
STATUS: Active
LAST_UPDATED: 2025-12-05
PRIVILEGE: admin
LOAD_WITH: []
-->

## Overview

This protocol guides you through creating new skills or skill modules for the LLM instruction system. Skills provide task-specific guidance to Claude sessions.

**Privilege Required**: admin

---

## When to Use

| Trigger | Action |
|---------|--------|
| Need new LLM capability | Follow this protocol |
| "create skill", "new skill" | Follow this protocol |
| Task pattern needs documentation | Follow this protocol |

---

## Skill Types

| Type | Location | Purpose | Example |
|------|----------|---------|---------|
| Bootstrap | `.claude/skills/0X_*.md` | LLM orientation | 00_BOOTSTRAP.md |
| Core | `.claude/skills/core/` | Always-load skills | study-creation-core.md |
| Module | `.claude/skills/modules/` | Optional, load-on-demand | extractors-catalog.md |
| Dev | `.claude/skills/DEV_*.md` | Developer workflows | DEV_DOCUMENTATION.md |

---

## Step-by-Step Guide

### Step 1: Determine Skill Type

**Bootstrap (0X_)**: System-level LLM guidance
- Task classification
- Context loading rules
- Execution patterns

**Core**: Essential task skills that are always loaded
- Study creation
- Run optimization (basic)

**Module**: Specialized skills loaded on demand
- Specific extractors
- Domain-specific (Zernike, neural)
- Advanced features

**Dev (DEV_)**: Developer-facing workflows
- Documentation maintenance
- Testing procedures
- Contribution guides

### Step 2: Create Skill File

#### For Core/Module Skills

```markdown
# {Skill Name}

**Version**: 1.0
**Purpose**: {One-line description}

---

## Overview

{What this skill enables Claude to do}

---

## When to Load

This skill should be loaded when:
- {Condition 1}
- {Condition 2}

---

## Quick Reference

{Tables with key patterns, commands}

---

## Detailed Instructions

### Pattern 1: {Name}

{Step-by-step instructions}

**Example**:
\`\`\`python
{code example}
\`\`\`

### Pattern 2: {Name}

{Step-by-step instructions}

---

## Code Templates

### Template 1: {Name}

\`\`\`python
{copy-paste ready code}
\`\`\`

---

## Validation

Before completing:
- [ ] {Check 1}
- [ ] {Check 2}

---

## Related

- **Protocol**: [{related}]({path})
- **Module**: [{related}]({path})
```

### Step 3: Register Skill

#### For Bootstrap Skills

Add to `00_BOOTSTRAP.md` task classification tree.

#### For Core Skills

Add to `02_CONTEXT_LOADER.md`:
```yaml
{TASK_TYPE}:
  always_load:
    - core/{skill_name}.md
```

#### For Modules

Add to `02_CONTEXT_LOADER.md`:
```yaml
{TASK_TYPE}:
  load_if:
    - modules/{skill_name}.md: "{condition}"
```

### Step 4: Update Navigation

Add to `01_CHEATSHEET.md` if relevant to common tasks.

### Step 5: Test

Test with fresh Claude session:
1. Start new conversation
2. Describe task that should trigger skill
3. Verify correct skill is loaded
4. Verify skill instructions are followed

---

## Skill Design Guidelines

### Structure

- **Front-load**: Most important info first
- **Tables**: Use for structured data
- **Code blocks**: Complete, copy-paste ready
- **Checklists**: For validation steps

### Content

- **Task-focused**: What should Claude DO?
- **Prescriptive**: Clear instructions, not options
- **Examples**: Show expected patterns
- **Validation**: How to verify success

### Length Guidelines

| Skill Type | Target Lines | Rationale |
|------------|--------------|-----------|
| Bootstrap | 100-200 | Quick orientation |
| Core | 500-1000 | Comprehensive task guide |
| Module | 150-400 | Focused specialization |

### Avoid

- Duplicating protocol content (reference instead)
- Vague instructions ("consider" → "do")
- Missing examples
- Untested code

---

## Module vs Protocol

**Skills** teach Claude HOW to interact:
- Conversation patterns
- Code templates
- Validation steps
- User interaction

**Protocols** document WHAT exists:
- Technical specifications
- Configuration options
- Architecture details
- Troubleshooting

Skills REFERENCE protocols, don't duplicate them.

---

## Examples

### Example: Domain-Specific Module

`modules/thermal-optimization.md`:
```markdown
# Thermal Optimization Module

**Version**: 1.0
**Purpose**: Specialized guidance for thermal FEA optimization

---

## When to Load

Load when:
- "thermal", "temperature", "heat" in user request
- Optimizing for thermal properties

---

## Quick Reference

| Physics | Extractor | Unit |
|---------|-----------|------|
| Max temp | E11 | K |
| Gradient | E12 | K/mm |
| Heat flux | E13 | W/m² |

---

## Objective Patterns

### Minimize Max Temperature

\`\`\`python
from optimization_engine.extractors import extract_temperature

def objective(trial):
    # ... run simulation ...
    temp_result = extract_temperature(op2_file)
    return temp_result['max_temperature']
\`\`\`

### Minimize Thermal Gradient

\`\`\`python
from optimization_engine.extractors import extract_thermal_gradient

def objective(trial):
    # ... run simulation ...
    grad_result = extract_thermal_gradient(op2_file)
    return grad_result['max_gradient']
\`\`\`

---

## Configuration Example

\`\`\`json
{
  "objectives": [
    {
      "name": "max_temperature",
      "type": "minimize",
      "unit": "K",
      "description": "Maximum temperature in component"
    }
  ]
}
\`\`\`

---

## Related

- **Extractors**: E11, E12, E13 in SYS_12
- **Protocol**: See OP_01 for study creation
```

---

## Troubleshooting

| Issue | Cause | Solution |
|-------|-------|----------|
| Skill not loaded | Not in context loader | Add loading rule |
| Wrong skill loaded | Ambiguous triggers | Refine conditions |
| Instructions not followed | Too vague | Make prescriptive |

---

## Cross-References

- **Context Loader**: `.claude/skills/02_CONTEXT_LOADER.md`
- **Bootstrap**: `.claude/skills/00_BOOTSTRAP.md`
- **Related**: [EXT_03_CREATE_PROTOCOL](./EXT_03_CREATE_PROTOCOL.md)

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2025-12-05 | Initial release |