Skill Creator

This Skill provides guidance for creating effective Skills.

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing professional knowledge, workflows and tools. You can think of them as "onboarding guides" for specific domains or tasks — they transform Claude from a general Agent into a specialized Agent equipped with procedural knowledge that no model can fully possess innately.

What Skills Provide

Professional workflows - Multi-step processes for specific domains
Tool integration - 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

Conciseness is Key

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

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

Prioritize concise examples over lengthy explanations.

Set Appropriate Levels of Freedom

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

High freedom (text-based instructions): Used when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.

Medium freedom (pseudocode or scripts with parameters): Used when there is a preferred pattern, certain variation is acceptable, or configuration affects behavior.

Low freedom (specific scripts, minimal parameters): Used when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.

Think of Claude as exploring paths: a narrow bridge on the edge of a cliff 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（必需）
│   ├── 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 it should be used.
Body (Markdown): Instructions and guidance for using the Skill. It is only loaded after the Skill is triggered (if it is triggered).

Bundled Resources (Optional)

Scripts (

scripts/

)

Executable code (Python/Bash, etc.) for tasks that require deterministic reliability or are written repeatedly.

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 being loaded into context
Note: Scripts may still need to be read by Claude for patching or environment-specific adjustments

References (

references/

)

Documents and reference materials intended to be loaded into context as needed to guide Claude's processes and thinking.

When to include: For documents Claude should refer to when working
Examples:
```
references/finance.md
```
for financial models,
```
references/mnda.md
```
for company NDA templates,
```
references/policies.md
```
for company policies,
```
references/api_docs.md
```
for API specifications
Use cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
Advantages: Keeps SKILL.md lean, only loaded when Claude determines it is needed
Best practice: If the 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 the information is truly core to 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 reference materials, patterns and examples to reference files.

Assets (

assets/

)

Files that are not intended to be loaded into context, but are used in outputs generated by Claude.

When to include: When the Skill requires files to be used in final outputs
Examples:
```
assets/logo.png
```
for brand assets,
```
assets/slides.pptx
```
for PowerPoint templates,
```
assets/frontend-template/
```
for HTML/React boilerplate,
```
assets/font.ttf
```
for typography
Use cases: Templates, images, icons, boilerplate code, fonts, sample documents that are copied or modified
Advantages: Separates output resources from documentation, allows Claude to use files without loading them into context

Content That Should Not Be Included in Skills

Skills should only contain necessary files that directly support their functionality. Do not create irrelevant documentation or auxiliary files, including:

README.md
INSTALLATION_GUIDE.md
QUICK_REFERENCE.md
CHANGELOG.md
Etc.

Skills should only contain information required by the AI Agent 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 increases clutter and confusion.

Progressive Disclosure Design Principle

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

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

Progressive Disclosure Patterns

Keep the SKILL.md body lean, controlled within 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting content into other files, be sure 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 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

markdown

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

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

Pattern 3: Conditional details

Display basic content, link to advanced content:

markdown

# 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 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 usage

Execute these steps in order, skipping only when there is a clear reason why they do not 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 existing Skills.

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, what else?"
"Can you give some examples of how this Skill will be used?"
"I can imagine users asking 'remove red-eye from this image' or 'rotate this image'. Are there other use cases you envision?"
"What should 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 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 translate 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 be helpful when repeating these workflows

Example: When building the

pdf-editor

Skill to handle queries such as "help me rotate this PDF", analysis shows:

Rotating PDFs requires rewriting the same code every time
Storing the
```
scripts/rotate_pdf.py
```
script in the Skill would be helpful

Example: When designing the

frontend-webapp-builder

Skill to handle queries such as "build me a to-do app" or "build me a dashboard to track step count", analysis shows:

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

Example: When building the

big-query

Skill to handle queries such as "how many users logged in today?", analysis shows:

Querying BigQuery requires rediscovering table schemas and relationships every time
Storing the
```
references/schema.md
```
file documenting table schemas in the Skill would be helpful

To determine the content of the Skill, 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 is time to actually create the Skill.

Skip this step only if the Skill being developed already exists and needs iteration or packaging. In this 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 required for a Skill, making the Skill creation process more efficient and reliable.

Usage:

bash

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 correct frontmatter and TODO placeholders
Creates sample resource directories:
```
scripts/
```
,
```
references/
```
and
```
assets/
```
Adds sample files in each directory that can be customized or deleted

After initialization, customize or delete the generated SKILL.md and sample 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 Claude instance. Include information that is beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details or reusable assets can help another Claude instance perform these tasks more effectively.

Learn proven design patterns

Refer to these helpful guides based on the Skill's requirements:

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 implementation, 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 to store in

assets/

, or documents to store in

references/

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 sample files and directories not required by the Skill should be deleted. The initialization script creates sample files in

scripts/

references/

and

assets/

to demonstrate the structure, but most Skills do not need all of them.

Update SKILL.md

Writing guideline: Always use imperative/infinitive form.

Frontmatter

Write YAML frontmatter with

name

and

description

