skills-manual

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skills Manual

技能手册

How to build effective skills for AI coding agents. For the full Anthropic guide, see

references/skill-builder-guide.md

如何为AI编码Agent构建高效技能。完整的Anthropic指南请参见

references/skill-builder-guide.md

。

Skill Structure

技能结构

your-skill-name/              # kebab-case, no spaces, no capitals, no underscores
  SKILL.md                    # Required — must be exactly this name (case-sensitive)
  references/                 # Optional — supporting docs loaded on demand
  scripts/                    # Optional — executable code
  assets/                     # Optional — templates, icons

The main file MUST be named
```
SKILL.md
```
— not
```
skill.md
```
,
```
SKILL.MD
```
, or anything else
Do NOT include
```
README.md
```
inside the skill folder
Folder name must be kebab-case (e.g.,
```
notion-project-setup
```
)

your-skill-name/              # kebab-case，无空格、无大写、无下划线
  SKILL.md                    # 必填——必须严格使用此名称（区分大小写）
  references/                 # 可选——按需加载的支持文档
  scripts/                    # 可选——可执行代码
  assets/                     # 可选——模板、图标

主文件必须命名为
```
SKILL.md
```
——不能是
```
skill.md
```
、
```
SKILL.MD
```
或其他名称
技能文件夹内请勿包含
```
README.md
```
文件夹名称必须使用kebab-case格式（例如：
```
notion-project-setup
```
）

YAML Frontmatter

YAML前置元数据

yaml

---
name: your-skill-name                     # Required — kebab-case, must match folder name
description: "What and when."             # Required — max 1024 chars, no < > brackets
license: MIT                              # Optional
allowed-tools: "Bash(python:*) WebFetch"  # Optional — restrict tool access
metadata:                                 # Optional
  author: Name
  version: 1.0.0
---

yaml

---
name: your-skill-name                     # 必填——kebab-case格式，必须与文件夹名称匹配
description: "功能与适用场景。"             # 必填——最多1024字符，不能包含< >括号
license: MIT                              # 可选
allowed-tools: "Bash(python:*) WebFetch"  # 可选——限制工具访问权限
metadata:                                 # 可选
  author: Name
  version: 1.0.0
---

Security Restrictions

安全限制

No XML angle brackets (
```
<
```
```
>
```
) in frontmatter — it appears in system prompt
No "claude" or "anthropic" in skill names (reserved)

前置元数据中不能包含XML尖括号（
```
<
```
```
>
```
）——这些内容会出现在系统提示中
技能名称中不能包含"claude"或"anthropic"（为保留名称）

Writing the Description

描述撰写

The description is the most important field. It controls when the skill gets loaded via progressive disclosure:

Frontmatter (always loaded) — Claude reads the description to decide relevance
SKILL.md body (loaded when relevant) — full instructions
Linked files (loaded on demand) — references, scripts, assets

The description MUST include both:

What the skill does
When to use it — specific trigger phrases users would actually say

Good:

yaml

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

Bad:

yaml

description: "Helps with projects."

To debug: ask Claude "When would you use the [skill name] skill?" — it will quote the description back, revealing what's missing.

描述是最重要的字段，它通过渐进式披露机制控制技能的加载时机：

前置元数据（始终加载）——Claude会读取描述来判断相关性
SKILL.md正文（相关时加载）——完整操作说明
关联文件（按需加载）——参考文档、脚本、资源

描述必须同时包含：

功能：技能能做什么
适用场景：用户实际会使用的特定触发短语

示例（良好）：

yaml

description: "管理Linear项目工作流，包括冲刺规划、任务创建和状态跟踪。当用户提及'sprint'、'Linear tasks'、'project planning'，或要求'create tickets'时使用。"

示例（不佳）：

yaml

description: "协助处理项目。"

调试方法：询问Claude "你会在什么时候使用[技能名称]技能？"——它会引用描述内容，从而揭示缺失的信息。

Writing Instructions

操作说明撰写

Structure

结构

markdown

---
name: your-skill
description: [...]
---

markdown

---
name: your-skill
description: [...]
---

Skill Name

技能名称

Instructions

操作步骤

Step-by-step workflow with clear actions.

包含明确操作的分步工作流。

Examples

示例

Common scenarios with expected inputs/outputs.

常见场景及预期输入/输出。

Troubleshooting

故障排除

Common errors, causes, and fixes.

undefined

常见错误、原因及解决方法。

undefined

Rules

规则

Lead with the most important rules
Be specific — include commands, file paths, expected outputs
Use numbered steps for sequential workflows, bullet points for guidelines
Show examples of correct and incorrect usage
Include error handling for common failures
Reference bundled files explicitly (e.g., "see
```
references/api-guide.md
```
")
Keep SKILL.md under 5,000 words — move detailed docs to
```
references/
```
Composability — assume other skills may be loaded simultaneously

优先列出最重要的规则
内容要具体——包含命令、文件路径、预期输出
顺序工作流使用编号步骤，指南类内容使用项目符号
展示正确和错误用法的示例
包含常见故障的错误处理方案
明确引用捆绑文件（例如："参见
```
references/api-guide.md
```
"）
SKILL.md字数控制在5000字以内——将详细文档移至
```
references/
```
目录
可组合性——假设其他技能可能同时加载

Iteration Signals

迭代信号

Signal	Meaning	Fix
Skill doesn't load when it should	Undertriggering	Add more trigger phrases and keywords to description
Skill loads for unrelated queries	Overtriggering	Add negative triggers, narrow scope
Claude doesn't follow instructions	Too verbose or ambiguous	Use bullet points, be explicit, move detail to references
Inconsistent results	Missing examples or validation	Add examples, error handling, quality checks

信号	含义	修复方案
技能在应加载时未加载	触发不足	在描述中添加更多触发短语和关键词
技能因无关查询加载	过度触发	添加否定触发条件，缩小适用范围
Claude未遵循操作说明	内容过于冗长或模糊	使用项目符号，表述明确，将细节移至参考文档
结果不一致	缺少示例或验证机制	添加示例、错误处理和质量检查