SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsskill-creator

skill-creator

Agents & models

View repository

Updated 10-16 08:42

About this skill

Skill Creator

This Skill provides the methods and process for "how to write an effective Skill."

About Skill

A Skill is a modular, reusable "guidance package" that, by providing specialized knowledge, workflow, tools, and resources, turns Claude from a general-purpose assistant into a specialized assistant with process-oriented capabilities.

What Skill provides

  1. Specialized workflow: multi-step processes for specific domains
  2. Tool integration: operational guidance for specific file formats / APIs
  3. Domain expertise: company/business-specific knowledge, schema, business logic
  4. Bundled resources: used for repetitive tasks scripts/、references/、assets/

Core principles

Conciseness first

The context window is a shared resource: the system prompt, conversation history, other Skill metadata, and user needs all have to share it.

Default assumption: Claude is already very smart. Only add information that Claude realistically "cannot get." For every passage of text, ask yourself:

  • "Does Claude really need this explanation?"
  • "Is the token cost of this text worth it?"

Prefer short examples and executable steps, and avoid lengthy narration.

Set appropriate Degrees of Freedom

Decide how specific the instructions should be based on the task's "fragility" and "variability":

  • High degrees of freedom (plain text guidance): use when there are many viable options, decisions depend on context, and heuristic judgment is needed
  • Medium degrees of freedom (pseudocode / configurable scripts): use when there are recommended patterns, limited variants are allowed, and configuration affects behavior
  • Low degrees of freedom (explicit scripts + a few parameters): use when the process is error-prone, strong consistency is required, and execution must follow a fixed order

You can think of Claude as "walking": a narrow bridge with cliffs on both sides needs stronger guardrails (low degrees of freedom); an open meadow allows more routes (high degrees of freedom).

Skill composition structure

Each skill consists of the required SKILL.md and optional resource directories:

skill-name/
├── SKILL.md（必需）
│   ├── YAML frontmatter metadata（必需）
│   │   ├── name:（必需）
│   │   └── description:（必需）
│   └── Markdown instructions（必需）
└── Bundled resources（可选）
    ├── scripts/          - 可执行代码（Python/Bash 等）
    ├── references/       - 需要时加载的参考文档
    └── assets/           - 用于输出的文件（模板、图标、字体等）

SKILL.md(required)

SKILL.md contains:

  • Frontmatter（YAML）: contains name and description. Claude mainly relies on them to determine whether to trigger the skill, so be sure to clearly describe "what it does + when to use it."
  • Body（Markdown）: the skill's specific instructions and how to use resources. Usually loaded only after the skill is triggered (if the platform supports it).

Bundled resources (optional)

scripts/

Used for tasks that require determinism and repeatable execution (Python/Bash, etc.).

  • Applicable scenarios: the same code is rewritten repeatedly, or higher determinism is needed
  • Example：scripts/rotate_pdf.py(rotate PDF)
  • Benefits: saves tokens, repeatable, directly executable (no need to read everything into context)
  • Note: scripts may still need to be read in order to patch them or adapt them to the environment
references/

Reference material loaded on demand, used to support Claude's reasoning and decision-making.

  • Applicable scenarios: documentation that Claude needs to consult while performing a task
  • Example：references/schema.md(table structure),references/api_docs.md(API documentation),references/policies.md(policies/standards)
  • Benefits: keep SKILL.md concise; load only when needed
  • Best practices: if the file is very large (>10k words), provide grep/search hints in SKILL.md Avoid duplication
  • Avoid duplication: information should either go in SKILL.md, or go in references/; put details preferentially in references/，SKILL.md keep only key processes and navigation
assets/

Files that do not need to be read into context but will be copied/referenced into the output.

  • Applicable scenarios: the skill needs templates, images, icons, fonts, boilerplate, etc.
  • Examples：assets/logo.png、assets/slides.pptx、assets/frontend-template/
  • Benefits: separate "resources for output" from "documentation" to reduce context pressure

