skill-creator

Skill Creator

Guidance for creating effective skills.

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities with specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains.

What Skills Provide

1. Specialized workflows — multi-step procedures for specific domains
2. Tool integrations — instructions for specific file formats or APIs
3. Domain expertise — company-specific knowledge, schemas, business logic
4. Bundled resources — scripts, references, assets

Core Principles

Concise is Key

The context window is a public good. Default assumption: Claude is already smart. Only add context Claude doesn't have. Prefer concise examples over verbose explanations.

Set Appropriate Degrees of Freedom

• High freedom (text instructions): multiple approaches valid, decisions depend on context
• Medium freedom (pseudocode or scripts with parameters): a preferred pattern exists
• Low freedom (specific scripts, few parameters): operations are fragile, consistency critical

Narrow bridge with cliffs needs guardrails (low freedom); open field allows many routes (high freedom).

Anatomy of a Skill

skill-name/
-- SKILL.md (required)
   -- YAML frontmatter (name, description)
   -- Markdown instructions
-- Bundled Resources (optional)
   -- scripts/      - Executable code
   -- references/   - Docs loaded as needed
   -- assets/       - Files used in output

SKILL.md (required)

• Frontmatter: name and description. Only fields Claude reads for triggering.
• Body: Loaded AFTER the skill triggers.

Bundled Resources

Scripts — deterministic code Claude would otherwise rewrite (e.g., scripts/rotate_pdf.py). Token efficient, can execute without loading into context.

References — docs loaded as needed (e.g., references/finance.md for schemas). Keeps SKILL.md lean. Best practice: include grep patterns for large files. Avoid duplication between SKILL.md and references — prefer references for detail.

Assets — files used in output, not in context (e.g., assets/template.pptx, assets/logo.png, assets/frontend-template/).

What NOT to Include

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md

Skill contains only what the AI agent needs to do the job.

Progressive Disclosure Design Principle

Three-level loading:

1. Metadata (name + description) — always in context (~100 words)
2. SKILL.md body — when skill triggers (<5k words)
3. Bundled resources — as needed

Keep SKILL.md body under 500 lines. Reference split-out files clearly.

Pattern 1: High-level guide with references

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md)
- **API reference**: See [REFERENCE.md](REFERENCE.md)

Pattern 2: Domain-specific organization

bigquery-skill/
-- SKILL.md
-- reference/
   -- finance.md
   -- sales.md
   -- product.md

Pattern 3: Conditional details — show basic content, link to advanced.

Guidelines:

• Avoid deeply nested references — one level deep from SKILL.md
• For files >100 lines, include a table of contents at the top

Skill Creation Process

1. Understand the skill with concrete examples
2. Plan reusable contents (scripts, references, assets)
3. Initialize the skill (run init_skill.py)
4. Edit the skill
5. Package (package_skill.py)
6. Iterate

Step 1: Understand with Concrete Examples

Ask questions to clarify functionality and triggering patterns. Example for an image-editor skill: "What should it support?", "Give examples of how it would be used", "What would a user say that should trigger this skill?"

Step 2: Plan Reusable Contents

For each example, identify scripts / references / assets that would help.

• pdf-editor: scripts/rotate_pdf.py
• frontend-webapp-builder: assets/hello-world/ template
• big-query: references/schema.md

Step 3: Initialize

Run init_skill.py for new skills:

scripts/init_skill.py <skill-name> --path <output-directory>

Generates the directory, SKILL.md template, and example scripts/, references/, assets/ dirs.

Step 4: Edit the Skill

Remember: the skill is for another Claude instance. Include non-obvious info.

Design pattern guides:

• Multi-step processes: see references/workflows.md
• Specific output formats: see references/output-patterns.md

Start with reusable resources. Test scripts by running them. Delete unused example files.

Update SKILL.md

Writing guidelines: Always use imperative/infinitive form.

Frontmatter:

• name: skill name
• description: primary triggering mechanism. Include what the skill does AND specific triggers/contexts. Put ALL "when to use" info here — body loads only after triggering.

Body: Instructions for using the skill and its bundled resources.

Step 5: Package

scripts/package_skill.py <path/to/skill-folder>

Validates (frontmatter, naming, directory structure, description, file organization) then packages to <skill-name>.skill (a zip file with .skill extension).

Step 6: Iterate

Use on real tasks -> notice struggles -> update SKILL.md or resources -> test again.