Skill Creator

Overview

The Skill Creator provides guidance for building modular packages that extend Claude's capabilities through specialized knowledge, workflows, and tool integrations.

Core Principles

Conciseness matters: "The context window is a public good." Only include information Claude doesn't already possess, challenging each detail's necessity.

Appropriate flexibility: Match specificity to task fragility—narrow bridges need guardrails (low freedom), open fields allow many routes (high freedom).

Progressive disclosure: Load metadata first (~100 words), then SKILL.md body (<5k words), then bundled resources as needed.

Skill Architecture

Every skill requires:

• SKILL.md with YAML frontmatter (name, description) and markdown instructions
• Optional bundled resources: scripts/, references/, and assets/ directories

Resource Types

Scripts (scripts/): Deterministic code for reliability and efficiency. Include when code gets repeatedly rewritten.

References (references/): Documentation loaded as needed. Use for schemas, APIs, policies, and detailed workflows. Keep SKILL.md lean by moving detailed material here.

Assets (assets/): Templates, images, boilerplate—used in output, not loaded into context.

Creation Process

1. Understand usage with concrete examples
2. Plan reusable contents (scripts, references, assets)
3. Initialize with node scripts/init-skill.js <skill-name> --path <directory>
4. Edit resources and SKILL.md
5. Package with node scripts/package-skill.js <path/to/skill-folder>
6. Iterate based on real usage

Key Guidelines

• Avoid deeply nested references; keep one level from SKILL.md
• Use imperative/infinitive voice in SKILL.md
• Description field triggers skill usage—include "when to use" information there
• Delete unused example files after initialization
• Test scripts before packaging
• Run packaging validation before distribution

SKILL.md Frontmatter

Required fields:

---
name: my-skill-name
description: |
  Brief description of what this skill does.
  Include when Claude should use this skill.
---

Optional fields:

• license: License type (e.g., "MIT")
• allowed-tools: List of tools the skill can use
• metadata: Additional metadata object

Naming Conventions

• Use hyphen-case for names (lowercase letters, digits, hyphens)
• Maximum 64 characters
• Cannot start/end with hyphen or contain consecutive hyphens

Description Guidelines

• Maximum 1024 characters
• Cannot contain angle brackets (< or >)
• Should explain when to use the skill

Structural Patterns

Skills can follow different organizational patterns:

Workflow-Based

For sequential processes with clear phases. See references/workflows.md.

Task-Based

For discrete operations that can be performed independently.

Reference/Guidelines

For providing specialized knowledge or style guides.

Capabilities-Based

For extending Claude with new abilities through tool integration.

Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).

Output Patterns

See references/output-patterns.md for guidance on:

• Template patterns (strict vs. flexible)
• Examples patterns (demonstrating desired output through examples)

Scripts Reference

init-skill.js

Initialize a new skill directory:

node scripts/init-skill.js <skill-name> --path <directory>

Creates a complete skill structure with example files.

package-skill.js

Package a skill for distribution:

node scripts/package-skill.js <skill-path> [output-directory]

Creates a .skill file (ZIP format) after validation.

quick-validate.js

Validate a skill's structure and metadata:

node scripts/quick-validate.js <skill-directory>

Checks frontmatter format, required fields, and naming conventions.