skill-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Best Practices

技能最佳实践

Reference: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf

参考文档：https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf

Instructions

操作步骤

Step 1: Identify your use case category

步骤1：确定用例类别

Determine which type of skill you're building:

Document & Asset Creation — consistent output (docs, designs, code)
Workflow Automation — multi-step processes with consistent methodology
MCP Enhancement — workflow guidance on top of MCP tool access

Define 2–3 concrete use cases before writing anything (see Planning section below).

明确你要构建的技能类型：

文档与资产创建 —— 生成标准化输出（文档、设计、代码）
工作流自动化 —— 遵循统一方法的多步骤流程
MCP工具增强 —— 基于MCP工具访问能力的工作流指导

在开始编写前，先定义2-3个具体用例（详见下方规划章节）。

Step 2: Create the folder and SKILL.md

步骤2：创建文件夹与SKILL.md文件

Name the folder in kebab-case (e.g.
```
my-skill-name
```
)
Create exactly
```
SKILL.md
```
(case-sensitive) inside it
Write YAML frontmatter with
```
name
```
and
```
description
```
(see Technical requirements)

文件夹名称采用kebab-case格式（例如：
```
my-skill-name
```
）
在文件夹内创建名称完全为
```
SKILL.md
```
的文件（区分大小写）
编写包含
```
name
```
和
```
description
```
的YAML前置内容（详见技术要求）

Step 3: Write the description — this is the most critical part

步骤3：编写描述——这是最关键的部分

The description controls when Claude loads your skill. It must include:

WHAT the skill does
WHEN to use it (specific trigger phrases)
Optional: negative triggers ("Do NOT use for...")

See "Writing effective descriptions" for good/bad examples.

描述内容决定Claude何时加载你的技能，必须包含：

功能：技能能做什么
触发时机：何时使用（具体触发短语）
可选：负向触发规则（“请勿用于……”）

参考“撰写有效描述”章节中的正反示例。

Step 4: Write the body instructions

步骤4：编写主体指令

Follow the recommended template:

## Instructions

→ numbered steps →

## Examples

→

## Troubleshooting

. Be specific and actionable. Move detailed docs to

references/

and link to them.

遵循推荐模板：

## 操作步骤

→ 编号步骤 →

## 示例

→

## 故障排查

。内容需具体且可执行，将详细文档移至

references/

目录并添加链接。

Step 5: Update CLAUDE.md and README.md

步骤5：更新CLAUDE.md和README.md

After creating or modifying any skill in this repository, always update the skill tables in both files:

```
CLAUDE.md
```
— skill table under "Included Skills" (Trigger column: one-line description of when it fires)
```
README.md
```
— skill table under "Enthaltene Skills" (Beschreibung column: German one-liner)

Both files must stay in sync. This step is mandatory and must not be skipped.

Also invoke the

cc-best-practices

skill when working on skills in this repository to ensure context and session management follow project standards.

在本仓库中创建或修改任何技能后，必须更新这两个文件中的技能表：

```
CLAUDE.md
```
—— “包含的技能”下的技能表（触发列：简要描述触发场景）
```
README.md
```
—— “Enthaltene Skills”下的技能表（Beschreibung列：德语简要说明）

两个文件必须保持同步，此步骤为强制要求，不可跳过。

同时，在本仓库中处理技能时需调用

cc-best-practices

技能，确保上下文和会话管理符合项目标准。

Step 6: Validate YAML and skills CLI compatibility

步骤6：验证YAML格式与技能CLI兼容性

Run the validation script from the repository root before testing or committing:

bash

bash .claude/skills/skill-best-practices/scripts/validate-skills.sh

Fix any

FAIL

lines before continuing. Common issues:

```
description
```
uses block scalar (
```
>
```
or
```
|
```
) → replace with a quoted single-line string
Sub-keys under a parent mapping key not indented → add two-space indent

After pushing, also run the remote check to confirm

npx skills add --list

finds all skills:

bash

bash .claude/skills/skill-best-practices/scripts/validate-skills.sh --remote