What not to put in a Skill

A Skill should contain only the necessary files that support its functionality. Do not add irrelevant documentation/auxiliary files, for example:

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

These "human documents" create noise and maintenance costs. The goal of a Skill is to enable an AI agent to complete tasks more reliably, not to record the writing process or serve as a user-facing manual.

Progressive Disclosure

Use a three-layer structure to control context:

  1. Metadata（name + description）: always in context (~100 words)
  2. SKILL.md body: loaded after the skill is triggered (recommended <5k words)
  3. Bundled resources: loaded only when needed (scripts can be executed directly, reference documents are read on demand)

Common patterns of Progressive Disclosure

Try to keep SKILL.md within the necessary range (recommended <500 lines) to avoid context bloat. When approaching the limit, split details into separate files and clearly specify "when to read" in SKILL.md Key principles:

Key principles: When a skill supports multiple variants/frameworks/options,SKILL.md keep only the core process and selection guidance; put variant details (patterns, examples, config) into references/。

Pattern 1: High-level navigation + references

# PDF 处理

## Quick start

用 pdfplumber 提取文本：
[code example]

## Advanced features

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

Load only when needed FORMS.md / REFERENCE.md / EXAMPLES.md。

Pattern 2: Split by business domain

When a skill covers multiple domains, split by domain to avoid loading irrelevant content:

bigquery-skill/
├── SKILL.md（概览与导航）
└── reference/
    ├── finance.md（revenue、billing metrics）
    ├── sales.md（opportunities、pipeline）
    ├── product.md（API usage、features）
    └── marketing.md（campaigns、attribution）

When the user asks about sales metrics, read only sales.md。

Similarly, deployment-type skills that support multiple providers can also be split by provider:

cloud-deploy/
├── SKILL.md（workflow + provider selection）
└── references/
    ├── aws.md（AWS deployment patterns）
    ├── gcp.md（GCP deployment patterns）
    └── azure.md（Azure deployment patterns）

Pattern 3: Conditional details

First give the basic approach, then link to advanced content:

# DOCX 处理

## Creating documents

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

## Editing documents

简单修改可以直接改 XML。

**涉及 tracked changes**：见 [REDLINING.md](REDLINING.md)
**涉及 OOXML 细节**：见 [OOXML.md](OOXML.md)

Important recommendations:

  • Avoid reference chains that are too deep: reference files should preferably all be directly linked from SKILL.md (keep one level of depth).
  • Long references should be structured: files longer than 100 lines should preferably include a table of contents for quick preview and locating.

Skill creation process

Skill creation usually proceeds through the following steps:

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

Execute in order; skip a step only when it is clearly not applicable.

Step 1: Understand the Skill with concrete examples

Skip only when the usage is already very clear; even when iterating on an existing skill, this step is usually still valuable.

To write an effective skill, you must first clarify how it will be used: this can come from real examples provided by the user, or you can generate examples and have the user confirm them.

For example: to make an image-editor skill, you can ask:

  • "What features does this image-editor skill need to support? Cropping, rotating, color adjustment, red-eye removal... anything else?"
  • "Can you give me some examples of how you would use it?"
  • "The trigger phrases I can think of are: 'help me remove red-eye from a photo', 'rotate this image 90 degrees'. How else would you phrase it?"
  • "What kind of phrasing should trigger this skill?"

Avoid asking too many questions at once; ask the most critical ones first, and fill in the rest later.

End this step when you have a clear consensus on "the boundaries of the features to support".

Step 2: Plan reusable contents

When turning concrete examples into skill content, do two things for each example:

  1. Execute it once from scratch (in your head/on paper) — how would you do it?
  2. Determine which scripts/、references/、assets/ can make repeated execution faster and more reliable

Example: when doing pdf-editor(the user asks "help me rotate this PDF"), you will find:

  1. Rotating a PDF requires repeatedly writing the same code
  2. Suitable to consolidate into scripts/rotate_pdf.py

