Atomizer/docs/protocols/extensions/EXT_04_CREATE_SKILL.md

EXT_04: Create New Skill

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

# {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:

{TASK_TYPE}:
  always_load:
    - core/{skill_name}.md

For Modules

Add to 02_CONTEXT_LOADER.md:

{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:

# 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

---

Version History

Version	Date	Changes
1.0	2025-12-05	Initial release