在测试或提交前，从仓库根目录运行验证脚本：

bash

bash .claude/skills/skill-best-practices/scripts/validate-skills.sh

修复所有

FAIL

项后再继续。常见问题：

```
description
```
使用块标量（
```
>
```
或
```
|
```
）→ 替换为带引号的单行字符串
父映射键下的子键未缩进 → 添加两个空格的缩进

推送代码后，还需运行远程检查，确认

npx skills add --list

能找到所有技能：

bash

bash .claude/skills/skill-best-practices/scripts/validate-skills.sh --remote

Step 7: Test triggering and functional behavior

步骤7：测试触发逻辑与功能表现

Run 10–20 test queries. Target: skill triggers on ~90% of relevant queries and never on unrelated topics. Iterate on the description until triggering is reliable (see Testing approach).

运行10-20次测试查询。目标：技能在约90%的相关查询中触发，且从不触发无关主题的查询。反复调整描述内容，直到触发逻辑可靠（详见测试方法）。

Step 7: Iterate based on signals

步骤8：基于反馈迭代优化

Undertriggering → add more trigger phrases to description
Overtriggering → add negative triggers, narrow scope
Instructions ignored → move critical steps to top, use explicit language

触发不足 → 在描述中添加更多触发短语
过度触发 → 添加负向触发规则，缩小适用范围
不遵循指令 → 将关键步骤移至顶部，使用明确表述

Examples

示例

Example 1: Building a new skill from scratch

示例1：从零开始构建新技能

User says: "Help me create a skill that plans sprints in Linear"

Actions:

Identify category: Workflow Automation + MCP Enhancement
Define use case: trigger = "plan sprint", "create sprint tasks"; steps = fetch Linear status → analyze velocity → create tasks
Create folder
```
linear-sprint-planner/SKILL.md
```
Write description: "Manages Linear sprint planning workflows. Use when user says 'plan sprint', 'create sprint tasks', or 'set up iteration'."
Write step-by-step instructions with Linear MCP tool calls
Test with 10 trigger phrases; adjust description if skill doesn't auto-load

Result: Functional skill that auto-triggers on sprint planning requests and executes the full workflow without user re-explaining the steps each time.

用户需求：“帮我创建一个在Linear中规划迭代的技能”

操作流程：

确定类别：工作流自动化 + MCP工具增强
定义用例：触发词 = “规划迭代”、“创建迭代任务”；步骤 = 获取Linear状态 → 分析速度 → 创建任务
创建文件夹
```
linear-sprint-planner/SKILL.md
```
编写描述：“管理Linear迭代规划工作流。当用户说‘规划迭代’、‘创建迭代任务’或‘设置迭代周期’时使用。”
编写包含Linear MCP工具调用的分步指令
用10个触发短语测试；若技能未自动加载则调整描述

结果：功能完备的技能，可在迭代规划请求时自动触发，无需用户每次重复解释步骤即可执行完整工作流。

Example 2: Reviewing an existing skill

示例2：审核现有技能

User says: "Review my SKILL.md and suggest improvements"

Actions:

Read the SKILL.md frontmatter — check name (kebab-case?), description (WHAT + WHEN? under 1024 chars? trigger phrases present?)
Check body — is it under 5,000 words? Are instructions specific and actionable? Is there a Troubleshooting section? Examples?
Simulate triggering — would the description cause Claude to load this skill for the right queries?
Report findings as: PASS / WARN / FAIL per criterion

Result: Prioritized list of improvements with specific fixes for each issue.

用户需求：“审核我的SKILL.md并提出改进建议”

操作流程：

阅读SKILL.md前置内容——检查名称（是否为kebab-case格式？）、描述（是否包含功能+触发时机？字符数是否少于1024？是否有触发短语？）
检查主体内容——字数是否少于5000字？指令是否具体可执行？是否有故障排查章节？是否有示例？
模拟触发场景——描述内容是否会让Claude在正确的查询中加载该技能？
按标准输出结果：每个检查项标记为PASS / WARN / FAIL

结果：按优先级排列的改进列表，每个问题都有具体修复方案。

