Back to Details

skill-creator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Creator

Skill Creator

Status: Production Ready Last Updated: 2026-01-09 Dependencies: None Reference: Anthropic's skill-creator
状态: 可用于生产环境 最后更新: 2026-01-09 依赖: 无 参考链接: Anthropic's skill-creator

Quick Start

快速开始

To scaffold a new skill, use the 
/create-skill
command:
/create-skill my-new-skill
To design an effective skill, continue reading this guide.
要快速搭建新技能，使用
/create-skill
命令：
/create-skill my-new-skill
要设计高效的技能，请继续阅读本指南。

Core Principles

核心原则

1. The Context Window is a Public Good

1. 上下文窗口是公共资源

Every token in your skill competes with conversation context. Be ruthlessly concise.
Ask for each paragraph:
  • Does Claude genuinely need this?
  • Could this be in 
    references/
    instead of main SKILL.md?
  • Is this duplicating information Claude already knows?
技能中的每个Token都会与对话上下文竞争资源。请务必保持极度简洁。
对每个段落提问:
  • Claude真的需要这些信息吗?
  • 能否将其放在
    references/
    目录而非主SKILL.md中?
  • 这些信息是否与Claude已有的知识重复?

2. Progressive Disclosure

2. 渐进式信息披露

Load information in layers:
LayerWhen LoadedTarget SizeContent
MetadataAlways40-55 tokensname + description
SKILL.mdWhen triggered<5k wordsInstructions, patterns
ResourcesAs neededVariablescripts/, references/, assets/
分层加载信息：
层级加载时机目标大小内容
元数据始终加载40-55个Token名称 + 描述
SKILL.md触发技能时<5000字说明、模式
资源文件需要时加载可变scripts/, references/, assets/

3. Freedom Levels

3. 自由度等级

Match instruction specificity to error probability:
High Freedom (text instructions)
  • For flexible approaches where multiple solutions work
  • Example: "Structure components for reusability"
Medium Freedom (pseudocode/patterns)
  • For preferred patterns with some flexibility
  • Example: Show a pattern with 
    [CUSTOMIZE]
    placeholders
Low Freedom (specific scripts/templates)
  • For fragile operations where exact steps matter
  • Example: Exact wrangler.jsonc configuration for D1 binding
根据错误概率匹配指令的具体程度：
高自由度（文本指令）
  • 适用于存在多种可行解决方案的灵活场景
  • 示例: "为可复用性构建组件"
中自由度（伪代码/模式）
  • 适用于有首选模式但保留一定灵活性的场景
  • 示例: 展示带有
    [CUSTOMIZE]
    占位符的模式
低自由度（特定脚本/模板）
  • 适用于步骤精确性要求极高的易出错操作
  • 示例: 用于D1绑定的精确wrangler.jsonc配置

Writing Effective Descriptions

撰写有效的技能描述

The description is the most critical part - it determines if your skill gets discovered.
描述是最关键的部分——它决定了你的技能能否被发现。

Target: 250-350 Characters

目标: 250-350字符

yaml
undefined
yaml
undefined

Too short (loses context):

过短（缺失上下文）:

description: "A skill for Tailwind" # ❌ 25 chars
description: "A skill for Tailwind" # ❌ 25个字符

Too long (wastes tokens):

过长（浪费Token）:

description: "This comprehensive skill provides detailed knowledge..." # ❌ 500+ chars
description: "This comprehensive skill provides detailed knowledge..." # ❌ 500+字符

Just right:

恰到好处:

description: | Build modern UIs with Tailwind v4 + shadcn/ui. Covers CSS variable theming, component installation, dark mode, and semantic color tokens.
Use when: setting up Tailwind v4, adding shadcn components, fixing theme issues, or troubleshooting "Cannot find module" errors.
undefined
description: | Build modern UIs with Tailwind v4 + shadcn/ui. Covers CSS variable theming, component installation, dark mode, and semantic color tokens.
Use when: setting up Tailwind v4, adding shadcn components, fixing theme issues, or troubleshooting "Cannot find module" errors.
undefined

