antoniocascais/skill-forge

Skill Creator

Creates Claude Code skills following official best practices.

Core Principles

Only Add What Claude Doesn't Have

Claude is already smart. Only include domain-specific context it lacks:

• API quirks, library gotchas, edge cases
• Your org's conventions and patterns
• Domain knowledge not in training data

Degrees of Freedom

Match instruction specificity to task fragility:

| Level | When | Example | |-------|------|---------| | High freedom | Multiple valid approaches | Code review (heuristics, not rigid steps) | | Medium freedom | Preferred pattern exists | Reports (customizable scripts) | | Low freedom | Fragile operations | DB migrations (exact commands, no deviation) |

Progressive Disclosure

Context loads in 3 levels:

1. Metadata (~100 tokens) - name + description, always in context
2. SKILL.md body (<5000 tokens recommended) - loaded when skill triggers
3. Resources (unlimited) - scripts/, references/, assets/ loaded as needed

Workflow

Step 1: Gather Requirements

Use AskUserQuestion to collect:

1. Skill name - lowercase, hyphens only, ≤64 chars

   • Good: pdf-processor, code-reviewer, deploy-helper
   • Bad: PDF_Processor, my cool skill

2. Description - what it does + when to use it (≤1024 chars)

   • Third person ("Processes...", "Generates...")
   • Include ALL trigger keywords in description (primary discovery mechanism)
   • Example: "Processes PDF files to extract text and tables. Use when working with PDFs, extracting document content, or converting PDF to markdown."

3. Allowed tools (optional) - restrict capabilities

   • Space-delimited: Read Glob Grep
   • YAML list (cleaner for many tools):

     allowed-tools:
       - Read
       - Write
       - Bash(git:*)
     

   • Bash patterns: Bash(git:*), Bash(git diff:*)
   • Unrestricted: omit field entirely

4. Complexity - determines resource structure

   • Simple: SKILL.md only
   • Medium: + references/ for docs
   • Complex: + scripts/ for automation, assets/ for templates and static files

5. Execution context (optional)

   • Needs isolated context? → context: fork
   • Specific agent type? → agent: Explore / Plan
   • Model override? → model: haiku / sonnet / opus

6. Invocation control (optional)

   • User-only trigger (side effects like deploy, commit)? → disable-model-invocation: true
   • Claude-only (background knowledge, not actionable as command)? → user-invocable: false
   • See Invocation Control for the interaction matrix

7. Arguments (optional)

   • Does the skill accept arguments? → use $ARGUMENTS in body
   • Autocomplete hint? → argument-hint: [issue-number]

8. Hooks (optional) - lifecycle automation

   • Validation after writes?
   • Logging before tool use?
   • See references/hooks.md for patterns

Step 2: Validate Name

- Only lowercase letters, numbers, hyphens
- No leading/trailing hyphens, no consecutive hyphens
- ≤64 characters
- Not reserved: anthropic, claude
- Must match parent directory name

Step 3: Generate Skill

Default location: ~/.claude/skills/{skill-name}/

Create SKILL.md with:

---
name: {skill-name}
description: {description}
allowed-tools: {tools}                # optional: space-delimited or YAML list
context: fork                         # optional: isolated execution
agent: {agent-type}                   # optional: Explore, Plan, general-purpose
model: {model}                        # optional: haiku, sonnet, opus
disable-model-invocation: true        # optional: user-only invocation
user-invocable: false                 # optional: Claude-only invocation
argument-hint: {hint}                 # optional: autocomplete hint
hooks: {}                             # optional: see references/hooks.md
---

Generate skill body matching the degree of freedom needed. Use imperative/infinitive form for instructions.

Step 4: Post-Creation

✅ Skill created at: ~/.claude/skills/{skill-name}/
✅ Skill is immediately available (hot-reload enabled)

Step 5: Iterate (User)

Inform user of the iteration loop:

1. Test skill on real tasks
2. Note where Claude struggles or produces poor output
3. Return to refine SKILL.md or add references/scripts
4. Repeat until quality is consistent

Invocation Control

Two fields control who can invoke a skill and how it loads into context:

| Frontmatter | User can invoke | Claude can invoke | Context loading | |-------------|----------------|-------------------|-----------------| | (default) | Yes | Yes | Description always in context, body loads when invoked | | disable-model-invocation: true | Yes | No | Description NOT in context, body loads when user invokes | | user-invocable: false | No | Yes | Description always in context, body loads when invoked |

When to use disable-model-invocation: true:

• Skills with side effects: deploy, commit, send messages, delete resources
• Skills where timing matters: user wants to control when it runs

When to use user-invocable: false:

• Background knowledge that isn't actionable as a command
• Context skills like legacy-system-context — Claude should know it, but /legacy-system-context isn't a meaningful user action

Workflow Patterns

Sequential: Step 1 → 2 → 3 (most skills) Conditional: Decision trees based on input type or user choice (see webapp-testing/) Multi-phase: Plan → validate → execute → verify (for destructive operations)

For enforcing phase gates (hard stops between phases), see references/advanced-features.md.

For resource types (scripts/, references/, assets/) and their context loading behavior, see references/spec-reference.md.

Anti-Patterns

• No README.md, CHANGELOG.md, INSTALLATION_GUIDE.md — only include what Claude needs to execute
• No "When to Use This Skill" in body — triggers come from description; body loads AFTER triggering
• No duplicated info between SKILL.md and references/ — pick one location
• No deeply nested references — keep one level deep from SKILL.md (except examples/ subdirectories)
• No time-sensitive information (dates, version-specific instructions that will rot)
• No hardcoded absolute paths

Advanced Features

For isolated execution (context: fork), string substitution ($ARGUMENTS), dynamic context injection, phase gates, and skill hooks — see references/advanced-features.md.

For skill hook syntax and patterns, see references/hooks.md.

Quick Reference

For the condensed field spec, directory structure, and description budget, see references/spec-reference.md.

Example Output

Generated skill examples at each complexity level:

• references/examples/simple.md — SKILL.md only, no resources
• references/examples/medium.md — with references/ and allowed-tools

Use these as templates when generating skills. For more examples: git clone https://github.com/anthropics/skills.git /tmp/claude-skills-examples

Troubleshooting

Skill name collision

Before creating, check if a skill already exists: ls ~/.claude/skills/{name}/. If it does, ask the user whether to update or choose a different name.

YAML parse errors

Common causes:

• Description contains unquoted colons — wrap in quotes: description: "Deploy helper: automates releases"
• Missing --- delimiters (need both opening and closing)
• Indentation mismatch in YAML lists

Skill not triggering after creation

The description is the primary discovery mechanism. Check:

• Does it include trigger phrases users would actually say?
• Is it too generic? ("Helps with projects" won't trigger)
• Is it too narrow? Missing synonyms or paraphrases

Best Practices Checklist

Before finalizing:

• [ ] Description is third person with ALL trigger keywords
• [ ] Description includes both what + when (trigger scenarios)
• [ ] SKILL.md under 500 lines (split to references/ if needed)
• [ ] Degree of freedom matches task fragility
• [ ] No hardcoded paths or time-sensitive info
• [ ] No "When to Use" section in body (triggers belong in description)
• [ ] Consistent terminology throughout
• [ ] Reference files >100 lines have TOC
• [ ] References one level deep (except examples/ subdirectories)
• [ ] Scripts are black-box (documented inputs/outputs, not read into context)
• [ ] Skills with side effects use disable-model-invocation: true
• [ ] Skills using Claude Code extensions include compatibility field