anthropic-skill-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Skills

构建Skill

Build skills that trigger correctly, execute reliably, and stay concise.

打造触发精准、执行可靠且简洁精炼的Skill。

Core Principles

核心原则

Use progressive disclosure:
- Frontmatter (
```
name
```
  ,
```
description
```
  ) for trigger selection.
- ```
SKILL.md
```
  body for core workflow.
- ```
references/
```
  for deep details loaded only when needed.
Keep skills composable: avoid assumptions that this is the only active skill.
Prefer deterministic scripts for fragile validation logic.

使用渐进式披露：
- Frontmatter（
```
name
```
  ,
```
description
```
  ）用于触发选择。
- ```
SKILL.md
```
  主体内容用于核心工作流。
- ```
references/
```
  用于仅在需要时加载的深度细节。
保持Skill的可组合性：不要假设这是唯一激活的Skill。
对于易出错的验证逻辑，优先使用确定性脚本。

Workflow

工作流

Define 2-3 concrete use cases.
Draft trigger-strong frontmatter.
Design reusable resources (
```
scripts/
```
,
```
references/
```
,
```
assets/
```
).
Write actionable instructions and error handling.
Run triggering/functional/performance tests.
Iterate based on under-trigger/over-trigger signals.

定义2-3个具体用例。
编写触发精准的Frontmatter。
设计可复用资源（
```
scripts/
```
、
```
references/
```
、
```
assets/
```
）。
编写可执行的操作说明与错误处理逻辑。
运行触发测试/功能测试/性能测试。
根据触发不足/过度触发的反馈迭代优化。

1) Define Use Cases

1) 定义用例

Capture for each use case:

User phrasing (what they actually say)
Intended result
Multi-step workflow and required tools (built-in and/or MCP)
Failure points that need guardrails

If use cases are vague, ask targeted follow-up questions before authoring.

为每个用例记录：

用户实际表述（他们真实会说的内容）
预期结果
多步骤工作流与所需工具（内置工具及/或MCP）
需要防护机制的失败点

若用例模糊，在开始编写前先提出针对性的跟进问题。

2) Frontmatter Design (Most Important)

2) Frontmatter设计（重中之重）

Write only what is needed to trigger correctly.

Required fields:

```
name
```
: kebab-case, matches folder name
```
description
```
: include BOTH
- What the skill does
- When to use it (trigger phrases/context/file types)

Description formula:

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

Good pattern:

"Processes PDF legal documents for contract review. Use when users ask for clause extraction, risk flags, or redline summaries from .pdf contracts."

Bad pattern:

"Helps with projects."

Precision controls:

Add negative triggers to reduce over-triggering.
Mention relevant file types when applicable.
Keep wording aligned with real user phrases from use cases.

仅编写确保精准触发所需的内容。

必填字段：

```
name
```
: 采用kebab-case格式，与文件夹名称一致
```
description
```
: 需同时包含
- Skill的功能
- 使用场景（触发短语/上下文/文件类型）

描述公式：

[功能说明] + [使用场景] + [核心能力]

优秀示例：

"处理PDF法律文档以进行合同审核。适用于用户要求从.pdf合同中提取条款、标记风险或生成修订摘要的场景。"

反面示例：

"助力项目开展。"

精准度控制：

添加负向触发规则以减少过度触发。
适用时提及相关文件类型。
措辞与用例中用户的真实表述保持一致。

3) Resource Plan

3) 资源规划

```
scripts/
```
: deterministic checks/transforms used repeatedly
```
references/
```
: large docs, domain logic, variant-specific guidance
```
assets/
```
: templates and artifacts used in outputs

Rules:

Keep
```
SKILL.md
```
compact; link to
```
references/
```
.
Avoid extra docs in skill folder (
```
README.md
```
, changelog, etc.).

```
scripts/
```
: 用于重复执行的确定性检查/转换逻辑
```
references/
```
: 大型文档、领域逻辑、特定变体的指导内容
```
assets/
```
: 输出中使用的模板与工件

规则：

保持
```
SKILL.md
```
简洁；通过链接指向
```
references/
```
中的内容。
Skill文件夹中避免额外文档（如
```
README.md
```
、变更日志等）。

4) Instruction Writing

4) 操作说明编写

