skill-creator

Skill Creator (Skill creation guide)

This skill provides guidance for creating effective skills.

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, 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.

What Skills provide

Specialized workflows - Multi-step processes for specific domains
Tool integration - Instructions for working with specific file formats or APIs
Domain expertise - Company-specific knowledge, architecture, business logic
Bundled resources - Scripts, reference materials, and assets for complex and repetitive tasks

Core principles

Conciseness is king

The context window is a shared resource. Skills share the context window with everything else Claude needs: system prompt, conversation history, metadata of other Skills, and the actual user request.

Default assumption: Claude is already very smart. Only add context that Claude does not yet have. Question every piece of information: "Does Claude really need this explanation?" and "Is this content worth consuming these tokens?"

Prefer concise examples over lengthy explanations.

Set the appropriate degree of freedom

Match the level of specificity to the fragility and variability of the task:

High degree of freedom (text instructions): Use when multiple approaches are valid, decisions depend on context, or heuristics guide the way.

Medium degree of freedom (pseudocode or scripts with parameters): Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.

Low degree of freedom (specific scripts, few parameters): Use when operations are fragile and error-prone, consistency is critical, or a specific order must be followed.

Think of Claude as exploring a path: a narrow bridge with cliffs requires specific guardrails (low degree of freedom), while an open field allows multiple routes (high degree of freedom).

Structure of a Skill

Each skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md（必需）
│   ├── YAML frontmatter 元数据（必需）
│   │   ├── name:（必需）
│   │   └── description:（必需）
│   └── Markdown 指令（必需）
└── 捆绑资源（可选）
    ├── scripts/          - 可执行代码（Python/Bash 等）
    ├── references/       - 按需加载到上下文的文档资料
    └── assets/           - 用于输出的文件（模板、图标、字体等）

SKILL.md (required)

Each SKILL.md contains:

Frontmatter(YAML): Contains name and description fields. This is the only field Claude uses to determine when to use the skill, so it is very important to clearly and comprehensively describe what the skill is and when to use it.
Body(Markdown): Instructions and guidelines for using the skill. Loaded only after the skill is triggered.

Bundled resources (optional)

Scripts（`scripts/`）

Executable code (Python/Bash, etc.) for tasks that require deterministic reliability or repeated writing.

When to include: When the same code is written repeatedly or deterministic reliability is required
Example：scripts/rotate_pdf.py for PDF rotation tasks
Advantages: Saves tokens, deterministic, can be executed without loading into context
Note: The script may still need to be read by Claude for patching or environment-specific adjustments

References（`references/`）

Documents and reference materials loaded into context on demand to guide Claude's processing and thinking.

When to include: Documents that Claude should reference while working
Examples：references/finance.md Financial architecture,references/mnda.md Company NDA template,references/policies.md Company policies,references/api_docs.md API specifications
Use cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
Advantages: Keeps SKILL.md concise, loading only when Claude determines it is needed
Best practices: If the file is large (>10k words), include grep search patterns in SKILL.md
Avoid duplication: Information should exist only in SKILL.md or in references files, not both. Unless the information is truly core to the skill, prefer using references files to store detailed information—this keeps SKILL.md concise while making information discoverable without occupying the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference materials, architecture, and examples to references files.

Assets（`assets/`）

Files not intended to be loaded into context, but used in Claude's output.

When to include: Files that the skill needs to use in its final output
Examples：assets/logo.png Brand assets,assets/slides.pptx PowerPoint templates,assets/frontend-template/ HTML/React boilerplate,assets/font.ttf Fonts
Use cases: Templates, images, icons, boilerplate code, fonts, sample documents that are copied or modified
Advantages: Separates output resources from documentation, allowing Claude to use files without loading them into context

What should not be included in a Skill

A Skill should contain only the essential files that directly support its functionality. Do not create additional documentation or auxiliary files, including:

README.md
INSTALLATION_GUIDE.md
QUICK_REFERENCE.md
CHANGELOG.md
etc.

A Skill should contain only the information needed for the AI agent to complete the work. It should not contain auxiliary context about the creation process, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files only adds confusion.

Progressive disclosure design principles

Skills use a three-level loading system to manage context efficiently:

Metadata (name + description) - Always in context (about 100 words)
SKILL.md body - When the skill triggers (<5k words)
Bundled resources - As needed by Claude (unlimited, because scripts can be executed without being read into the context window)

Progressive disclosure patterns

Keep the SKILL.md body concise and under 500 lines to minimize context bloat. When approaching this limit, split content into separate files. When splitting content into other files, be sure to reference them from SKILL.md and clearly describe when to read them, so that readers of the skill know they exist and when to use them.

Key principles: When a skill supports multiple variants, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configurations) to separate reference files.

Pattern 1: High-level guide with references

# PDF 处理

## 快速开始

使用 pdfplumber 提取文本：
[代码示例]

## 高级功能

- **表单填写**：参见 [FORMS.md](FORMS.md) 完整指南
- **API 参考**：参见 [REFERENCE.md](REFERENCE.md) 所有方法
- **示例**：参见 [EXAMPLES.md](EXAMPLES.md) 常见模式

