skills-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skills Best Practices

Skills最佳实践

Comprehensive reference for building Agent Skills that follow Anthropic's official guidelines. Skills are folders containing instructions, scripts, and resources that teach Claude how to handle specific tasks. They follow the Agent Skills open standard.

本指南是遵循Anthropic官方规范构建Agent Skills的综合参考资料。Skills是包含指令、脚本和资源的文件夹，用于指导Claude处理特定任务。它们遵循Agent Skills开放标准。

Quick Start

快速开始

A minimal skill is a directory with a

SKILL.md

file:

my-skill/
├── SKILL.md          # Required - instructions with YAML frontmatter
├── references/       # Optional - detailed docs loaded on demand
├── scripts/          # Optional - executable code
└── assets/           # Optional - templates, fonts, icons

Minimal

SKILL.md

yaml

---
name: my-skill-name
description: What it does. Use when [specific triggers].
---

一个最简技能是包含

SKILL.md

文件的目录：

my-skill/
├── SKILL.md          # 必填项 - 带有YAML前置元数据的指令文件
├── references/       # 可选 - 按需加载的详细文档
├── scripts/          # 可选 - 可执行代码
└── assets/           # 可选 - 模板、字体、图标

最简

SKILL.md

示例：

yaml

---
name: my-skill-name
description: What it does. Use when [specific triggers].
---

My Skill Name

[Instructions here]


Only `name` and `description` are required in frontmatter.

[Instructions here]


前置元数据中仅`name`和`description`为必填项。

Core Design Principles

核心设计原则

Progressive Disclosure (Most Important)

渐进式披露（最重要）

Skills load information in three levels to minimize token usage:

Level	When Loaded	Token Cost	Content
1: Metadata	Always (startup)	~100 tokens	`name` + `description` from frontmatter
2: Instructions	When skill triggers	<5k tokens (recommended)	SKILL.md body
3: Resources	As needed	Effectively unlimited	Bundled files, scripts

Keep SKILL.md under 500 lines. Move detailed docs to separate files and reference them:

markdown

undefined

Skills通过三个层级加载信息，以最小化令牌消耗：

层级	加载时机	令牌成本	内容
1: 元数据	始终加载（启动时）	~100令牌	前置元数据中的 `name` + `description`
2: 指令	技能触发时	<5k令牌（推荐）	SKILL.md正文内容
3: 资源	按需加载	几乎无限制	捆绑文件、脚本

请将SKILL.md控制在500行以内。将详细文档移至单独文件并通过引用链接：

markdown

undefined

Advanced features

高级功能

Form filling: See FORMS.md
API reference: See reference.md


Claude reads referenced files only when the task requires them.

表单填充: 参考FORMS.md
API参考: 参考reference.md


Claude仅在任务需要时才会读取引用文件。

Composability

可组合性

Skills work alongside other skills. Don't assume yours is the only one loaded.

Skills可与其他技能协同工作，不要假设你的技能是唯一加载的技能。

Portability

可移植性

Skills work across Claude.ai, Claude Code, API, and Agent SDK without modification (if dependencies are available).

Skills无需修改即可在Claude.ai、Claude Code、API和Agent SDK上运行（前提是依赖项可用）。

Writing the Description (Critical)

描述撰写（关键）

The description is the single most important field - it determines when your skill activates. Claude uses it to decide relevance from potentially 100+ available skills.

描述是最重要的字段——它决定了你的技能何时激活。Claude会根据描述从100+可用技能中判断相关性。

Rules

规则

Write in third person ("Processes files..." not "I help you process files...")
Include WHAT it does + WHEN to use it
Max 1024 characters, no XML angle brackets
Be slightly "pushy" - Claude tends to undertrigger rather than overtrigger
Include specific trigger phrases users would naturally say

使用第三人称撰写（例如“处理文件...”而非“我帮你处理文件...”）
包含功能 + 使用场景
最多1024字符，不包含XML尖括号
语气可稍“主动”——Claude倾向于触发不足而非过度触发
包含用户自然会使用的特定触发短语