```
name
```
: Skill name
```
description
```
: This is the main trigger mechanism for the Skill, helping Claude understand when to use the Skill.
- Include what the Skill does and 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 for Claude.
- Example description for the
```
docx
```
  Skill: "Comprehensive document creation, editing and analysis with support for revision tracking, comments, format preservation and text extraction. Used when Claude needs to process professional documents (.docx files): (1) create new documents, (2) modify or edit content, (3) handle revision tracking, (4) add 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 4.5: Evaluate the need for .claude/rules/ summary

If the Skill contains specifications that should be followed globally (such as coding standards, architecture conventions), you need to create a summary file under

.claude/rules/

to ensure these specifications are automatically loaded in each session.

Judgment criteria:

Condition	Requires rules summary	Not required
Includes coding specifications	✅ e.g. naming conventions, architecture conventions	❌ Pure workflow
Includes global constraints	✅ e.g. prohibited operations, mandatory rules	❌ Limited to specific scenarios
Required for every session	✅ e.g. code style, commit specifications	❌ Can be triggered on demand

If required:

Create a corresponding
```
.md
```
file under
```
.claude/rules/
```
File name format:
```
{skill-name}-rules.md
```
Content: Only include specification summaries (no more than 20 lines), reference the Skill for details

Summary file example:

markdown

# spec-writer 规范摘要
- Spec 必须放入 01-05 分类目录
- 文件夹命名：YYYYMMDD-HHMM-中文任务描述
- 文件名固定为 plan.md
- 详细规范见 spec-writer Skill

If not required: Skip this step, the Skill is only loaded on demand through the trigger mechanism.

Step 5: Package the Skill

After Skill development is complete, it must be packaged into a distributable .skill file to share with users. The packaging process automatically verifies the Skill first 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:

Automatically verify the Skill, checking:
- YAML frontmatter format and required fields
- Skill naming conventions and directory structure
- Completeness and quality of the description
- File organization and resource references
Package the Skill if verification passes, creating a .skill file named after the Skill (e.g.
```
my-skill.skill
```
) containing all files and maintaining the correct directory structure for distribution. .skill files are zip files with the .skill extension.

If verification fails, the script will report an error and exit without creating the package. Fix any verification 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 there is fresh context about the Skill's performance.

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

Follow-up Actions (Tool Memory)

After completing Skill creation/editing, you should:

Verification Steps

Check that the frontmatter of SKILL.md is complete (name, description are required)
Confirm that the description includes trigger conditions for "when to use"
Verify that all referenced resource files (scripts/, references/, assets/) exist
If there are scripts, run tests to ensure no errors
If the Skill contains global specifications, check that there is a corresponding summary file under
```
.claude/rules/
```
If there is a summary file, confirm that the summary content is consistent with the Skill body (avoid information desynchronization)

Quality Checks

Is the SKILL.md body controlled within 500 lines?
Is content duplication with references/ files avoided?
Are unnecessary sample files and directories deleted?
Do longer reference files have a table of contents?

Packaging and Distribution

Run
```
scripts/package_skill.py <skill-folder>
```
to package
If verification fails, fix according to the error message and repackage
Share the generated
```
.skill
```
file with the user

Common Pitfalls

Missing trigger conditions in the description, causing the Skill not to be called automatically
Writing "when to use this Skill" in the body (should be written in the description)
Creating unnecessary auxiliary files such as README.md
Packaging and distributing scripts without testing

skill-creator

NPX Install

Tags

SKILL.md Content (Chinese)

Skill Creator

About Skills

What Skills Provide

Core Principles

Conciseness is Key

Set Appropriate Levels of Freedom

Skill Structure

SKILL.md (Required)

Bundled Resources (Optional)

Scripts (
`scripts/`
)

References (
`references/`
)

Assets (
`assets/`
)

Content That Should Not Be Included in Skills

Progressive Disclosure Design Principle

Progressive Disclosure Patterns

Skill Creation Process

Step 1: Understand the Skill through concrete examples

Step 2: Plan reusable Skill content

Step 3: Initialize the Skill

Step 4: Edit the Skill

Learn proven design patterns

Start with reusable Skill content

Update SKILL.md

Frontmatter

Body

Step 4.5: Evaluate the need for .claude/rules/ summary

Step 5: Package the Skill

Step 6: Iterate

Follow-up Actions (Tool Memory)

Verification Steps

Quality Checks

Packaging and Distribution

Common Pitfalls

skill-creator

NPX Install

Tags

SKILL.md Content (Chinese)

Skill Creator

About Skills

What Skills Provide

Core Principles

Conciseness is Key

Set Appropriate Levels of Freedom

Skill Structure

SKILL.md (Required)

Bundled Resources (Optional)

Scripts (scripts/)

References (references/)

Assets (assets/)

Content That Should Not Be Included in Skills

Progressive Disclosure Design Principle

Progressive Disclosure Patterns

Skill Creation Process

Step 1: Understand the Skill through concrete examples

Step 2: Plan reusable Skill content

Step 3: Initialize the Skill

Step 4: Edit the Skill

Learn proven design patterns

Start with reusable Skill content

Update SKILL.md

Frontmatter

Body

Step 4.5: Evaluate the need for .claude/rules/ summary

Step 5: Package the Skill

Step 6: Iterate

Follow-up Actions (Tool Memory)

Verification Steps

Quality Checks

Packaging and Distribution

Common Pitfalls

Scripts (
`scripts/`
)

References (
`references/`
)

Assets (
`assets/`
)