Two-Paragraph Structure

两段式结构

Paragraph 1: What you can build + key features (active voice) Paragraph 2: When to use + error keywords for discovery
第一段: 可实现的功能 + 核心特性（主动语态） 第二段: 适用场景 + 用于发现的错误关键词

Description Checklist

描述检查清单

  • Active voice ("Build X" not "This skill provides X")
  • Specific technologies named
  • 3-5 "Use when" scenarios
  • 2-3 distinctive error messages/keywords
  • No meta-commentary about the skill itself
  • 250-350 characters total
  • 使用主动语态（"构建X"而非"本技能提供X"）
  • 明确提及具体技术
  • 3-5个"适用场景"
  • 2-3个独特的错误消息/关键词
  • 无关于技能本身的元评论
  • 总长度250-350字符

Bad vs Good Examples

反面与正面示例

yaml
undefined
yaml
undefined

❌ Bad: Passive, vague, no discovery keywords

❌ 反面示例: 被动语态、模糊、无发现关键词

description: | This skill helps you with database operations. It provides patterns for working with data and can be useful in many situations.
description: | This skill helps you with database operations. It provides patterns for working with data and can be useful in many situations.

✅ Good: Active, specific, discoverable

✅ 正面示例: 主动语态、具体、易被发现

description: | Build type-safe database queries with Drizzle ORM and Cloudflare D1. Covers schema definition, migrations, relations, and transaction patterns.
Use when: setting up D1 database, writing Drizzle schemas, debugging "no such table" or "D1_ERROR" issues.

---
description: | Build type-safe database queries with Drizzle ORM and Cloudflare D1. Covers schema definition, migrations, relations, and transaction patterns.
Use when: setting up D1 database, writing Drizzle schemas, debugging "no such table" or "D1_ERROR" issues.

---

Skill Structure

技能结构

Required Files

必需文件

skills/my-skill/
├── SKILL.md          # Main documentation (required)
└── README.md         # Auto-trigger keywords (required)
skills/my-skill/
├── SKILL.md          # 主文档（必需）
└── README.md         # 自动触发关键词（必需）

Optional Resources

可选资源

skills/my-skill/
├── scripts/          # Executable helpers
│   └── setup.sh      # Example: automated setup script
├── references/       # Extended documentation
│   └── api-guide.md  # Loaded when user needs deep details
└── assets/           # Templates, images
    └── config.json   # Template files for output
skills/my-skill/
├── scripts/          # 可执行辅助脚本
│   └── setup.sh      # 示例: 自动化安装脚本
├── references/       # 扩展文档
│   └── api-guide.md  # 用户需要深度信息时加载
└── assets/           # 模板、图片
    └── config.json   # 输出用模板文件

When to Use Each

各目录适用场景

scripts/: Deterministic tasks that must be exact
  • Database migrations
  • Project scaffolding
  • Configuration generation
references/: Extended documentation too long for SKILL.md
  • Full API references
  • Comprehensive troubleshooting guides
  • Migration guides between versions
assets/: Template files for output
  • Configuration file templates
  • Boilerplate code
  • Images/diagrams
scripts/: 必须精确执行的确定性任务
  • 数据库迁移
  • 项目搭建
  • 配置生成
references/: 内容过长不适合放入SKILL.md的扩展文档
  • 完整API参考
  • 全面的故障排除指南
  • 版本间迁移指南
assets/: 输出用模板文件
  • 配置文件模板
  • 样板代码
  • 图片/图表

YAML Frontmatter

YAML 前置元数据

Required Fields

必需字段

yaml
---
name: lowercase-hyphen-case
description: |
  [250-350 chars with "Use when:" section]
---
yaml
---
name: lowercase-hyphen-case
description: |
  [250-350字符，包含"Use when:"部分]
---

Optional Fields

可选字段

yaml
---
name: my-skill
description: |
  [description - max 1024 chars]
allowed-tools:
  - Bash
  - Read
  - Write
