skill-creator

Trigger when:

• User says "create a skill for X"
• User says "make this into a skill"
• User asks how to write a skill
• User wants to add to the skill library
• skill-forge needs to materialize a skill

Step 1: Clarify the Need

Before creating, understand:

```

What problem does this skill solve?

What goes wrong without it?

Who/when would use this?

Is there an existing skill that covers this?

```

Step 2: Define the Trigger

The description field is critical - it determines activation:

```

Good trigger: "When modifying database schemas, force migration planning

and rollback strategy before executing any ALTER statements"

Bad trigger: "Help with databases"

```

Be specific. Include keywords. Describe the situation.

Step 3: Write Clear Instructions

Each step should be:

• Actionable (starts with verb)
• Unambiguous (one interpretation)
• Testable (you can verify it was done)

```

Good: "List all callers of the function using grep or IDE find-references"

Bad: "Consider the dependencies"

```

Step 4: Add Guardrails

NEVER/ALWAYS sections prevent misuse:

• NEVER: Things that would break the skill's intent
• ALWAYS: Non-negotiable behaviours

```

NEVER:

• Skip the migration plan for "simple" changes
• Execute DDL without rollback strategy

ALWAYS:

• Test migrations on copy of production data
• Include rollback script with every migration

```

Step 5: Provide Real Examples

Examples should be:

• Concrete (real-looking code/scenarios)
• Complete (show full input → output)
• Varied (different situations)

Include - what doesn't work and why.

Step 6: Write the File

Create the skill:

```

mkdir -p skills/[skill-name]

# Write SKILL.md with template

```

Before finalizing, verify:

| Aspect | Check |

|--------|-------|

| Name | Kebab-case, descriptive, not generic |

| Description | Specific triggers, includes keywords |

| Purpose | Clear problem statement, real need |

| Triggers | Specific conditions, includes exceptions |

| Instructions | Actionable steps, unambiguous |

| NEVER | Prevents misuse, hard rules |

| ALWAYS | Required behaviours, non-negotiable |

| Examples | Concrete, complete, varied |

| Failed attempts | Documents what doesn't work |

| Distinct | Not duplicate of existing skill |

Skills should reveal complexity gradually:

Layer 1: Metadata (~100 tokens)

• Name + description
• Always loaded, determines activation
• Must be tight and triggerable

Layer 2: Instructions (~500-1000 tokens)

• Loaded when skill activates
• Step-by-step process
• The "how to"

Layer 3: Resources (variable)

• Scripts, templates, references
• Executed or loaded on demand
• Not in main context

Keep Layer 1 tight. Most tokens should be in Layer 2.

The Checklist (prove-it, loose-ends)

• Run through verification steps
• Binary pass/fail outcomes

The Process (rubber-duck, battle-plan)

• Multi-step workflow
• Each step builds on previous

The Gate (you-sure, skill-gate)

• Pause before action
• Require confirmation

The Transform (geordie, explain-like)

• Change output format/style
• Modify how information is presented

The Analysis (pre-mortem, split-decision)

• Structured evaluation
• Multiple perspectives/options

• Create vague, generic skills ("help with code")
• Skip the examples section
• Write instructions that are just "be careful about X"
• Duplicate existing skills
• Create skills without NEVER/ALWAYS guardrails
• Make triggers too broad (will over-activate)

• Include section
• Test trigger description against likely user prompts
• Keep description under 100 tokens
• Make instructions step-by-step and actionable
• Ground in real problem (not theoretical)

Example 1: User Requests New Skill

User: "Create a skill for handling database migrations"

```

Let me create a structured skill for database migrations.

First, some questions:

1. What goes wrong without this skill? (e.g., data loss, failed deployments)
2. What's the trigger? (modifying schemas, adding tables, etc.)
3. What's the process you want enforced?

[After gathering info, creates skill following template]

```

Example 2: Forging from Discovery

skill-forge identifies a non-obvious learning about API rate limiting.

```

Forging skill: api-rate-limit-handling

[Creates skill with:]

• Trigger: When implementing API calls, external service integration
• Instructions: Check rate limits, implement backoff, handle 429s
• Failed attempts: "Tried simple retry - got banned"
• Examples: Concrete rate limiting code

```

This skill is the foundation for:

• skill-forge: Uses skill-creator to materialize discoveries
• learn-from-this: Feeds insights to skill-creator
• All manual skill creation

Bad skills are worse than no skills - they activate at wrong times, give vague

guidance, and erode trust in the system. Good skills are force multipliers.

This meta-skill ensures every new skill meets the quality bar. It's the

quality gate for the skill library itself.