skill-creator

ABOUTME: Enforces conventions from CLAUDE.md and provides init/validate tooling

Skill Creator

Create effective Claude Code skills following established conventions.

Quick Reference

| Script | Purpose | |--------|---------| | init_skill.py | Create new skill with proper structure | | validate_skill.py | Validate skill frontmatter and structure |

Run with --help for full options:

uv run ~/.claude/skills/skill-creator/scripts/init_skill.py --help

Skill Anatomy

Every skill consists of:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description, allowed-tools)
│   ├── ABOUTME headers (after closing ---)
│   └── Markdown body (instructions)
└── Optional resources/
    ├── scripts/      - Executable code (Python/Bash)
    ├── references/   - Documentation loaded on demand
    └── assets/       - Files used in output (templates, etc.)

SKILL.md Structure

Frontmatter (Required)

---
name: skill-name
description: >-
  What the skill does and WHEN to use it. Include trigger phrases.
  Triggers on "keyword1", "keyword2", "keyword3".
allowed-tools: Read, Write, Edit, Bash
---

Allowed frontmatter keys: name, description, allowed-tools, license, metadata

ABOUTME Headers (Required)

MUST appear immediately after the closing ---:

---
name: my-skill
description: What it does. Triggers on "x", "y".
allowed-tools: Read, Write
---

# ABOUTME: [Brief description of file purpose]
# ABOUTME: [Key context or dependencies]

# Skill Title

Body (Required)

Write instructions Claude needs to execute the skill effectively.

🔄 RESUMED SESSION CHECKPOINT

When a session is resumed from context compaction, verify skill creation state:

┌─────────────────────────────────────────────────────────────┐
│  SESSION RESUMED - SKILL CREATION VERIFICATION              │
│                                                             │
│  Before continuing skill creation/update work:              │
│                                                             │
│  1. Was I in the middle of creating/updating a skill?       │
│     → Check summary for skill names being worked on         │
│     → Check ~/.claude/skills/ for partial skills            │
│                                                             │
│  2. Did the skill pass validation?                          │
│     → Run: uv run validate_skill.py <skill-path>            │
│                                                             │
│  3. Are ABOUTME headers correct?                            │
│     → Must appear AFTER closing --- of frontmatter          │
│     → Must have 2 lines describing purpose and context      │
│                                                             │
│  If skill creation was in progress:                         │
│  → Re-validate the skill structure                          │
│  → Check description is under 1024 chars                    │
│  → Ensure trigger phrases are included                      │
└─────────────────────────────────────────────────────────────┘

Workflow: Create New Skill

Step 1: Initialize

uv run ~/.claude/skills/skill-creator/scripts/init_skill.py \
    my-new-skill \
    --path ~/.claude/skills

Step 2: Edit SKILL.md

1. Update the description with clear trigger phrases
2. Write ABOUTME headers describing the skill purpose
3. Add workflow instructions or decision trees
4. Reference any scripts/references you'll create

Step 3: Add Resources (Optional)

• scripts/: Add helper scripts for repeatable operations
• references/: Add detailed docs that load only when needed
• assets/: Add templates or files used in output

🚨 IMPORTANT: When creating scripts, invoke the appropriate language skill FIRST:

• .sh files → /bash
• .py files → /python
• .go files → /golang

Step 4: Validate

uv run ~/.claude/skills/skill-creator/scripts/validate_skill.py \
    ~/.claude/skills/my-new-skill

Step 5: Test

Test the skill by invoking it in a Claude Code session with trigger phrases.

Workflow: Update Existing Skill

When modifying an existing skill (adding features, fixing issues, improving documentation):

Step 1: Understand Current Structure

Read the existing SKILL.md to understand:

• Current sections and their organization
• Where new content fits logically
• Existing patterns and style to follow

# Check current structure
head -50 ~/.claude/skills/<skill-name>/SKILL.md

Step 2: Plan Changes

Before editing, identify:

• Where the new content belongs (which section)
• How it relates to existing content (new section vs. addition to existing)
• Style consistency (follow existing formatting patterns)

Step 3: Make Changes

Follow these rules when editing:

• Preserve ABOUTME headers - never remove or modify unless intentional
• Maintain consistent formatting - match existing heading levels, list styles
• Add to existing sections when content is related
• Create new sections only when content is distinct
• Update trigger phrases if adding new use cases

Step 4: Validate

uv run ~/.claude/skills/skill-creator/scripts/validate_skill.py \
    ~/.claude/skills/<skill-name>

Step 5: Test

Verify the skill triggers correctly with both old and new trigger phrases.

Design Principles

Conciseness

Context window is shared. Only include what Claude does NOT already know. Prefer examples over verbose explanations.

Progressive Disclosure

| Level | When Loaded | Size Target | |-------|-------------|-------------| | Frontmatter | Always | ~100 words | | SKILL.md body | When triggered | <500 lines | | References | On demand | Unlimited |

Degrees of Freedom

Match specificity to task fragility:

• High freedom (text instructions): Multiple valid approaches
• Medium freedom (pseudocode/params): Preferred pattern with variation
• Low freedom (specific scripts): Fragile operations requiring consistency

Patterns

See references/patterns.md for:

• Sequential workflow patterns
• Conditional workflow patterns
• Output template patterns
• Domain-specific organization

Validation Rules

The validate script checks:

1. Frontmatter: Valid YAML, required fields present
2. Name: Hyphen-case, max 64 chars, matches directory name
3. Description: No angle brackets, max 1024 chars, includes triggers
4. Structure: ABOUTME headers present after frontmatter

Common Issues

| Issue | Solution | |-------|----------| | Skill not triggering | Add trigger phrases to description | | Skill not triggering on updates | Add "update skill", "modify skill" to triggers | | ABOUTME before frontmatter | Move ABOUTME after closing --- | | Description too long | Move details to SKILL.md body | | Missing allowed-tools | Add tools the skill needs | | Style inconsistency after edit | Read existing skill first; match patterns |