---
Note: 
allowed-tools
is an optional field to restrict which tools Claude can use. The 
metadata:
field with 
keywords:
array is commonly used in this repository for improved discoverability, though it's not officially documented in the Anthropic spec. Fields like 
license:
are informational but not functionally used by Claude Code.
yaml
---
name: my-skill
description: |
  [描述 - 最多1024字符]
allowed-tools:
  - Bash
  - Read
  - Write
---
注意: 
allowed-tools
是可选字段，用于限制Claude可使用的工具。本仓库中常用
metadata:
字段搭配
keywords:
数组来提升可发现性，尽管这并未在Anthropic的官方规范中正式文档化。
license:
等字段仅作信息展示，Claude Code不会实际使用。

Field Guidelines

字段指南

  • name: Lowercase letters, numbers, hyphens only. Max 64 chars. Gerund form recommended (e.g., 
    processing-pdfs
    )
  • description: Max 1024 chars. Must include what it does AND when to use it. Third-person perspective.
  • allowed-tools: Restricts which tools Claude can use when skill is active (rare, optional)
  • name: 仅包含小写字母、数字、连字符。最多64字符。推荐使用动名词形式（如
    processing-pdfs
    ）
  • description: 最多1024字符。必须包含功能描述和适用场景。使用第三人称视角。
  • allowed-tools: 限制技能激活时Claude可使用的工具（罕见，可选）

Common Mistakes

常见错误

1. Description Too Vague

1. 描述过于模糊

yaml
undefined
yaml
undefined

❌ Won't be discovered

❌ 无法被发现

description: "Helps with authentication"
description: "Helps with authentication"

✅ Will be discovered

✅ 可被发现

description: | Implement authentication with Clerk - React components, middleware, and Cloudflare Workers integration with JWT verification.
Use when: adding auth to React apps, protecting API routes, or troubleshooting "clerk/backend" import errors.
undefined
description: | Implement authentication with Clerk - React components, middleware, and Cloudflare Workers integration with JWT verification.
Use when: adding auth to React apps, protecting API routes, or troubleshooting "clerk/backend" import errors.
undefined

2. Duplicating Claude's Knowledge

2. 重复Claude已有的知识

yaml
undefined
yaml
undefined

❌ Claude already knows JavaScript basics

❌ Claude已掌握JavaScript基础

Variables

Variables

Use 
const
for constants and 
let
for variables...
Use 
const
for constants and 
let
for variables...

✅ Focus on what Claude might get wrong

✅ 聚焦Claude可能出错的点

Critical: Cloudflare Workers Differences

关键: Cloudflare Workers 的差异

  • No 
    process.env
    - use 
    env
    parameter from fetch handler
  • No Node.js 
    fs
    module - use R2 or KV for storage
undefined
  • 无
    process.env
    - 使用fetch处理程序中的
    env
    参数
  • 无Node.js 
    fs
    模块 - 使用R2或KV进行存储
undefined

3. Missing Error Keywords

3. 缺少错误关键词

Skills are often triggered when users hit errors. Include common error messages:
yaml
description: |
  ...
  Use when: troubleshooting "Cannot read properties of undefined",
  "NEXT_REDIRECT" errors, or hydration mismatches.
技能通常在用户遇到错误时被触发。请包含常见错误消息：
yaml
description: |
  ...
  Use when: troubleshooting "Cannot read properties of undefined",
  "NEXT_REDIRECT" errors, or hydration mismatches.

4. Overly Rigid Instructions

4. 指令过于僵化

markdown
undefined
markdown
undefined

❌ Too rigid (breaks if API changes)

❌ 过于僵化（API变更后会失效）

Always call api.configure({ version: "2.1.0" }) first.
Always call api.configure({ version: "2.1.0" }) first.

✅ Flexible with rationale

✅ 灵活且说明理由

Configure the API client before making calls. The version should match your installed package version (check package.json).
undefined
在调用API前配置客户端。版本需与已安装的包版本匹配（检查package.json）。
undefined

5. No Production Validation

5. 未经过生产环境验证

Skills should be tested in real projects, not just theoretically correct:
markdown
undefined
技能应在真实项目中测试，而非仅理论正确：
markdown
undefined