Good vs Bad

正反示例

yaml

undefined

yaml

undefined

GOOD - specific, actionable, includes triggers

良好示例 - 具体、可操作、包含触发词

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

BAD - too vague

不良示例 - 过于模糊

description: Helps with documents.

BAD - missing triggers

不良示例 - 缺少触发场景

description: Creates sophisticated multi-page documentation systems.


More examples in [references/description-guide.md](references/description-guide.md).

description: Creates sophisticated multi-page documentation systems.


更多示例请参考[references/description-guide.md](references/description-guide.md)。

Frontmatter Reference

前置元数据参考

Required Fields

必填字段

Field	Rules
`name`	Kebab-case, max 64 chars, lowercase + numbers + hyphens only. No "claude" or "anthropic"
`description`	Non-empty, max 1024 chars, no XML tags. WHAT + WHEN

The agentskills.io standard and the Claude API require both fields. Claude Code is more lenient:

name

falls back to the directory name, and

description

falls back to the first markdown paragraph. Write both anyway for portability.

字段	规则
`name`	使用kebab-case格式，最多64字符，仅包含小写字母、数字和连字符。不可使用“claude”或“anthropic”
`description`	非空，最多1024字符，无XML标签。需包含功能+使用场景

agentskills.io标准和Claude API要求这两个字段。Claude Code的限制更宽松：

name

会回退到目录名称，

description

会回退到第一个markdown段落。但为了可移植性，建议同时填写这两个字段。

Optional Fields (Claude Code)

可选字段（Claude Code）

Field	Purpose
`argument-hint`	Autocomplete hint, e.g. `[issue-number]`
`when_to_use`	Extra trigger context, appended to `description` in the skill listing
`arguments`	Named positional arguments for `$name` substitution (space-separated string or list)
`disable-model-invocation`	`true` = only user can invoke (for deploy, commit)
`user-invocable`	`false` = hidden from `/` menu (background knowledge)
`allowed-tools`	Pre-approves tools (no permission prompt); space-separated, e.g. `Read Grep Glob`
`model`	Override model for this skill; accepts `inherit` . Lasts the current turn only
`effort`	Override effort level: `low` , `medium` , `high` , `xhigh` , `max`
`context`	`fork` = run in isolated subagent
`agent`	Subagent type when `context: fork` (e.g. `Explore` , `Plan` )
`hooks`	Hooks scoped to this skill's lifecycle
`paths`	Glob patterns limiting when skill activates

字段	用途
`argument-hint`	自动补全提示，例如 `[issue-number]`
`when_to_use`	额外触发上下文，会附加到技能列表中的 `description` 之后
`arguments`	用于 `$name` 替换的命名位置参数（空格分隔字符串或列表）
`disable-model-invocation`	`true` = 仅用户可调用（适用于部署、提交等场景）
`user-invocable`	`false` = 在 `/` 菜单中隐藏（作为背景知识）
`allowed-tools`	预批准工具（无需权限提示）；空格分隔，例如 `Read Grep Glob`
`model`	覆盖此技能使用的模型；接受 `inherit` 值。仅对当前对话轮次生效
`effort`	覆盖努力级别： `low` , `medium` , `high` , `xhigh` , `max`
`context`	`fork` = 在独立子Agent中运行
`agent`	当 `context: fork` 时的子Agent类型（例如 `Explore` , `Plan` ）
`hooks`	作用于此技能生命周期的钩子
`paths`	限制技能激活的Glob模式

Naming Conventions

命名规范

The

name

(and its folder) must: be 1-64 chars; use only lowercase letters, numbers, and hyphens; not start or end with a hyphen; not contain consecutive hyphens (

--

); and match the parent directory name. Anthropic surfaces also reject the reserved words

claude

and

anthropic

Prefer gerund form for clarity:

processing-pdfs

analyzing-spreadsheets

managing-databases

Also acceptable:
```
pdf-processing
```
,
```
process-pdfs
```
Avoid:
```
helper
```
,
```
utils
```
,
```
tools
```
,
```
documents
```

name

（及其所在文件夹）必须：1-64字符；仅使用小写字母、数字和连字符；不以连字符开头或结尾；不包含连续连字符(

--

)；与父目录名称匹配。Anthropic平台还会拒绝保留词

claude

和

anthropic

。

优先使用动名词形式以确保清晰：

processing-pdfs

analyzing-spreadsheets

managing-databases

也可接受：
```
pdf-processing
```
,
```
process-pdfs
```
避免使用：
```
helper
```
,
```
utils
```
,
```
tools
```
,
```
documents
```

Structuring Instructions

指令结构

Be Concise

简洁性

Claude is smart. Only add context it doesn't already have:

markdown

undefined

Claude很智能，只需添加它不具备的上下文信息：

markdown

undefined

GOOD (~50 tokens)

良好示例（约50令牌）

Extract PDF text

提取PDF文本

Use pdfplumber for text extraction:

python

import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

使用pdfplumber进行文本提取：

python

import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

BAD (~150 tokens)

不良示例（约150令牌）

Extract PDF text

提取PDF文本

PDF files are a common file format containing text and images. To extract text, you need a library. There are many available...

undefined

PDF是包含文本和图像的常见文件格式。要提取文本，你需要一个库。有很多可用的库...

undefined

Avoid Too Many Options

避免过多选项

Don't present multiple approaches unless necessary. Give one default with an escape hatch:

markdown

undefined

除非必要，否则不要提供多种方法。给出一个默认方案并提供备选方案：

markdown

undefined

BAD: "Use pypdf, or pdfplumber, or PyMuPDF, or pdf2image..."

不良示例："使用pypdf，或pdfplumber，或PyMuPDF，或pdf2image..."

GOOD: "Use pdfplumber for text extraction. For scanned PDFs needing

良好示例："使用pdfplumber进行文本提取。对于需要OCR的扫描版PDF，改用pdf2image搭配pytesseract。"

OCR, use pdf2image with pytesseract instead."

—

undefined

undefined

Set Degrees of Freedom

设置自由度

High freedom (text guidelines): Multiple approaches valid, context-dependent
Medium freedom (pseudocode/templates): Preferred pattern exists, some variation OK
Low freedom (exact scripts): Operations are fragile, consistency critical

高自由度（文本指南）：多种方法均有效，取决于上下文
中等自由度（伪代码/模板）：存在首选模式，允许一定变化
低自由度（精确脚本）：操作易受影响，一致性至关重要

Recommended SKILL.md Structure

Skill Name

技能名称

Quick start

快速开始

[Minimal working example]

[最简工作示例]

Workflow Decision Tree

工作流决策树

[Route to the right approach based on task type]

[根据任务类型选择合适的方法]

Detailed Instructions

详细指令

[Step-by-step for each workflow]

[每个工作流的分步说明]

Examples

示例

[Concrete input/output pairs]

[具体的输入/输出对]

Troubleshooting

故障排除

[Common errors and fixes]

undefined

[常见错误及修复方法]

undefined

Reference Files

参考文件

Keep references one level deep from SKILL.md. "Depth" means the reference chain (a file linking to a file linking to a file), not filesystem nesting - a

references/

subdirectory is fine. In a chain, Claude may preview files with partial reads (

head

) and miss content.

markdown

undefined

请将参考文件保持在SKILL.md的一级深度。“深度”指的是引用链（文件链接到文件再链接到文件），而非文件系统嵌套——

references/

子目录是允许的。在多级引用链中，Claude可能会部分读取文件（

head

）并遗漏内容。

markdown

undefined

BAD: Too deep

不良示例：层级过深

SKILL.md -> advanced.md -> details.md -> actual info