Example 3: Troubleshooting a skill that doesn't trigger

示例3：排查技能不触发问题

User says: "My skill never loads automatically, I always have to invoke it manually"

Actions:

Read the description field — is it too generic? ("Helps with projects" won't work)
Check for missing trigger phrases — does it include words users would actually say?
Ask Claude: "When would you use the [skill name] skill?" — Claude quotes the description back; gaps become obvious
Rewrite description to add specific trigger phrases and retest

Result: Updated description with concrete triggers; skill auto-loads on relevant queries.

用户需求：“我的技能从不自动加载，我总是需要手动调用它”

操作流程：

阅读描述字段——是否过于宽泛？（“帮助处理项目”这类表述无效）
检查是否缺少触发短语——是否包含用户实际会使用的词汇？
询问Claude：“你会在什么时候使用[技能名称]技能？”——Claude会复述描述内容，问题点会变得很明显
重写描述以添加具体触发短语并重新测试

结果：更新后的描述包含具体触发词，技能可在相关查询中自动加载。

What is a skill?

什么是技能？

A skill is a folder containing:

```
SKILL.md
```
(required): Instructions in Markdown with YAML frontmatter
```
scripts/
```
(optional): Executable code (Python, Bash, etc.)
```
references/
```
(optional): Documentation loaded as needed
```
assets/
```
(optional): Templates, fonts, icons used in output

技能是一个包含以下内容的文件夹：

```
SKILL.md
```
（必填）：带YAML前置内容的Markdown格式指令
```
scripts/
```
（可选）：可执行代码（Python、Bash等）
```
references/
```
（可选）：按需加载的文档
```
assets/
```
（可选）：输出中使用的模板、字体、图标

Core design principles

核心设计原则

Progressive Disclosure — three levels:

YAML frontmatter: always in system prompt; tells Claude when to load the skill
SKILL.md body: loaded when relevant; full instructions
Linked files in
```
references/
```
: loaded on demand

Composability — skills work alongside others; don't assume exclusivity.

Portability — works identically across Claude.ai, Claude Code, and API.

渐进式披露——三个层级：

YAML前置内容：始终包含在系统提示中；告诉Claude何时加载技能
SKILL.md主体：相关场景下加载；完整指令
```
references/
```
中的链接文件：按需加载

可组合性——技能可与其他技能协同工作；不要假设独占性。

可移植性——在Claude.ai、Claude Code和API中表现一致。

Planning: Start with use cases

规划：从用例开始

Before writing, define 2–3 concrete use cases:

Use Case: <name>
Trigger: User says "<phrase>" or "<phrase>"
Steps:
  1. ...
  2. ...
Result: <expected outcome>

Ask yourself:

What does the user want to accomplish?
What multi-step workflow is required?
Which tools are needed (built-in or MCP)?
What domain knowledge should be embedded?

编写前，定义2-3个具体用例：

用例：<名称>
触发条件：用户说“<短语>”或“<短语>”
步骤：
  1. ...
  2. ...
预期结果：<预期输出>

自问以下问题：

用户想要达成什么目标？
需要哪些多步骤工作流？
需要用到哪些工具（内置或MCP）？
应嵌入哪些领域知识？

Three skill categories

三类技能

Category	When to use	Key techniques
Document & Asset Creation	Consistent, high-quality output (docs, designs, code)	Style guides, templates, quality checklists
Workflow Automation	Multi-step processes with consistent methodology	Step-by-step with validation gates, iterative loops
MCP Enhancement	Workflow guidance on top of MCP tool access	Sequential MCP calls, embedded domain expertise

类别	适用场景	关键技术
文档与资产创建	生成标准化、高质量输出（文档、设计、代码）	风格指南、模板、质量检查表
工作流自动化	遵循统一方法的多步骤流程	带验证节点的分步流程、迭代循环
MCP工具增强	基于MCP工具访问能力的工作流指导	顺序MCP调用、嵌入领域专业知识

Technical requirements

技术要求

File & folder naming

文件与文件夹命名

Folder: kebab-case only (
```
notion-project-setup
```
) — no spaces, underscores, or capitals
File: exactly SKILL.md
(case-sensitive) — no variations
No
```
README.md
```
inside the skill folder (put docs in
```
SKILL.md
```
or
```
references/
```
)

文件夹：仅允许kebab-case格式（
```
notion-project-setup
```
）——无空格、下划线或大写字母
文件：名称必须完全为**
```
SKILL.md
```
**（区分大小写）——不允许变体
技能文件夹内不得有
```
README.md
```
（文档放在SKILL.md或
```
references/
```
中）

YAML frontmatter

YAML前置内容

Minimal required format:

yaml

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

name
(required):

kebab-case, no spaces or capitals
Must match folder name

description
(required):

MUST include BOTH: what the skill does AND when to use it (trigger conditions)
Under 1024 characters
No XML tags (
```
<
```
or
```
>
```
)
Include specific trigger phrases users would actually say
Mention file types if relevant

Optional fields:

yaml

license: MIT
compatibility: "Requires Python 3.10+"
metadata:
  author: Your Name
  version: 1.0.0
  mcp-server: server-name

Security restrictions — forbidden in frontmatter:

XML angle brackets (
```
< >
```
)
Names containing "claude" or "anthropic" (reserved)

最小必填格式：

yaml

---
name: your-skill-name
description: 功能描述。当用户请求[具体短语]时使用。
---

name
（必填）：

kebab-case格式，无空格或大写字母
必须与文件夹名称一致

description
（必填）：

必须同时包含：技能功能 AND 触发时机（触发条件）
字符数少于1024
无XML标签（
```
<
```
或
```
>
```
）
包含用户实际会使用的具体触发短语
若相关，提及文件类型

可选字段：

yaml

license: MIT
compatibility: "需要Python 3.10+"
metadata:
  author: 你的名字
  version: 1.0.0
  mcp-server: server-name

安全限制——前置内容中禁止：

XML尖括号（
```
< >
```
）
包含“claude”或“anthropic”的名称（为保留词）

Writing effective descriptions

撰写有效描述

Structure:

[What it does] + [When to use it] + [Key capabilities]

Good examples:

yaml

undefined

结构：

[功能描述] + [触发时机] + [核心能力]

优秀示例：

yaml

undefined

Specific and actionable

具体且可执行

description: Analyzes Figma design files and generates developer handoff docs. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".

description: 分析Figma设计文件并生成开发者交付文档。当用户上传.fig文件、请求“设计规范”、“组件文档”或“设计转代码交付”时使用。

Includes trigger phrases

包含触发短语

description: Manages Linear project workflows including sprint planning and task creation. Use when user mentions "sprint", "Linear tasks", or asks to "create tickets".


**Bad examples:**

```yaml

description: 管理Linear项目工作流，包括迭代规划和任务创建。当用户提及“迭代”、“Linear任务”或请求 “创建工单”时使用。


**反面示例：**

```yaml

Too vague

过于宽泛

description: Helps with projects.

description: 帮助处理项目。

Missing triggers

缺少触发条件

description: Creates sophisticated multi-page documentation systems.

description: 创建复杂的多页面文档系统。

Too technical, no user triggers

过于技术化，无用户触发词

description: Implements the Project entity model with hierarchical relationships.

---

description: 实现带有层级关系的项目实体模型。

---

Writing instructions (SKILL.md body)

编写指令（SKILL.md主体）

Recommended structure:

markdown

undefined

推荐结构：

markdown

undefined

Your Skill Name

你的技能名称

Instructions

操作步骤

Step 1: [First Major Step]

步骤1：[核心步骤1]

Clear explanation of what happens.

清晰说明操作内容。

Step 2: ...

步骤2：...

Examples

示例

Example 1: [Common scenario]

示例1：[常见场景]

User says: "..." Actions:

... Result: ...

用户说：“...” 操作流程：

... 结果：...

Troubleshooting

故障排查

Error: [Common error message]

错误：[常见错误信息]

Cause: Why it happens Solution: How to fix

undefined

原因： 错误产生的原因 解决方案： 修复方法

undefined

Best practices for instructions

指令撰写最佳实践

Be specific and actionable:

undefined

具体且可执行：

undefined

Good

优秀示例

Run

python scripts/validate.py --input {filename}

to check data format. If validation fails, common issues:

Missing required fields (add to CSV)
Invalid date formats (use YYYY-MM-DD)

运行

python scripts/validate.py --input {filename}

检查数据格式。若验证失败，常见问题：

缺少必填字段（添加到CSV）
日期格式无效（使用YYYY-MM-DD）

Bad

反面示例

Validate the data before proceeding.


**Include error handling** — document common errors with cause and solution.

**Reference bundled resources clearly:**

Before writing queries, consult

references/api-patterns.md

for:

Rate limiting guidance
Pagination patterns


**Use progressive disclosure** — keep SKILL.md focused on core instructions; move detailed docs to `references/` and link to them. Keep SKILL.md under 5,000 words.

**For critical validations**, prefer a bundled script over language instructions — code is deterministic, language interpretation isn't.

---

在继续前验证数据。


**包含错误处理**——记录常见错误的原因和解决方案。

**清晰引用捆绑资源：**

编写查询前，请参考

references/api-patterns.md

获取：

限流指南
分页模式


**使用渐进式披露**——保持SKILL.md聚焦于核心指令；将详细文档移至`references/`并添加链接。SKILL.md字数需控制在5000字以内。

**对于关键验证**，优先使用捆绑脚本而非自然语言指令——代码具有确定性，而语言解释存在不确定性。

---

Testing approach

测试方法

1. Triggering tests

1. 触发测试

Run 10–20 queries. Skill should trigger on ~90% of relevant queries and NOT trigger on unrelated topics.

Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"

Should NOT trigger:
- "What's the weather?"
- "Help me write Python code"

Debugging: Ask Claude "When would you use the [skill name] skill?" — it will quote the description back.

运行10-20次查询。技能应在约90%的相关查询中触发，且绝不触发无关主题的查询。

应触发：
- “帮我设置新的ProjectHub工作区”
- “我需要在ProjectHub中创建一个项目”

不应触发：
- “天气怎么样？”
- “帮我写Python代码”

调试方法： 询问Claude“你会在什么时候使用[技能名称]技能？”——它会复述描述内容。

2. Functional tests

2. 功能测试

Valid outputs generated
API calls succeed
Error handling works
Edge cases covered

生成有效输出
API调用成功
错误处理有效
覆盖边缘情况

3. Performance comparison

3. 性能对比

Compare token count, tool calls, and back-and-forth messages with vs. without the skill.

Pro tip: Iterate on a single challenging task until Claude succeeds, then extract the winning approach into a skill.

对比使用技能与不使用技能时的令牌数量、工具调用次数和交互消息数。

小技巧： 针对单个复杂任务反复迭代，直到Claude能成功完成，然后将有效的方法提炼为技能。

Troubleshooting

故障排查

Skill won't upload

技能无法上传

Error	Cause	Fix
"Could not find SKILL.md"	Wrong filename	Rename exactly to `SKILL.md`
"Invalid frontmatter"	YAML formatting	Add `---` delimiters, close quotes
"Invalid skill name"	Spaces or capitals in name	Use kebab-case

错误信息	原因	修复方法
"Could not find SKILL.md"	文件名错误	重命名为 `SKILL.md`
"Invalid frontmatter"	YAML格式错误	添加 `---` 分隔符，闭合引号
"Invalid skill name"	名称包含空格或大写字母	使用kebab-case格式

Skill doesn't trigger (undertriggering)

技能不触发（触发不足）

Description too generic
Missing trigger phrases users actually say
Missing relevant file type mentions

Fix: Add more specific keywords and phrases to the description.

描述过于宽泛
缺少用户实际使用的触发短语
缺少相关文件类型提及

修复方法： 在描述中添加更具体的关键词和短语。

Skill triggers too often (overtriggering)

技能触发过于频繁（过度触发）

Add negative triggers and narrow the scope:

yaml

description: Advanced data analysis for CSV files. Use for statistical modeling,
  regression, clustering. Do NOT use for simple data exploration.

添加负向触发规则并缩小适用范围：

yaml

description: 针对CSV文件的高级数据分析。用于统计建模、
  回归分析、聚类分析。请勿用于简单的数据探索。

Instructions not followed

不遵循指令

Too verbose — keep concise, use bullet points, move details to
```
references/
```
Instructions buried — put critical instructions at top, use
```
## Critical
```
headers
Ambiguous language — be explicit: "CRITICAL: Before calling X, verify: ..."
Model laziness — add to user prompts (more effective than SKILL.md): "Take your time, quality over speed, do not skip validation steps"

过于冗长——保持简洁，使用项目符号，将细节移至
```
references/
```
指令位置靠后——将关键指令放在顶部，使用
```
## 关键步骤
```
标题
表述模糊——明确表述：“重要提示：调用X之前，请验证：...”
模型惰性——在用户提示中添加说明（比SKILL.md更有效）：“请仔细处理，质量优先，不要跳过验证步骤”

Large context / slow responses

上下文过大 / 响应缓慢

Move detailed docs to
```
references/
```
Keep SKILL.md under 5,000 words
Reduce simultaneous enabled skills (evaluate if you have more than 20–50)

将详细文档移至
```
references/
```
保持SKILL.md字数在5000以内
减少同时启用的技能数量（评估是否超过20-50个）

Workflow patterns

工作流模式

Five patterns cover most skill types: Sequential orchestration, Multi-MCP coordination, Iterative refinement, Context-aware tool selection, and Domain-specific intelligence.

For detailed examples and implementation templates for each pattern, consult

references/patterns.md

五种模式覆盖大多数技能类型：顺序编排、多MCP协同、迭代优化、上下文感知工具选择和领域特定智能。

如需每种模式的详细示例和实现模板，请参考

references/patterns.md

。

Quick checklist

快速检查清单

Before you start:

Identified 2–3 concrete use cases
Tools identified (built-in or MCP)
Planned folder structure

During development:

Folder named in kebab-case
```
SKILL.md
```
exists (exact spelling, case-sensitive)
YAML frontmatter has
```
---
```
delimiters
```
name
```
: kebab-case, no spaces, no capitals
```
description
```
includes WHAT and WHEN
No XML tags (
```
< >
```
) anywhere
Instructions clear and actionable
Error handling included
Examples provided
References clearly linked

Repository sync (mandatory for this repo):

```
CLAUDE.md
```
skill table updated
```
README.md
```
skill table updated
```
cc-best-practices
```
skill was loaded during this session
```
validate-skills.sh
```
run — no
```
FAIL
```
lines
After push:
```
validate-skills.sh --remote
```
run — all skills found by
```
npx skills
```

Before upload:

Triggers on obvious tasks
Triggers on paraphrased requests
Does NOT trigger on unrelated topics
Functional tests pass

After upload:

Test in real conversations
Monitor for under/over-triggering
Iterate on description and instructions

开始前：

确定2-3个具体用例
确定所需工具（内置或MCP）
规划文件夹结构

开发过程中：

文件夹名称为kebab-case格式
存在
```
SKILL.md
```
文件（拼写完全正确，区分大小写）
YAML前置内容包含
```
---
```
分隔符
```
name
```
：kebab-case格式，无空格，无大写字母
```
description
```
包含功能和触发时机
无XML标签（
```
< >
```
）
指令清晰且可执行
包含错误处理
提供示例
清晰引用参考资源

仓库同步（本仓库强制要求）：

更新CLAUDE.md中的技能表
更新README.md中的技能表
本次会话中已加载cc-best-practices技能
已运行validate-skills.sh——无FAIL项
推送后：已运行validate-skills.sh --remote——所有技能可被npx skills找到

上传前：

在明确任务中触发
在改写后的请求中触发
绝不触发无关主题
功能测试通过

上传后：

在真实对话中测试
监控触发不足/过度触发情况
迭代优化描述和指令 ",