Example: when doing frontend-webapp-builder(the user asks "make a todo app / make a dashboard"), you will find:

  1. Frontend projects always require repeatedly writing the same boilerplate (HTML/React, etc.)
  2. Suitable to prepare a assets/hello-world/ template directory

Example: when doing big-query(the user asks "how many users logged in today?"), you will find:

  1. You have to rediscover the table schema and relationships every time
  2. Suitable to write references/schema.md to record the schema

Go through all the examples, and finally obtain a list of "which reusable resources to include".

Step 3: Initialize Skill

If you are creating a skill from scratch,alwaysfirst run init_skill.py. It will generate a template directory containing the required structure, reducing omissions and rework.

Skip this step and proceed to the next step only when the skill already exists and you are iterating/packaging it.

Usage:

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

This script will:

  • Create the skill directory at the specified path
  • Generate a SKILL.md template with TODO placeholders (including the correct frontmatter)
  • Create example resource directories:scripts/、references/、assets/
  • Place example files in each directory that can be modified/deleted as needed

After initialization, modify or delete the example files and directories as needed.

Step 4: Edit Skill

When editing a (newly generated or existing) skill, remember: you are writing instructions for "another Claude instance". Only include information that is helpful to Claude and not obvious: procedural knowledge, domain details, reusable assets, etc.

Learn mature design patterns

Refer to the following guidelines based on the skill type:

  • Multi-step processes: see references/workflows.md(sequential processes and conditional branches)
  • Specific output formats/quality standards: see references/output-patterns.md(template and example pattern)

Start with reusable resources

prioritize implementing the scripts/、references/、assets/. This step may require the user to provide materials: for example, brand-guidelines skill requires the user to provide brand resources to place in assets/, or provide documents to place in references/。

Newly added scripts must be "actually run" to verify that the output meets expectations; if there are many similar scripts, at least run a representative sample to build confidence (balancing time cost).

Unneeded example files/directories should be deleted. The template directory is only to demonstrate the structure; most skills will not use all of the content.

Update SKILL.md

Writing requirements: Use imperative/infinitive forms uniformly (for example, "check... / run... / generate...").

Frontmatter

SKILL.md The YAML frontmatter at the top only contains name and description：

  • name: skill name
  • description: the skill's main trigger mechanism, used to tell Claude "when to use it"
    • It is necessary to clearly state both "what it does" and "trigger scenarios/context"
    • All "when to use" information should be placed here, not in the body (the body is only loaded after triggering)
    • Example (docx skill's description):
      • "Professional document (.docx) creation/editing/analysis supporting tracked changes, comments, format preservation, and text extraction. Use when Claude needs to handle .docx: creating, modifying, handling tracked changes, adding comments, and similar scenarios."

Do not add other fields in the frontmatter.

Body

In the body, clearly explain: how to use the skill and how to use its bundled resources.

Step 5: Package the Skill

After development is complete, it needs to be packaged into a distributable .skill file. The packaging script will first automatically verify whether the skill meets the requirements:

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

You can also specify the output directory:

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

The packaging script will:

  1. Validate: check
    • YAML frontmatter format and required fields
    • skill naming conventions and directory structure
    • completeness and quality of the description
    • file organization and resource references
  2. Package: after verification passes, generate a file named after the skill directory name .skill file (such as my-skill.skill), and maintain the correct distribution directory structure (essentially zip + .skill extension).

If verification fails, output an error and exit; no package will be generated. After fixing, rerun the packaging command.

Step 6: Iterate

After a skill is used in a real task, users usually immediately suggest improvements (at this point the context is the most current and the feedback is the most specific).

Iteration workflow:

  1. Use the skill in a real task
  2. Observe bottlenecks/inefficiencies
  3. Determine how to update SKILL.md or bundled resources
  4. Test again after modification