htlin222/skill-gen

Skill Generator

Generates properly structured Claude Code skills from user requirements.

Quick Start

To create a new skill, gather from the user:

1. What should this skill do?
2. A short name (e.g., processing-pdfs, testing-code)
3. When should Claude use it?
4. Does it need scripts or just instructions?

Workflow

Step 1: Gather Requirements

• Purpose: What does the skill do?
• Triggers: When should it activate? (keywords, scenarios)
• Complexity: Instructions-only, or needs scripts/references?
• Freedom level: Rigid (exact steps) vs flexible (general guidance)?

Step 2: Generate Skill Structure

Create directory: ~/.claude/skills/{skill-name}/

{skill-name}/
├── SKILL.md           # Required: Main instructions (<500 lines)
├── scripts/           # Optional: Executable code
│   └── main.py
└── references/        # Optional: Detailed docs (one level deep)
    └── examples.md

Step 3: Write SKILL.md

---
name: {skill-name}
description: {What it does in third person}. Use when {trigger conditions}.
---

# {Skill Title}

{Brief overview - assume Claude is smart, only add context it doesn't already have}

## Quick Start

{Minimal working example or first step}

## Instructions

{Step-by-step guidance with appropriate freedom level}

## Advanced Features

**Feature A**: See [references/feature-a.md](references/feature-a.md)
**Feature B**: See [references/feature-b.md](references/feature-b.md)

Step 4: Check Line Count & Apply Progressive Disclosure

After drafting SKILL.md, count its lines. If approaching or exceeding 500 lines:

1. Inform the user: "The SKILL.md is {N} lines — exceeding the recommended 500-line limit for optimal performance."
2. Identify splittable sections: detailed references, long examples, advanced features, API docs
3. Move to reference files: references/{topic}.md — keep links one level deep
4. Replace in SKILL.md with a short summary + link:

   **Advanced feature X**: See [references/feature-x.md](references/feature-x.md)
   

5. Add table of contents to any reference file over 100 lines

Even under 500 lines, prefer splitting if a section is self-contained and only needed in specific scenarios.

Step 5: Validate

Run through the validation checklist before finalizing.

Naming Rules

• Length: 1-64 characters
• Format: lowercase letters, numbers, hyphens only
• Prefer gerund form: processing-pdfs, testing-code, writing-documentation
• Acceptable alternatives: pdf-processing, process-pdfs
• Not allowed: start/end with -, consecutive --, reserved words (anthropic, claude), XML tags
• Avoid: vague names (helper, utils, tools), overly generic (documents, data)
• Must match: folder name

Description Rules

• Maximum: 1024 characters, non-empty, no XML tags
• Always third person: "Processes Excel files" not "I can help you" or "You can use this"
• Include both: what it does AND when to use it
• Be specific with key terms: Claude uses descriptions to choose from 100+ skills

Good examples:

description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

description: Generates descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

Avoid: "Helps with documents", "Processes data", "Does stuff with files"

Core Principles

Conciseness

The context window is shared. Challenge each piece of information:

• "Does Claude really need this explanation?"
• "Can I assume Claude knows this?"
• "Does this paragraph justify its token cost?"

Only add context Claude doesn't already have.

Degrees of Freedom

Match specificity to the task's fragility:

| Freedom | Use When | Example | |---------|----------|---------| | High (text instructions) | Multiple valid approaches, context-dependent | Code review guidelines | | Medium (pseudocode/params) | Preferred pattern exists, some variation ok | Report generation template | | Low (exact scripts) | Fragile operations, consistency critical | Database migrations |

Progressive Disclosure

• SKILL.md = overview + navigation (table of contents)
• Reference files = detailed content (loaded on-demand)
• Keep SKILL.md body under 500 lines
• Keep references one level deep from SKILL.md (no nested references)
• Structure long reference files (100+ lines) with a table of contents

Consistent Terminology

Pick one term and use it throughout. Don't mix "API endpoint" / "URL" / "API route" / "path".

Patterns

Workflow with Checklist

For complex multi-step operations:

## Workflow

Copy this checklist and track progress:

```
- [ ] Step 1: Analyze input
- [ ] Step 2: Generate plan
- [ ] Step 3: Validate plan
- [ ] Step 4: Execute
- [ ] Step 5: Verify output
```

Feedback Loop

Run validator → fix errors → repeat:

1. Make changes
2. Validate: `python scripts/validate.py`
3. If validation fails: fix issues, return to step 2
4. Only proceed when validation passes

Template Pattern

Provide output format templates, matching strictness to requirements.

Examples Pattern

Provide input/output pairs for output-quality-dependent skills.

Conditional Workflow

Guide through decision points:

**Creating new?** → Follow "Creation workflow"
**Editing existing?** → Follow "Editing workflow"

Scripts Best Practices

• Handle errors explicitly — don't punt to Claude
• No voodoo constants — justify and document all values
• List dependencies — specify packages to install
• Make execution intent clear:
  • "Run script.py to extract fields" (execute)
  • "See script.py for the algorithm" (read as reference)
• Use forward slashes in all file paths (scripts/helper.py not scripts\helper.py)
• MCP tool references — use fully qualified names: ServerName:tool_name

Anti-Patterns

• Explaining things Claude already knows (what PDFs are, how libraries work)
• Offering too many tool/library options — provide a default with escape hatch
• Time-sensitive information — use "old patterns" section with <details> tag
• Deeply nested references (file → file → file)
• Windows-style paths
• Assuming packages are installed without explicit install instructions

Validation Checklist

Core Quality

• [ ] Name: lowercase, numbers, hyphens only, 1-64 chars, no reserved words
• [ ] Description: third person, specific, includes what + when, under 1024 chars
• [ ] SKILL.md body under 500 lines
• [ ] Additional details in separate files (one level deep)
• [ ] No time-sensitive information
• [ ] Consistent terminology throughout
• [ ] Concrete examples (not abstract)
• [ ] Progressive disclosure used appropriately
• [ ] Workflows have clear steps

Scripts (if applicable)

• [ ] Scripts handle errors explicitly
• [ ] No voodoo constants (all values justified)
• [ ] Required packages listed with install instructions
• [ ] Forward slashes in all paths
• [ ] Validation/verification steps for critical operations
• [ ] Feedback loops for quality-critical tasks

Testing

• [ ] Tested with real usage scenarios
• [ ] Works across target models (Haiku needs more guidance, Opus needs less)

Further Reading

Eval-driven development: See references/eval-driven-development.md for the build → test → observe → iterate cycle, two-Claude iterative development, and observation patterns for refining skills after initial creation.