elliotjlt/claude-skill-potions/skill-creator

Skill Creator

<purpose> Creating good skills is itself a skill. This meta-skill guides the creation of new skills with proper structure, clear triggers, actionable instructions, and the guardrails that make skills reliable. It's the skill that makes skills. </purpose>

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

<template>

---
name: [kebab-case-name]
description: |
  [2-4 sentence description. This is what triggers activation.
  Be specific about WHEN this skill should activate. Include
  keywords that would appear in relevant user requests.]
allowed-tools: |
  bash: [list of bash commands needed]
  file: [read, write, etc.]
---
 
# [Skill Name]
 
<purpose>
[1-2 paragraphs: Why does this skill exist? What problem does it solve?
What goes wrong without it? This grounds the skill in real need.]
</purpose>
 
## 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.]
 
<failed-attempts>
What DOESN'T work:
-[Approach that seems reasonable but fails, and why]
-[Common mistake to avoid]
</failed-attempts>
 
## 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:

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

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.