Skill Creator

When To Activate

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

The Skill Template

[Skill Name]

When To Activate

Trigger when:

[Specific condition 1]
[Specific condition 2]
[Specific condition 3]

Do NOT trigger for:

[Exception 1]
[Exception 2]

Instructions

Step 1: [Verb-based title]

[Clear, actionable instructions]

Step 2: [Verb-based title]

[Clear, actionable instructions]

Step 3: [Verb-based title]

[Clear, actionable instructions]

NEVER

[Hard rule 1 - something that would break the skill's purpose]
[Hard rule 2]
[Hard rule 3]

ALWAYS

[Required behaviour 1]
[Required behaviour 2]
[Required behaviour 3]

Examples

Example 1: [Descriptive scenario name]

[Show concrete input and output. Real-world scenario.]

Example 2: [Another scenario]

[Different angle or edge case.]

Why This Skill Exists

[Final grounding: the human cost of not having this skill]

</template>

## Instructions

### 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 `<failed-attempts>` - what doesn't work and why.

### Step 6: Write the File

Create the skill:

mkdir -p skills/[skill-name]

Write SKILL.md with template


## Skill Quality Checklist

<checklist>
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 |
</checklist>

## Progressive Disclosure

<progressive-disclosure>
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.
</progressive-disclosure>

## Common Skill Patterns

<patterns>
**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
</patterns>

## NEVER

- 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)

## ALWAYS

- Include `<failed-attempts>` 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)

## Examples

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

What goes wrong without this skill? (e.g., data loss, failed deployments)
What's the trigger? (modifying schemas, adding tables, etc.)
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


## Integration

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

## Why This Skill Exists

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.