skill-developer

Skill Developer

When to Load This Skill

Load when: creating a new skill, modifying an existing skill, updating skill-rules.json, evaluating skill quality, or refactoring the skill library.

Skill Anatomy

Every skill follows this structure:

.claude/skills/{skill-name}/
├── SKILL.md                  # main file — MUST be under 500 lines
└── resources/
    ├── topic-1.md            # deep-dive subsections — under 500 lines each
    └── topic-2.md

SKILL.md is the entry point. It must:

• State when to load the skill (trigger criteria)
• Provide immediately actionable patterns (not just theory)
• Reference resources/ files for details rather than inlining everything
• Stay under 500 lines — if growing beyond this, extract to resources

Creating a New Skill

Step 1: Define the trigger

Ask: "What file patterns or prompt keywords make this skill relevant?" These go into skill-rules.json under the skill's triggers.

Step 2: Write SKILL.md

Structure:

# {Skill Name}

## When to Load This Skill
{file patterns and keywords}

## {Core Concept or Setup}
{immediately actionable content}

## {Main Pattern 1}
{code example or steps}

## {Main Pattern 2}
{code example or steps}

## Further Resources

Step 3: Register in skill-rules.json

{
  "skill": "my-new-skill",
  "triggers": {
    "files": ["*.relevant-ext", "specific-file.py"],
    "keywords": ["relevant keyword", "another trigger phrase"],
    "always_load": false
  },
  "priority": 11
}

Priority determines load order when the 3-skill limit is reached. Lower number = higher priority.

Step 4: Test activation

Open a test project, mention a trigger keyword, and verify the skill appears in context via the hook output.

Quality Standards

A good skill is:

• Actionable: Contains copy-paste-ready code, not just descriptions
• Specific: Covers our actual stack (uv, FastAPI, YC, etc.) not generic patterns
• Concise: Every line earns its place — no padding
• Self-contained: Does not require reading another skill to use
• Honest: Notes limitations and when NOT to use the pattern