Production Example

生产环境示例

Tested in [Project Name]:
  • Build time: 45 seconds
  • Errors prevented: 6/6 documented issues
  • Zero runtime errors after deployment

---
已在[项目名称]中测试：
  • 构建时间: 45秒
  • 避免的错误: 6/6已记录问题
  • 部署后无运行时错误

---

Token Efficiency

Token 效率

Measuring Efficiency

效率衡量

Compare tokens used with vs without skill:
MetricWithout SkillWith SkillSavings
Setup tokens~15k~5k67%
Errors hit2-30100%
Iterations3-4175%
对比使用技能前后的Token消耗：
指标未使用技能使用技能节省比例
初始化Token~15k~5k67%
遇到的错误2-30100%
迭代次数3-4175%

Optimization Techniques

优化技巧

  1. Move examples to references/: Keep SKILL.md under 5k words
  2. Use code blocks strategically: One good example > three mediocre ones
  3. Link don't duplicate: Reference official docs instead of copying
  4. Prune ruthlessly: If Claude knows it, don't include it
  1. 将示例移至references/：保持SKILL.md在5000字以内
  2. 策略性使用代码块：一个优质示例胜过三个平庸示例
  3. 链接而非重复：引用官方文档而非复制内容
  4. 严格精简：Claude已掌握的内容无需包含

Testing Your Skill

测试你的技能

Discovery Test

可发现性测试

Ask Claude Code naturally:
"Help me set up [technology your skill covers]"
Claude should propose using your skill. If not:
  • Check description has relevant keywords
  • Verify README.md has auto-trigger keywords
  • Ensure skill is symlinked to ~/.claude/skills/
自然地向Claude Code提问：
"Help me set up [你的技能涵盖的技术]"
Claude应提议使用你的技能。若未触发：
  • 检查描述是否包含相关关键词
  • 验证README.md是否包含自动触发关键词
  • 确保技能已链接到~/.claude/skills/目录

Functionality Test

功能测试

Build a real project using only the skill's guidance:
  • Did you need to search for additional information?
  • Did you hit any errors the skill should have prevented?
  • Was any instruction unclear or wrong?
仅使用技能中的指导构建真实项目：
  • 是否需要额外搜索信息？
  • 是否遇到技能本应预防的错误？
  • 是否存在说明模糊或错误的地方？

Verification Script

验证脚本

bash
./scripts/check-metadata.sh <skill-name>
bash
./scripts/check-metadata.sh <skill-name>

Quality Checklist

质量检查清单

Before committing a skill:
  • Name is lowercase-hyphen-case, max 40 chars
  • Description is 250-350 chars with "Use when:" section
  • SKILL.md under 5k words
  • All code examples tested and working
  • Package versions verified current
  • Known issues documented with sources (GitHub issues, etc.)
  • Production tested (not just theoretically correct)
  • README.md has auto-trigger keywords
  • Symlinked and discoverable
提交技能前：
  • 名称为小写连字符格式，最多40字符
  • 描述为250-350字符，包含"Use when:"部分
  • SKILL.md不超过5000字
  • 所有代码示例已测试且可正常运行
  • 已验证包版本为当前最新
  • 已记录已知问题及来源（GitHub issues等）
  • 已通过生产环境测试（非仅理论正确）
  • README.md包含自动触发关键词
  • 已链接且可被发现

References

参考资料

Quick Command Reference

快速命令参考

bash
undefined
bash
undefined

Create new skill

创建新技能

/create-skill my-skill-name
/create-skill my-skill-name

Install skill

安装技能

./scripts/install-skill.sh my-skill-name
./scripts/install-skill.sh my-skill-name

Verify metadata

验证元数据

./scripts/check-metadata.sh my-skill-name
./scripts/check-metadata.sh my-skill-name

Check all skills

检查所有技能

./scripts/check-all-versions.sh
./scripts/check-all-versions.sh

Generate marketplace manifest

生成市场清单

./scripts/generate-plugin-manifests.sh my-skill-name
undefined
./scripts/generate-plugin-manifests.sh my-skill-name
undefined