SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsskill-creator

skill-creator

Agents & models

View repository

Updated 10-16 09:20

About this skill

Skill Creator

This skill provides guidance on 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 that no model can fully possess.

What Skills Provide

  1. Specialized workflows - Multi-step processes for specific domains
  2. Tool integrations - Instructions for handling specific file formats or APIs
  3. Domain expertise - Company-specific knowledge, patterns, business logic
  4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks

Core Principles

Conciseness Is Key

The context window is a public 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 Claude does not already have. Question every piece of information: "Does Claude really need this explanation?" and "Is this text worth its token cost?"

Prefer concise examples over lengthy explanations.

Set Appropriate Degrees of Freedom

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

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

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 needs 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 前置元数据（必需）
│   │   ├── name:（必需）
│   │   └── description:（必需）
│   └── Markdown 说明（必需）
└── 捆绑资源（可选）
    ├── scripts/          - 可执行代码（Python/Bash 等）
    ├── references/       - 根据需要加载到上下文中的文档
    └── assets/           - 用于输出的文件（模板、图标、字体等）

SKILL.md (required)

Each SKILL.md contains:

  • Frontmatter(YAML): Contains the 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. Loaded only 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: For PDF rotation tasks, scripts/rotate_pdf.py
  • Advantages: High token efficiency, strong determinism, 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 used to load into context as needed to guide Claude's process and thinking.

  • When to include: For documents that Claude should reference while working
  • Examples: For financial models references/finance.md, for company NDA templates references/mnda.md, for company policies references/policies.md, for API specifications references/api_docs.md
  • 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 reference files, not both. Unless the information is truly core to the skill, prefer placing detailed information in reference files—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, patterns, and examples to reference files.
Assets (assets/）

Files not intended to be loaded into context, but used in the output produced by Claude.

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

What should not be included in skills

Skills should contain only the 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
  • etc.

Skills should contain only the information needed for the AI agent to complete the task at hand. It should not contain 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 effectively manage context:

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

Progressive disclosure patterns

Keep SKILL.md body concise, no more than 500 lines, to minimize context bloat. When approaching this limit, split content into separate files. When splitting content into other files, it is important to reference them from SKILL.md and clearly describe when to read them, to ensure the skill's readers 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 (schemas, examples, configuration) to separate reference files.

Pattern 1: Advanced guide with references

# PDF 处理

## 快速入门

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

## 高级功能

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

Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only 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（概述和导航）
└── reference/
    ├── finance.md（收入、账单指标）
    ├── sales.md（机会、管道）
    ├── product.md（API 使用、功能）
    └── marketing.md（活动、归因）

When the user asks about sales metrics, Claude reads only 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 reads only 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 reads REDLINING.md or OOXML.md only when the user needs 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 longer than 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 involves the following steps:

  1. Understand the skill through concrete examples
  2. Plan reusable skill content (scripts, references, assets)
  3. Initialize the skill (run init_skill.py)
  4. Edit the skill (implement resources and write SKILL.md)
  5. Package the skill (run package_skill.py)
  6. Iterate based on actual usage

Follow these steps in order, skipping them only when there is a clear reason that 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 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, rotating, and anything else?"
  • "Can you give some examples of how this skill would be used?"
  • "I can imagine users asking for 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 the user, 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 there is a clear understanding of the features the skill should support.

Step 2: Plan reusable skill content

To turn specific examples into effective skills, analyze each example by:

  1. Considering how to execute the example from scratch
  2. Identifying what scripts, references, and assets would be helpful when repeatedly executing these workflows

Example: When building the pdf-editor skill to handle queries such as "help me rotate this PDF", the analysis shows:

  1. Rotating a PDF requires rewriting the same code every time
  2. 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 that tracks my steps", the analysis shows:

  1. Writing a front-end web app requires the same boilerplate HTML/React every time
  2. 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?", the analysis shows:

  1. Querying BigQuery requires rediscovering the table schema and relationships every time
  2. Storing the references/schema.md file documenting the table schema in the skill would be helpful

To determine the contents of the skill, 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.

Skip this step only if the skill being developed already exists and needs iteration or packaging. In that case, continue 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, automatically including everything the skill needs, making the skill creation process more efficient and reliable.

Usage:

scripts/init_skill.py <技能名称> --path <输出目录>

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 (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 would help another Claude instance execute 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 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 brand-guidelines For skills, users may need to provide brand assets or templates stored in assets/ , or documents stored 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, just test a representative sample to ensure they all work properly while balancing completion time.

Any example files and directories not needed by 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 with name and description :

  • name: skill name
  • description: This is the skill's primary trigger mechanism, helping Claude understand when to use the skill.
    • Include what the skill does and the 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 is not helpful to Claude.
    • docx Example description for the skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting 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 task"

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 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:

scripts/package_skill.py <技能文件夹路径>

Optional output directory specification:

scripts/package_skill.py <技能文件夹路径> ./dist

The packaging script will:

  1. Validatethe skill automatically, checking:

    • YAML frontmatter format and required fields
    • Skill naming conventions and directory structure
    • Description completeness and quality
    • File organization and resource references

  2. Packagethe skill (if validation passes), creating a .skill file named after the skill (e.g., my-skill.skill), containing all files and preserving the correct directory structure for distribution. A .skill file is a zip file with the extension .skill.

If validation fails, the script will report the error and exit without creating a package. Fix any validation errors and run the packaging command again.

Step 6: Iterate

After testing the skill, the user may request improvements. This usually happens shortly after using the skill, with fresh context on how the skill performed.

Iteration workflow:

  1. Use the skill in a real task
  2. Note difficulties or inefficiencies
  3. Determine how SKILL.md or bundled resources should be updated
  4. Implement the changes and test again