Claude only loads FORMS.md, REFERENCE.md, or EXAMPLES.md when needed.

Pattern 2: Organize by domain

For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:

bigquery-skill/
├── SKILL.md（概述和导航）
└── reference/
    ├── finance.md（收入、账单指标）
    ├── sales.md（商机、管道）
    ├── product.md（API 使用、功能）
    └── marketing.md（营销活动、归因）

When the 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（工作流程 + 提供商选择）
└── references/
    ├── aws.md（AWS 部署模式）
    ├── gcp.md（GCP 部署模式）
    └── azure.md（Azure 部署模式）

When the user selects AWS, Claude only reads aws.md.

Pattern 3: Conditional details

Show basic content, link to advanced content:

# DOCX 处理

## 创建文档

使用 docx-js 创建新文档。参见 [DOCX-JS.md](DOCX-JS.md)。

## 编辑文档

对于简单编辑，直接修改 XML。

**跟踪变更**：参见 [REDLINING.md](REDLINING.md)
**OOXML 详情**：参见 [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 only 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 that 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, 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 usage

Execute these steps in order, and skip them only when there is a clear reason they do not apply.

Step 1: Understand the Skill through concrete examples

Skip this step only when the skill's usage patterns are already clearly understood. Even when working with an existing skill, this step is still valuable.

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 from generated examples validated through user feedback.

For example, when building an image-editor skill, relevant questions include:

"What features should the image-editor skill support? Editing, rotating, anything else?"
"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.' Are there other ways you imagine it being used?"
"What should users say to trigger this skill?"

To avoid overwhelming the user, do not ask 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 that example from scratch
Identifying which scripts, references, and assets would help when repeatedly executing these workflows

Example: when building a pdf-editor skill that handles queries such as "help me rotate this PDF," the analysis shows:

Rotating a PDF requires rewriting the same code every time
Storing a scripts/rotate_pdf.py script in the skill would be helpful

Example: designing a frontend-webapp-builder skill, the analysis shows:

Writing a frontend webapp requires the same HTML/React boilerplate every time
Storing in the skill the assets/hello-world/ template containing boilerplate HTML/React project files would be helpful

Example: Building the big-query skill that handles queries like "How many users logged in today?", the analysis shows:

Querying BigQuery requires rediscovering table schemas and relationships every time
Storing in the skill the references/schema.md file that records table schemas would be helpful

To determine the skill's content, analyze each specific example to create a list of reusable resources to include: scripts, references, and assets.

Step 3: Initialize the Skill

At this point, it is time to actually create the skill.

Only skip this step if 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 init_skill.py script. This script conveniently generates a new template skill directory that automatically includes everything the skill needs, making the skill creation process more efficient and reliable.

Usage:

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

This script:

Creates the skill directory at the specified path
Generates a SKILL.md template with the correct frontmatter and TODO placeholders
Creates example resource directories:scripts/、references/ and assets/
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 skill (newly generated or existing), remember that the skill is created for use by another Claude instance. Include information that is beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance perform these tasks more effectively.

Learn proven design patterns

Consult these useful guides based on the skill's needs:

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 start implementing, begin with the reusable resources identified above:scripts/、references/ and assets/ files. Note that this step may require user input. For example, when implementing the brand-guidelines skill, the user may need to provide brand assets or templates stored in assets/ , or documentation stored in references/ .

Added scripts must be tested by actually running them to ensure there are no bugs and that the output meets expectations. If there are many similar scripts, just test a representative sample to make sure they all work, while balancing completion time.

Any example files and directories not needed for the skill should be deleted. The initialization script creates example files in scripts/、references/ and assets/ to demonstrate the structure, but most skills do not need all of them.

Update SKILL.md

Writing guidelines: Always use the imperative/infinitive form.

Frontmatter

Write YAML frontmatter containing name and description YAML frontmatter:

name: skill name
description: This is the main trigger mechanism for the skill, helping Claude understand when to use the skill.
- Includes what the skill does and the specific triggers/context for when to use it.
- Include all "when to use" information here - do not put it in the body. The body is only loaded after triggering, so a "When to use this Skill" section in the body is not helpful to Claude.
- docx Example skill description: "Comprehensive document creation, editing, and analysis with support for tracked changes, 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) handling tracked changes, (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

After development is complete, the skill 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:

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

Optional output directory specification:

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

The packaging script will:

Validate the skill, automatically checking:
- YAML frontmatter format and required fields
- Skill naming conventions and directory structure
- Description completeness and quality
- File organization and resource references
If validation passes, thenpackage the skill, creating a .skill file named after the skill (e.g., my-skill.skill), containing all files while maintaining the appropriate directory structure for distribution. A .skill file is a zip file with a .skill extension.

If validation fails, the script will report the error and exit without creating a package. After fixing all validation errors, 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 the skill's performance is still fresh.

Iteration workflow:

Use the skill in real tasks
Notice difficulties or inefficiencies
Identify how SKILL.md or bundled resources should be updated
Implement changes and test again