Skill Creator
This skill provides guidance on creating efficient 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 assistant into a specialized one equipped with procedural knowledge that the model doesn't fully possess.
Capabilities Provided by Skills
- Specialized Workflows - Domain-specific multi-step processes
- Tool Integrations - Instructions for using specific file formats or APIs
- Domain Expertise - Company-specific knowledge, architecture, business logic
- Bundled Resources - Scripts, reference documents, and resource files for complex and repetitive tasks
Core Principles
Simplicity First
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 contextual information that Claude doesn't already possess. 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 solutions.
Medium Freedom (Pseudocode or Scripts with Parameters): Use when there's a preferred pattern, 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 exploring a path: a narrow bridge with cliffs needs 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 metadata (Required)
│ │ ├── name: (Required)
│ │ └── description: (Required)
│ └── Markdown instructions (Required)
└── Bundled Resources (Optional)
├── scripts/ - Executable code (Python/Bash, etc.)
├── references/ - Reference documents loaded into context on demand
└── assets/ - Files used in output (templates, icons, fonts, etc.)
SKILL.md (Required)
Each SKILL.md contains:
- Frontmatter (YAML): Includes and fields. These are the only fields Claude uses to determine when to use the skill, so it's crucial 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 (if at all) after the skill is triggered.
Bundled Resources (Optional)
Scripts ()
Executable code (Python/Bash, etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
- When to Include: When the same code is repeatedly rewritten or deterministic reliability is needed
- Example: for PDF rotation tasks
- Advantages: Saves tokens, 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 ()
Reference documents and materials designed to be loaded into context on demand to guide Claude's processes and thinking.
- When to Include: For documents Claude should reference while working
- Example: for financial architecture, for company NDA templates, for company policies, for API specifications
- Use Cases: Database architecture, API documentation, domain knowledge, company policies, detailed workflow guides
- Advantages: Keeps SKILL.md lean, only loaded when Claude determines it's needed
- Best Practice: If a file is large (>10k words), include grep search patterns in SKILL.md
- Avoid Duplication: Information should exist in either SKILL.md or reference files, not both. Unless it's the true core content of the skill, prioritize storing 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 references, architecture, 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
- Example: for brand assets, for PowerPoint templates,
assets/frontend-template/
- Use Cases: Templates, images, icons, boilerplate code, fonts, sample documents to be copied or modified
- Advantages: Separates output resources from documentation, allowing Claude to use files without loading them into context
Content That Should Not Be Included in Skills
Skills should only contain essential 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
- etc.
Skills should only contain the information the AI assistant needs to complete the task at hand. It should not include auxiliary context about the creation process, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files only adds confusion and ambiguity.
Progressive Disclosure Design Principles
Skills use a three-level loading system to effectively manage context:
- 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 and under 500 lines to minimize context bloat. When approaching this limit, split content into separate files. When splitting content into other files, it's crucial to reference them from SKILL.md and clearly describe when to read them, to ensure the skill's reader knows 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, sales funnel)
├── product.md (API usage, features)
└── marketing.md (Marketing campaigns, attribution)
When a user asks about sales metrics, Claude only reads sales.md.
Similarly, for skills that support 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 Document
Use docx-js to create new documents. See [DOCX-JS.md](DOCX-JS.md).
## Edit Document
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 the user needs these features.
Important Guidelines:
- Avoid Deeply Nested References - Keep references at one level deep from SKILL.md. All reference files should be directly linked from SKILL.md.
- Organize 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 includes the following steps:
- Understand the skill through concrete examples
- Plan reusable skill content (scripts, reference documents, resource files)
- 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 usage
Follow these steps in order, skipping only when there's a clear reason it doesn't apply.
Step 1: Understand the Skill Through Concrete Examples
Skip this step only if 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 editing skill, relevant questions include:
- "What features should the image editing 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'. How else do you envision this skill being used?"
- "What would a user 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 to improve effectiveness.
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 scripts, reference documents, and resource files that would be useful for repeatedly executing 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
- A script would be useful to store in the skill
Example: When designing a
skill to handle queries like "Build a to-do app for me" or "Build a step-tracking dashboard for me", analysis shows:
- Writing frontend web applications requires the same boilerplate HTML/React code every time
- An template containing boilerplate HTML/React project files would be useful to store in the skill
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
- A file documenting table schemas would be useful to store in the skill
To determine the skill's content, analyze each concrete example to create a list of reusable resources to include: scripts, reference documents, and resource files.
Step 3: Initialize the Skill
At this point, it's time to actually create the skill.
Skip this step only if the skill being developed already exists and needs to be iterated 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 that automatically includes 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 will:
- Create a skill directory at the specified path
- Generate a SKILL.md template with correct frontmatter and TODO placeholders
- Create example resource directories: , , and
- Add 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 resources will help another instance of Claude perform these tasks more effectively.
Learn Proven Design Patterns
Depending on your skill needs, refer to these useful guides:
- 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, the user 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 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 your 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 doesn'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 work with professional documents (.docx files) for: (1) creating new documents, (2) modifying or editing content, (3) using 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 first automatically validates the skill to ensure it meets all requirements:
bash
scripts/package_skill.py <path/to/skill-folder>
Optional output directory specification:
bash
scripts/package_skill.py <path/to/skill-folder> ./dist
The packaging script will:
-
Validate the skill with automatic checks:
- YAML frontmatter format and required fields
- Skill naming conventions and directory structure
- Completeness and quality of description
- 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 appropriate directory structure for distribution. A .skill file is a zip file with a .skill extension.
If validation fails, the script will report errors and exit without creating a 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 immediately after using the skill, with fresh context on how the skill performed.
Iteration Workflow:
- Use the skill on actual tasks
- Note difficulties or inefficiencies
- Determine how SKILL.md or bundled resources should be updated
- Implement changes and test again