Skill Creator

Create effective, well-structured skills for Claude Code and OpenCode.

Quick Start

1. Run init script: bash scripts/init_skill.sh <skill-name> [output-dir]
2. Edit SKILL.md: Fill in frontmatter and instructions
3. Add resources: scripts/, references/, assets/ as needed
4. Test: Run skill in context to verify behavior

Skill Anatomy

skill-name/
├── SKILL.md              # Required - frontmatter + instructions
├── scripts/              # Executable code (Python/Bash)
├── references/           # Documentation loaded on-demand
└── assets/               # Templates, images, static files

Frontmatter (YAML) - only two fields:

• name: Lowercase, hyphens, max 64 chars (must match directory name)
• description: What it does + when to use it, max 1024 chars

For complete structure details, see references/skill-anatomy.md.

Core Workflow

Step 1: Define Purpose

Answer these questions:

• What problem does this skill solve?
• What triggers should activate it? (error messages, keywords, scenarios)
• What does Claude need to know that isn't obvious?

Step 2: Initialize Skill

# Create new skill with proper structure
bash scripts/init_skill.sh my-skill-name ~/.claude/skills

# Or manually:
mkdir -p ~/.claude/skills/my-skill-name
touch ~/.claude/skills/my-skill-name/SKILL.md

Step 3: Write Frontmatter

---
name: my-skill-name
description: |
  Use when [specific triggers and symptoms].
  Provides [what it does] for [use case].
---

Critical: Description is the PRIMARY trigger mechanism. Include:

• Concrete triggers ("Use when...")
• Problem symptoms (error messages, scenarios)
• Keywords Claude might search for

Step 4: Write Body

Keep SKILL.md lean (<500 lines, ~1500-2000 words):

• Overview: Core principle in 1-2 sentences
• Quick reference: Table/bullets for scanning
• Workflow steps: What to do, in order
• Pointers to references/ for detailed content

Step 5: Add Resources (Optional)

Type	Location	When to Use
Scripts	scripts/	Deterministic operations, reusable code
References	references/	Detailed docs, API specs, schemas
Assets	assets/	Templates, images, static files

Step 6: Test and Iterate

1. Use the skill in a real scenario
2. Note what's unclear or missing
3. Update and re-test
4. Repeat until bulletproof

Progressive Disclosure

Skills use three-level loading to conserve context:

Level	What Loads	When
Metadata	name + description (~100 words)	Always in context
SKILL.md body	Instructions (<5k words)	When skill triggers
Resources	scripts/, references/, assets/	When explicitly needed

Key principle: Only load what's needed. Reference files from SKILL.md clearly:

For API details, see [references/api.md](references/api.md).
For form handling, see [references/forms.md](references/forms.md).

Description Writing

The description field is CRITICAL for skill discovery.

Pattern: Use when [triggers] - [what it provides]

# Bad - vague, no triggers
description: Helps with testing

# Bad - implementation details, not triggers
description: Uses Jest and React Testing Library

# Good - specific triggers + value
description: |
  Use when tests fail intermittently, have race conditions, or 
  timing dependencies - provides condition-based polling patterns
  that replace arbitrary timeouts.

Common Mistakes

Mistake	Fix
Everything in SKILL.md	Move detailed content to references/
Vague description	Add specific triggers and symptoms
No "Use when" triggers	Description must tell Claude WHEN to use it
Deeply nested references	Keep references one level from SKILL.md
Missing cross-references	Point to references/ files explicitly

Resources

• references/skill-anatomy.md - Complete structure documentation
• references/best-practices.md - Anthropic guidelines and patterns
• references/examples.md - Annotated skill examples
• scripts/init_skill.sh - Skill scaffolding script
• assets/skill-template.md - Copy-paste starter template

Checklist

Before deploying a skill:

• name in frontmatter matches directory name
• description starts with "Use when..." and includes triggers
• SKILL.md body is <500 lines
• Detailed content moved to references/
• References/ files linked from SKILL.md
• Tested in real scenario