SKILL.md -> advanced.md -> details.md -> 实际信息

GOOD: One level

良好示例：一级深度

SKILL.md -> advanced.md (contains the info directly) SKILL.md -> reference.md (contains the info directly)


For reference files >100 lines, include a **table of contents** at the top. Watch file *size* too: a single reference of many hundreds of lines defeats progressive disclosure even at one level deep, because Claude loads the whole file for any subtopic. Split large references by subtopic so each task pulls only what it needs.

SKILL.md -> advanced.md（直接包含信息） SKILL.md -> reference.md（直接包含信息）


对于超过100行的参考文件，请在顶部添加**目录**。同时注意文件大小：即使是一级深度，数百行的参考文件也会违背渐进式披露的原则，因为Claude会为任何子主题加载整个文件。请按子主题拆分大型参考文件，以便每个任务仅获取所需内容。

Patterns

模式

Sequential Workflow

顺序工作流

markdown

undefined

markdown

undefined

Step 1: Analyze input

步骤1：分析输入

Run:

python scripts/analyze.py input.pdf

运行：

python scripts/analyze.py input.pdf

Step 2: Validate

步骤2：验证

Run:

python scripts/validate.py fields.json

Fix any errors before continuing.

运行：

python scripts/validate.py fields.json

修复所有错误后再继续。

Step 3: Execute

步骤3：执行

Run:

python scripts/process.py input.pdf fields.json output.pdf

undefined

运行：

python scripts/process.py input.pdf fields.json output.pdf

undefined

Conditional Workflow (Decision Tree)

条件工作流（决策树）

markdown

undefined

markdown

undefined

Workflow Decision Tree

工作流决策树

Creating new content? -> Follow "Creation workflow" Editing existing content? -> Follow "Editing workflow" Reviewing content? -> Follow "Review workflow"

undefined

创建新内容？ -> 遵循“创建工作流” 编辑现有内容？ -> 遵循“编辑工作流” 审核内容？ -> 遵循“审核工作流”

undefined

Feedback Loop

反馈循环

markdown

1. Make edits
2. Validate: `python scripts/validate.py`
3. If validation fails -> fix issues -> go to step 2
4. Only proceed when validation passes

markdown

1. 进行编辑
2. 验证：`python scripts/validate.py`
3. 如果验证失败 -> 修复问题 -> 返回步骤2
4. 仅在验证通过后继续

Checklist Pattern (for complex tasks)

清单模式（适用于复杂任务）

markdown

Copy this checklist and track progress:
- [ ] Step 1: Analyze input
- [ ] Step 2: Create plan
- [ ] Step 3: Validate plan
- [ ] Step 4: Execute
- [ ] Step 5: Verify output

More patterns in references/patterns.md.

markdown

复制此清单并跟踪进度：
- [ ] 步骤1：分析输入
- [ ] 步骤2：制定计划
- [ ] 步骤3：验证计划
- [ ] 步骤4：执行
- [ ] 步骤5：验证输出

更多模式请参考references/patterns.md。

Scripts

脚本

When your skill includes executable code:

Solve, don't punt: Handle errors explicitly instead of letting them fail
Justify constants: No magic numbers - document why each value was chosen
Prefer execution over loading: Scripts run without entering context; only output consumes tokens
Clarify intent: "Run
```
analyze.py
```
" (execute) vs "See
```
analyze.py
```
" (read as reference)
List dependencies in SKILL.md and verify availability

当技能包含可执行代码时：

解决问题，而非回避：显式处理错误，而非让其失败
解释常量：避免魔法数字——记录每个值的选择原因
优先执行而非加载：脚本运行时不会进入上下文；仅输出会消耗令牌
明确意图：“Run
```
analyze.py
```
”（执行） vs “See
```
analyze.py
```
”（作为参考读取）
在SKILL.md中列出依赖项并验证其可用性

Testing

测试

Build Evaluations First

先构建评估用例

