skill-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Writing

Skill编写

Goal

目标

Produce a usable Skill package: SKILL.md (always) + optional reference files and scripts (when helpful). Optimize for: discoverability, correctness, concision, testability.

产出可用的Skill包：必含SKILL.md，可选包含参考文件和脚本（如有需要）。需在可发现性、准确性、简洁性、可测试性上进行优化。

Output contract

输出约定

When triggered, deliver:

SKILL.md with valid YAML frontmatter (
```
name
```
,
```
description
```
)
If needed: suggested folder layout + filenames + brief contents for each extra file (do NOT bloat SKILL.md)
3+ evaluation prompts to test activation + behavior

触发后需交付：

包含有效YAML前置元数据（
```
name
```
、
```
description
```
）的SKILL.md
如有需要：建议的文件夹结构、文件名及每个额外文件的简要内容（请勿冗余SKILL.md内容）
3个及以上用于测试激活逻辑与行为的评估提示词

Workflow (do in order)

工作流程（按顺序执行）

1) Extract requirements

1) 提取需求

Capture (infer if missing):

Primary job: what the Skill reliably accomplishes
Triggers: phrases/users requests that should activate it
Inputs: files/types/tools needed (pdf/docx/xlsx/pptx, repos, APIs, etc.)
Constraints: tone, formatting, compliance, latency, determinism
Failure modes: common mistakes to guardrail

捕捉（若缺失则推断）以下信息：

核心功能：该Skill可稳定实现的功能
触发条件：可激活该Skill的语句或用户请求
输入项：所需的文件类型/工具（如pdf/docx/xlsx/pptx、代码仓库、API等）
约束条件：语气、格式、合规性、延迟、确定性要求
失败场景：需要防范的常见错误

2) Design information architecture

2) 设计信息架构

Use progressive disclosure:

Keep SKILL.md short (prefer <300 lines)
Push long content into one-level-deep files:
- ```
REFERENCE.md
```
  (APIs/schemas)
- ```
WORKFLOWS.md
```
  (multi-step procedures)
- ```
EXAMPLES.md
```
  (I/O pairs)
- ```
CHECKLISTS.md
```
  (validation rubrics)
Prefer scripts for deterministic transforms/validation; document how to run them.

采用渐进式披露原则：

保持SKILL.md内容简短（建议少于300行）
将长篇内容放入一级深度的文件中：
- ```
REFERENCE.md
```
  （API/数据结构）
- ```
WORKFLOWS.md
```
  （多步骤流程）
- ```
EXAMPLES.md
```
  （输入输出示例对）
- ```
CHECKLISTS.md
```
  （验证准则）
对于确定性的转换/验证操作，优先使用脚本实现，并记录运行方法。

3) Write frontmatter (strict)

3) 编写前置元数据（严格规范）

```
name
```
: lowercase letters/numbers/hyphens only; <=64 chars; no reserved words
```
description
```
: 3rd-person; states what + when to use; <=1024 chars; non-empty

```
name
```
：仅允许小写字母、数字、连字符；长度不超过64字符；不得使用保留字
```
description
```
：第三人称表述；需说明功能及适用场景；长度不超过1024字符；不能为空

4) Write SKILL.md body (minimum necessary)

4) 编写SKILL.md主体内容（仅保留必要信息）

Include only what improves success:

Goal
When to use / When not to use
Default approach (1 best path)
Decision points (few, explicit)
Templates (copy/pasteable)
Validation loop (draft → check → fix → finalize)
Examples (at least 2)

仅保留有助于提升使用成功率的内容：

目标
适用场景 / 不适用场景
默认实现方案（最优路径）
决策节点（少量、明确）
模板（可直接复制使用）
验证流程（草稿→检查→修正→定稿）
示例（至少2个）

5) Add evaluations

5) 添加评估内容

Create at least 3 tests:

Activation test (should trigger)
Non-activation test (should not trigger)
Edge case (most likely failure mode)

创建至少3项测试：

激活测试（应触发Skill）
非激活测试（不应触发Skill）
边缘场景测试（最可能出现的失败情况）

Templates

模板

Frontmatter template

前置元数据模板

yaml

---
name: <lowercase-hyphen-name>
description: <does X. Use when Y.>
---

yaml

---
name: <lowercase-hyphen-name>
description: <does X. Use when Y.>
---

SKILL.md skeleton (recommended)

SKILL.md 骨架（推荐）

markdown

undefined

markdown

undefined

<Skill Title>

Goal

...

When to use

When not to use

Inputs

Outputs

Default workflow

Validation checklist

Examples

Example 1

Input: ... Output: ...

undefined

Input: ... Output: ...

undefined

“High-level + references” pattern

“概览+引用”模式

In SKILL.md, link (one level deep):

```
REFERENCE.md
```
for details
```
WORKFLOWS.md
```
for complex steps
```
EXAMPLES.md
```
for many examples Avoid SKILL.md → advanced.md → details.md chains.

在SKILL.md中，仅链接一级深度的文件：

```
REFERENCE.md
```
用于存放详情
```
WORKFLOWS.md
```
用于存放复杂步骤
```
EXAMPLES.md
```
用于存放多示例避免出现SKILL.md → advanced.md → details.md这类多层级引用链。

Writing rules (hard)

编写规则（强制遵守）

One primary approach; alternatives only as fallback
No time-sensitive branching (“before/after date”); instead: “Current method” + “Legacy (deprecated)” section
Consistent terminology (pick one term per concept)
No Windows paths; use forward slashes
If scripts exist: specify exact commands + expected outputs
Always include a validator/checklist step for fragile tasks

仅提供一种核心实现方案，替代方案仅作为 fallback
不允许基于时间的分支逻辑（如“某日期之前/之后”）；应改为：“当前方案” + “遗留方案（已废弃）”章节
术语保持一致（每个概念对应唯一术语）
不使用Windows路径格式；统一使用正斜杠
若包含脚本：需明确指定命令及预期输出
对于易出错的任务，必须包含验证器/检查清单步骤

Common anti-patterns

常见反模式

Vague description (“helps with documents”)
Too many options (“use A/B/C/D…”)
Long tutorials Claude already knows
Deeply nested references
“Just figure it out” steps without verification

模糊的描述（如“处理文档”）
过多选项（如“可使用A/B/C/D…”）
包含Claude已熟知的冗长教程
深度嵌套的引用
无验证步骤的“自行判断”环节

Evaluation pack (copy/paste)

评估包（可直接复制）

Write 3+ prompts like:

“Create a Skill that … (include triggers + constraints). Return SKILL.md.”
“User asks for adjacent task that should NOT trigger; respond normally.”
“Edge case: missing inputs or conflicting constraints; infer defaults and still produce SKILL.md.”

编写3个及以上如下格式的提示词：

“Create a Skill that … (include triggers + constraints). Return SKILL.md.”
“User asks for adjacent task that should NOT trigger; respond normally.”
“Edge case: missing inputs or conflicting constraints; infer defaults and still produce SKILL.md.”

Done criteria

完成标准

Frontmatter validates
SKILL.md under 500 lines
Clear activation triggers in description + “When to use”
Includes checklist + examples + evaluations

前置元数据符合规范
SKILL.md内容不超过500行
描述与“适用场景”中明确标注激活触发条件
包含检查清单、示例与评估内容