Skill Builder
This Skill provides guidance for creating effective Skills.
About Skills
Skills are modular, self-contained software packages that extend Claude's capabilities by providing expertise, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess on its own.
What Skills Provide
- Specialized Workflows - Domain-specific multi-step processes
- Tool Integrations - Instructions for handling specific file formats or APIs
- Domain Expertise - Company-specific knowledge, patterns, business logic
- Bundled Resources - Scripts, references, and assets for complex and repetitive tasks
Core Principles
Brevity is Key
The context window is a shared resource. Skills share the context window with everything else Claude needs: system prompts, conversation history, metadata from other Skills, and the actual user request.
Default Assumption: Claude is already highly intelligent. Only add context that Claude doesn't already have. Question every piece of information: "Does Claude really need this explanation?" and "Is this text worth its token cost?"
Prioritize concise examples over lengthy explanations.
Set Appropriate Degrees of Freedom
Match specificity to the fragility and variability of the task:
High Freedom (Text-based instructions) : Use when multiple approaches work, decisions depend on context, or heuristics guide the method.
Medium Freedom (Pseudocode or parameterized scripts) : Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
Low Freedom (Specific scripts, few parameters) : Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
Imagine Claude navigating a path: a narrow bridge with cliffs requires specific guardrails (low freedom), while an open field allows multiple routes (high freedom).
Skill Structure
Each Skill consists of a required SKILL.md file and optional bundled resources:
skill-name/
├── SKILL.md (Required)
│ ├── YAML Frontmatter (Required)
│ │ ├── name: (Required)
│ │ └── description: (Required)
│ └── Markdown Instructions (Required)
└── Bundled Resources (Optional)
├── scripts/ - Executable code (Python/Bash, etc.)
├── references/ - Documents loaded into context as needed
└── assets/ - Files used in Claude's output
SKILL.md (Required)
Each SKILL.md contains:
- Frontmatter (YAML) : Includes and fields. This is the only field Claude uses to determine when to use the Skill, so it's critical to clearly and comprehensively describe what the Skill does and when it should be used.
- Body (Markdown) : Instructions and guidance for using the Skill. Only loaded after the Skill is triggered (if at all).
Bundled Resources (Optional)
Scripts ()
Executable code (Python/Bash, etc.) for tasks that require deterministic reliability or are repeatedly written.
- When to Include : When the same code is written repeatedly or deterministic reliability is needed
- Example : for PDF rotation tasks
- Benefits : Token-efficient, deterministic, can be executed without loading into context
- Note : Scripts may still need to be read by Claude for patching or environment-specific adjustments
References ()
Documents and reference materials loaded into context as needed to guide Claude's process and thinking.
- When to Include : For documents Claude should reference while working
- Examples : for financial patterns, for company NDA templates, for company policies, for API specifications
- Use Cases : Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
- Benefits : Keeps SKILL.md lean, loaded only when Claude determines it's needed
- Best Practice : If files are large (>10k words), include grep search patterns in SKILL.md
- Avoid Duplication : Information should exist only in SKILL.md or reference files, not both. Unless information is truly core to the Skill, prioritize placing detailed information in reference files—this keeps SKILL.md lean while making information discoverable without occupying the context window. Only keep basic procedural instructions and workflow guidance in SKILL.md; move detailed reference materials, patterns, and examples to reference files.
Assets ()
Files not intended to be loaded into context, but used in the output generated by Claude.
- When to Include : When the Skill requires files to be used in the final output
- Examples : for brand assets, for PowerPoint templates,
assets/frontend-template/
- Use Cases : Templates, images, icons, boilerplate code, fonts, sample documents to be copied or modified
- Benefits : Separates output resources from documentation, allowing Claude to use files without loading them into context
What Not to Include in Skills
Skills should only contain necessary files that directly support their functionality. Do not create redundant documentation or auxiliary files, including:
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- And so on
Skills should only contain the information an AI agent needs to get the job done. It should not include auxiliary context about the creation process, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files only adds clutter and confusion.
Progressive Disclosure Design Principles
Skills use a three-level loading system to manage context effectively:
- Metadata (Name + Description) - Always in context (~100 words)
- SKILL.md Body - When the Skill is triggered (<5k words)
- Bundled Resources - As needed by Claude (unlimited, since scripts can be executed without being read into the context window)
Progressive Disclosure Patterns
Keep the SKILL.md body lean, under 500 lines, to minimize context bloat. When approaching this limit, split content into separate files. When splitting content into other files, it's important to reference them from SKILL.md and clearly describe when to read them, to ensure readers of the Skill know they exist and when to use them.
Key Principle: When a Skill supports multiple variants, frameworks, or options, only keep core workflows and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configurations) to separate reference files.
Pattern 1: High-Level Guide with References
markdown
# PDF Processing
## Quick Start
Use pdfplumber to extract text:
[Code Example]
## Advanced Features
- **Form Filling**: See [FORMS.md](FORMS.md) for complete guide
- **API Reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
Claude only loads FORMS.md, REFERENCE.md, or EXAMPLES.md when needed.
Pattern 2: Domain-Specific Organization
For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
bigquery-skill/
├── SKILL.md (Overview and Navigation)
└── reference/
├── finance.md (Revenue, billing metrics)
├── sales.md (Opportunities, pipeline)
├── product.md (API usage, features)
└── marketing.md (Campaigns, attribution)
When a user asks about sales metrics, Claude only reads sales.md.
Similarly, for Skills supporting multiple frameworks or variants, organize by variant:
cloud-deploy/
├── SKILL.md (Workflow + Provider Selection)
└── references/
├── aws.md (AWS deployment patterns)
├── gcp.md (GCP deployment patterns)
└── azure.md (Azure deployment patterns)
When a user selects AWS, Claude only reads aws.md.
Pattern 3: Conditional Details
Show basic content, link to advanced content:
markdown
# DOCX Processing
## Create Documents
Use docx-js to create new documents. See [DOCX-JS.md](DOCX-JS.md).
## Edit Documents
For simple edits, modify XML directly.
**For Revision Tracking**: See [REDLINING.md](REDLINING.md)
**For OOXML Details**: See [OOXML.md](OOXML.md)
Claude only reads REDLINING.md or OOXML.md when users need these features.
Important Guidelines:
- Avoid Deeply Nested References - Keep references one level deep from SKILL.md. All reference files should be linked directly from SKILL.md.
- Structure Longer Reference Files - For files over 100 lines, include a table of contents at the top so Claude can see the full scope when previewing.
Skill Creation Process
Skill creation involves the following steps:
- Understand the Skill through concrete examples
- Plan reusable Skill content (scripts, references, assets)
- Initialize the Skill (run init_skill.py)
- Edit the Skill (implement resources and write SKILL.md)
- Package the Skill (run package_skill.py)
- Iterate based on actual use
Execute these steps in order, skipping only when there's a clear reason they don't apply.
Step 1: Understand the Skill through Concrete Examples
Skip this step only when the usage patterns of the Skill are already clearly understood. This step is still valuable even when working on an existing Skill.
To create an effective Skill, you need a clear understanding of concrete examples of how the Skill will be used. This understanding can come from direct user examples or generated examples validated by user feedback.
For example, when building an image editor Skill, relevant questions include:
- "What features should the image editor Skill support? Editing, rotation, or others?"
- "Can you give some examples of how this Skill would be used?"
- "I can imagine users asking things like 'Remove red-eye from this image' or 'Rotate this image'. Can you think of other ways this Skill might be used?"
- "What should users say to trigger this Skill?"
To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better results.
End this step when you have a clear understanding of the features the Skill should support.
Step 2: Plan Reusable Skill Content
To turn concrete examples into an effective Skill, analyze each example by:
- Considering how to execute the example from scratch
- Identifying which scripts, references, and assets would help when repeating these workflows
Example: When building a
Skill to handle queries like "Help me rotate this PDF", analysis shows:
- Rotating a PDF requires rewriting the same code every time
- Storing a script in the Skill would be helpful
Example: When designing a
Skill to handle queries like "Build a todo app for me" or "Build a dashboard to track my steps", analysis shows:
- Writing frontend web apps requires the same boilerplate HTML/React every time
- Storing an template with boilerplate HTML/React project files in the Skill would be helpful
Example: When building a
Skill to handle queries like "How many users logged in today?", analysis shows:
- Querying BigQuery requires rediscovering table schemas and relationships every time
- Storing a file documenting table schemas in the Skill would be helpful
To determine the Skill's content, analyze each concrete example to create a list of reusable resources to include: scripts, references, and assets.
Step 3: Initialize the Skill
At this point, it's time to actually create the Skill.
Skip this step only when the Skill being developed already exists and needs to be iterated on or packaged. In that case, proceed to the next step.
When creating a new Skill from scratch, always run the
script. This script conveniently generates a new template Skill directory, automatically including everything needed for the Skill, making the Skill creation process more efficient and reliable.
Usage:
bash
scripts/init_skill.py <skill-name> --path <output-directory>
The script:
- Creates a Skill directory at the specified path
- Generates a SKILL.md template with correct frontmatter and TODO placeholders
- Creates example resource directories: , , and
- Adds example files in each directory that can be customized or deleted
After initialization, customize or delete the generated SKILL.md and example files as needed.
Step 4: Edit the Skill
When editing a newly generated or existing Skill, remember that the Skill is created for use by another instance of Claude. Include information that is beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets will help another instance of Claude perform these tasks more effectively.
Learn Proven Design Patterns
Refer to these useful guides as needed for your Skill:
- Multi-step Processes: See references/workflows.md for sequential workflows and conditional logic
- Specific Output Formats or Quality Standards: See references/output-patterns.md for templates and example patterns
These files contain established best practices for effective Skill design.
Start with Reusable Skill Content
To begin implementation, start with the reusable resources identified above:
,
, and
files. Note that this step may require user input. For example, when implementing a
Skill, users may need to provide brand assets or templates to store in
, or documents to store in
.
Added scripts must be tested by actually running them to ensure there are no errors and the output meets expectations. If there are many similar scripts, only test a representative sample to ensure they all work correctly, while balancing completion time.
Any example files and directories not needed by the Skill should be deleted. The initialization script creates example files in
,
, and
to demonstrate the structure, but most Skills won't need all of them.
Update SKILL.md
Writing Guidelines: Always use imperative/infinitive form.
Frontmatter
Write YAML frontmatter with
and
:
- : Skill name
- : This is the Skill's primary trigger mechanism, helping Claude understand when to use the Skill.
- Include what the Skill does and specific triggers/contexts for using it.
- Include all "when to use" information here—not in the body. The body is only loaded after triggering, so a "when to use this Skill" section in the body won't help Claude.
- Example description for a Skill: "Comprehensive document creation, editing, and analysis with support for revision tracking, comments, format preservation, and text extraction. Use when Claude needs to handle professional documents (.docx files) for: (1) creating new documents, (2) modifying or editing content, (3) handling revision tracking, (4) adding comments, or any other document tasks"
Do not include any other fields in the YAML frontmatter.
Body
Write instructions for using the Skill and its bundled resources.
Step 5: Package the Skill
Once Skill development is complete, it must be packaged into a distributable .skill file to share with users. The packaging process automatically validates the Skill first to ensure it meets all requirements:
bash
scripts/package_skill.py <skill-folder-path>
Optional output directory specification:
bash
scripts/package_skill.py <skill-folder-path> ./dist
The packaging script will:
-
Validate the Skill automatically by checking:
- YAML frontmatter format and required fields
- Skill naming conventions and directory structure
- Description completeness and quality
- File organization and resource references
-
Package the Skill (if validation passes), creating a .skill file named after the Skill (e.g.,
) that contains all files and maintains the correct directory structure for distribution. The .skill file is a zip file with a .skill extension.
If validation fails, the script will report errors and exit without creating the package. Fix any validation errors and run the packaging command again.
Step 6: Iterate
After testing the Skill, users may request improvements. This usually happens shortly after using the Skill, when the context of its performance is fresh.
Iteration Workflow:
- Use the Skill in actual tasks
- Note difficulties or inefficiencies
- Determine how SKILL.md or bundled resources should be updated
- Implement changes and test again