Write imperative, testable steps.

Include:

Clear step order and dependencies
Validation checkpoints
Common errors with concrete fixes
Example user inputs and expected outputs

For critical checks, prefer scripts over prose-only checks.

编写命令式、可测试的步骤。

需包含：

清晰的步骤顺序与依赖关系
验证检查点
常见错误及具体修复方案
用户输入示例与预期输出

对于关键检查，优先使用脚本而非纯文字描述的检查逻辑。

5) Test Protocol

5) 测试方案

Run these three test groups.

运行以下三类测试。

A. Triggering Tests

A. 触发测试

Should trigger on obvious requests
Should trigger on paraphrased requests
Should NOT trigger on unrelated requests

Target benchmark:

Trigger on ~90% of relevant prompts in a 10-20 prompt suite

应在明确请求时触发
应在转述后的请求时触发
不应在无关请求时触发

目标基准：

在包含10-20个提示的测试集中，对约90%的相关提示触发Skill

B. Functional Tests

B. 功能测试

Validate:

Correct outputs
Tool/API call success
Error handling paths
Edge cases

验证：

输出正确性
工具/API调用成功率
错误处理流程
边缘情况

C. Performance Comparison

C. 性能对比

Compare with vs without skill:

Number of clarification turns
Failed tool/API calls
Token usage
End-to-end completion quality

对比启用与未启用Skill的情况：

澄清对话轮次数量
工具/API调用失败次数
Token使用量
端到端完成质量

6) Iteration Rules

6) 迭代规则

Under-triggering signals:

Skill does not load when expected
Users keep manually invoking it

Fix:

Add clearer trigger phrases and technical terms to
```
description
```
.

Over-triggering signals:

Skill loads for unrelated requests

Fix:

Add negative triggers and tighten scope language.

Execution issues:

Inconsistent outputs, retries, user corrections

Fix:

Tighten instructions, add explicit validations, and script critical checks.

触发不足的信号：

Skill未在预期场景下加载
用户持续手动调用Skill

修复方案：

在
```
description
```
中添加更明确的触发短语与技术术语。

过度触发的信号：

Skill在无关请求时加载

修复方案：

添加负向触发规则并收紧范围描述。

执行问题：

输出不一致、重试、用户修正

修复方案：

收紧操作说明、添加显式验证，并为关键检查编写脚本。

Troubleshooting Quick Guide

快速故障排除指南

Upload fails with missing
```
SKILL.md
```
: file must be exactly
```
SKILL.md
```
.
Invalid frontmatter: verify YAML delimiters
```
---
```
and valid syntax.
Invalid skill name: use lowercase kebab-case.
Skill not followed: move critical instructions to top and make them concrete.
Slow behavior: move long content to
```
references/
```
; reduce enabled skills.

因缺少
```
SKILL.md
```
导致上传失败：文件名称必须严格为
```
SKILL.md
```
。
无效前置元数据：验证YAML分隔符
```
---
```
与语法正确性。
无效Skill名称：使用小写kebab-case格式。
Skill未被执行：将关键操作说明移至顶部并具体化。
运行缓慢：将长内容移至
```
references/
```
；减少启用的Skill数量。

Packaging

打包

Validate and package before distribution:

bash

python3 .agents/skills/skill-creator/scripts/quick_validate.py <skill-dir>
python3 .agents/skills/skill-creator/scripts/package_skill.py <skill-dir>

分发前先验证并打包：

bash

python3 .agents/skills/skill-creator/scripts/quick_validate.py <skill-dir>
python3 .agents/skills/skill-creator/scripts/package_skill.py <skill-dir>

References

参考资料

```
references/checklist.md
```
```
references/prompt-templates.md
```
```
references/patterns.md
```
```
references/source.md
```
: source PDF and extracted principles
```
references/trigger-examples.md
```
: trigger/non-trigger examples for description tuning
```
references/failure-remedies.md
```
: failure patterns and minimum effective fixes

```
references/checklist.md
```
```
references/prompt-templates.md
```
```
references/patterns.md
```
```
references/source.md
```
: 源PDF与提炼的原则
```
references/trigger-examples.md
```
: 用于优化描述的触发/非触发示例
```
references/failure-remedies.md
```
: 失败模式与最小有效修复方案