Create evaluations before writing extensive instructions - this proves the skill solves a real problem. Run Claude on representative tasks without the skill and document the failures; build ~3 scenarios that test those gaps; measure a baseline; then write the minimum instructions needed to pass. Iterate against the baseline.

在编写详细指令之前创建评估用例——这能证明技能解决了实际问题。在不使用技能的情况下让Claude处理代表性任务并记录失败情况；构建约3个测试这些短板的场景；测量基准；然后编写通过测试所需的最少指令。根据基准迭代优化。

Triggering Tests

触发测试

Should trigger:
- "Help me set up a new project in [Service]"
- "I need to create a project" (paraphrased)

Should NOT trigger:
- "What's the weather?" (unrelated)
- "Write Python code" (too generic)

应触发：
- "Help me set up a new project in [Service]"
- "I need to create a project"（改写后的表述）

不应触发：
- "What's the weather?"（无关内容）
- "Write Python code"（过于通用）

Functional Tests

功能测试

Test normal operations, edge cases, and out-of-scope requests. Run the same request 3-5 times to check consistency.

测试正常操作、边缘情况和超出范围的请求。同一请求运行3-5次以检查一致性。

Debug Triggering

调试触发问题

Ask Claude: "When would you use the [skill-name] skill?" - it quotes the description back. Adjust based on what's missing.

询问Claude：“When would you use the [skill-name] skill?”——它会返回描述内容。根据缺失的信息进行调整。

Troubleshooting

故障排除

Symptom	Cause	Fix
Skill never loads	Description too vague	Add specific triggers and key terms
Skill loads for wrong tasks	Description too broad	Add negative triggers, be more specific
Instructions not followed	Too verbose or buried	Put critical instructions at top, use headers
Slow/degraded responses	SKILL.md too large	Move content to references/, keep under 500 lines
"Could not find SKILL.md"	Wrong filename	Must be exactly `SKILL.md` (case-sensitive)
"Invalid skill name"	Spaces or capitals	Use kebab-case: `my-skill-name`

症状	原因	修复方法
技能从未加载	描述过于模糊	添加特定触发词和关键术语
技能在错误任务中加载	描述过于宽泛	添加否定触发词，表述更具体
未遵循指令	指令过于冗长或被隐藏	将关键指令放在顶部，使用标题
响应缓慢/性能下降	SKILL.md过大	将内容移至references/，保持在500行以内
"Could not find SKILL.md"	文件名错误	必须严格为 `SKILL.md` （区分大小写）
"Invalid skill name"	包含空格或大写字母	使用kebab-case格式： `my-skill-name`

Distribution

分发

Surface	How to Deploy
Claude.ai	Settings > Features > Upload zip
Claude Code (personal)	`~/.claude/skills/<name>/SKILL.md`
Claude Code (project)	`.claude/skills/<name>/SKILL.md`
Claude Code (plugin)	`<plugin>/skills/<name>/SKILL.md`
API	Upload via the Skill Management API, use via the Messages API
Enterprise	Managed settings (org-wide)

Skills don't sync across surfaces - deploy separately to each.

平台	部署方式
Claude.ai	设置 > 功能 > 上传zip包
Claude Code（个人）	`~/.claude/skills/<name>/SKILL.md`
Claude Code（项目）	`.claude/skills/<name>/SKILL.md`
Claude Code（插件）	`<plugin>/skills/<name>/SKILL.md`
API	通过Skill Management API上传，通过Messages API使用
企业版	管理设置（全组织范围）

Skills不会在各平台间同步——需单独部署到每个平台。

Using Skills with the API

通过API使用Skills

Custom skills are uploaded through the Skill Management API;

anthropic

-type skills are pre-built by Anthropic. Both are used identically - pass them in the Messages API

container

parameter, each as

{type, skill_id, version}

where

type

anthropic

custom

. Up to 8 Skills per request. Requires the code execution tool and the beta headers

