Skill Creator

Creates Claude Code skills following official best practices.

Official spec: https://agentskills.io/specification (append .md for markdown)

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:

Progressive Disclosure

Context loads in 3 levels:

1. •Metadata (~100 words) - name + description, always in context
2. •SKILL.md body (<5000 words) - loaded when skill triggers
3. •Resources (unlimited) - scripts/, references/, templates/ 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

   • •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):
     yaml

     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, templates/ for output
5. •

   Execution context (optional)

   • •Needs isolated context? → context: fork
   • •Specific agent type? → agent: Explore / Plan
6. •

   Visibility (optional)

   • •Hide from slash commands? → user-invocable: false
7. •

   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
- ≤64 characters
- Not reserved: anthropic, claude, official

Step 3: Generate Skill

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

Create SKILL.md with:

---
name: {skill-name}
description: {description}
allowed-tools: {tools}       # space-delimited or YAML list, omit if unrestricted
context: fork                # optional: isolated execution
agent: {agent-type}          # optional: Explore, Plan, etc.
user-invocable: true         # optional: slash command visibility
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

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)

Enforcing Phase Gates

Claude tends to rush ahead. To force hard stops between phases, use AskUserQuestion as a gate:

## Phase 1: Gather Input

**STOP. Use AskUserQuestion before proceeding.**

[phase instructions...]

**Do NOT proceed to Phase 2 until user responds.**

## Phase 2: Confirm Understanding

**STOP. Use AskUserQuestion to confirm before execution.**

[present what you understood, then ask confirmation...]

**Do NOT proceed to Phase 3 until user confirms.**

Key elements:

• •Bold STOP directive at phase start
• •Explicit instruction to use AskUserQuestion
• •Clear "do NOT proceed until..." at phase end

Resource Types

Anti-patterns: No README.md, CHANGELOG.md, INSTALLATION_GUIDE.md - only include what Claude needs to execute.

Isolated Execution

Use context: fork for skills that need isolated sub-agent context:

---
name: code-analyzer
context: fork
agent: Explore
---

When forked:

• •Skill runs in separate context
• •Parent conversation state preserved
• •Results returned to main context

Skill Hooks

Skills can define lifecycle hooks scoped to their execution. See references/hooks.md for full documentation.

Quick example:

hooks:
  PostToolUse:
    - matcher: Write
      hooks:
        - type: command
          command: "jq -r '.tool_input.file_path' | xargs -I{} ./validate.sh \"{}\""

String Substitution Variables

Available variables for dynamic values in SKILL.md:

Usage examples:

hooks:
  PostToolUse:
    - matcher: Write
      hooks:
        - type: command
          command: "echo 'Session: ${CLAUDE_SESSION_ID}' >> /tmp/skill-audit.log"

Store artifacts in `/tmp/claude-${CLAUDE_SESSION_ID}/` for session isolation.

Use cases:

• •Audit logging with session correlation
• •Session-specific temp directories
• •Tracking which session created artifacts
• •Correlating web session commits/PRs

Skill Spec (Condensed)

Required Frontmatter

• •name: lowercase, hyphens, ≤64 chars
• •description: what + when (triggers), third person, ≤1024 chars

Optional Frontmatter

• •allowed-tools: pre-approved tools (space-delimited or YAML list)
• •context: fork for isolated sub-agent execution
• •agent: agent type for execution (e.g., Explore, Plan)
• •hooks: skill-specific lifecycle hooks (see references/hooks.md)
• •language: response language (e.g., japanese)
• •user-invocable: false to hide from slash command menu (default: true)
• •license: e.g., "MIT"

Body Guidelines

• •Keep under 500 lines
• •Use progressive disclosure: split to references/ when approaching limit
• •No time-sensitive information
• •Consistent terminology

Directory Structure

skill-name/
├── SKILL.md           # Required entry point
├── scripts/           # Executables (run, don't read)
├── references/        # Docs loaded as needed
├── templates/         # Output scaffolds
└── assets/            # Static files (images, fonts)

Reference Files

• •Keep one level deep from SKILL.md (no nested references)
• •Files >100 lines should include a TOC at the top

Examples

Clone the official repo for real examples:

git clone https://github.com/anthropics/skills.git /tmp/claude-skills-examples

Example patterns:

Tooling (in cloned repo):

• •skill-creator/scripts/init_skill.py - scaffolds new skill directory
• •skill-creator/scripts/package_skill.py - validates and packages skill

Best Practices Checklist

Before finalizing:

• • Description is third person with ALL trigger keywords
• • SKILL.md under 500 lines (split to references/ if needed)
• • Degree of freedom matches task fragility
• • No hardcoded paths or time-sensitive info
• • Consistent terminology throughout
• • Reference files >100 lines have TOC
• • Scripts are black-box (documented inputs/outputs, not read into context)