code-execution-2025-08-25

and

skills-2025-10-02

(plus

files-api-2025-04-14

for file upload/download). The API code execution environment has no network access and no runtime package installation - bundle dependencies or use pre-installed packages.

自定义技能通过Skill Management API上传；

anthropic

类型的技能由Anthropic预构建。两者的使用方式相同——在Messages API的

container

参数中传递，格式为

{type, skill_id, version}

，其中

type

为

anthropic

或

custom

。每个请求最多可使用8个Skills。需要代码执行工具和Beta头信息

code-execution-2025-08-25

、

skills-2025-10-02

（加上文件上传/下载所需的

files-api-2025-04-14

）。API代码执行环境无网络访问权限且无法安装运行时包——请捆绑依赖项或使用预安装的包。

Security

安全

Only use skills from trusted sources
No XML angle brackets in frontmatter (injection risk)
Audit all bundled scripts and resources before using third-party skills
Be cautious of skills that fetch from external URLs

仅使用可信来源的Skills
前置元数据中不要包含XML尖括号（存在注入风险）
在使用第三方Skills前审核所有捆绑的脚本和资源
谨慎使用从外部URL获取内容的Skills

Additional References

额外参考

Description writing guide - detailed examples and anti-patterns
Patterns and workflows - advanced patterns with MCP, subagents, iterative refinement
Claude Code features - context:fork, dynamic injection, argument substitution
Quality checklist - pre-upload validation checklist
ClawHub publishing -
```
metadata.openclaw
```
schema, moderation pipeline, reason codes catalog, pre-publish checklist

描述撰写指南 - 详细示例和反模式
模式与工作流 - 包含MCP、子Agent、迭代优化的高级模式
Claude Code功能 - context:fork、动态注入、参数替换
质量清单 - 上传前验证清单
ClawHub发布指南 -
```
metadata.openclaw
```
schema、审核流程、原因代码目录、发布前清单

skills-best-practices

Original

Translation

Skills Best Practices

Skills最佳实践

Quick Start

快速开始

My Skill Name

My Skill Name

Core Design Principles

核心设计原则

Progressive Disclosure (Most Important)

渐进式披露（最重要）

Advanced features

高级功能

Composability

可组合性

Portability

可移植性

Writing the Description (Critical)

描述撰写（关键）

Rules

规则

Good vs Bad

正反示例

GOOD - specific, actionable, includes triggers

良好示例 - 具体、可操作、包含触发词

BAD - too vague

不良示例 - 过于模糊

BAD - missing triggers

不良示例 - 缺少触发场景

Frontmatter Reference

前置元数据参考

Required Fields

必填字段

Optional Fields (Claude Code)

可选字段（Claude Code）

Naming Conventions

命名规范

Structuring Instructions

指令结构

Be Concise

简洁性

GOOD (~50 tokens)

良好示例（约50令牌）

Extract PDF text

提取PDF文本

BAD (~150 tokens)

不良示例（约150令牌）

Extract PDF text

提取PDF文本

Avoid Too Many Options

避免过多选项

BAD: "Use pypdf, or pdfplumber, or PyMuPDF, or pdf2image..."

不良示例："使用pypdf，或pdfplumber，或PyMuPDF，或pdf2image..."

GOOD: "Use pdfplumber for text extraction. For scanned PDFs needing

良好示例："使用pdfplumber进行文本提取。对于需要OCR的扫描版PDF，改用pdf2image搭配pytesseract。"

OCR, use pdf2image with pytesseract instead."

Set Degrees of Freedom

设置自由度

Recommended SKILL.md Structure

推荐的SKILL.md结构

Skill Name

技能名称

Quick start

快速开始

Workflow Decision Tree

工作流决策树

Detailed Instructions

详细指令

Examples

示例

Troubleshooting

故障排除

Reference Files

参考文件

BAD: Too deep

不良示例：层级过深

GOOD: One level

良好示例：一级深度