skill-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Design

技能设计

Design skills as reusable behavior systems that are easy to discover and execute.

将技能设计为易于发现和执行的可复用行为系统。

Trigger Contract

触发约定

Use this skill when users ask to:

create a new skill
refactor an existing skill
improve trigger quality or discoverability
align
```
SKILL.md
```
,
```
README.md
```
, and
```
references/
```
remove ambiguity or conflicting guidance

Typical trigger phrases:

"create a skill for X"
"design a new skill"
"refactor this skill"
"make this skill reusable"
"align README and SKILL behavior"

当用户提出以下需求时，可使用本技能：

创建新技能
重构现有技能
提升触发质量或可发现性
对齐
```
SKILL.md
```
、
```
README.md
```
与
```
references/
```
目录内容
消除模糊或相互矛盾的指引

典型触发语句：

"为X创建一个技能"
"设计一个新技能"
"重构这个技能"
"让这个技能可复用"
"对齐README与SKILL的行为逻辑"

Core Principles

核心原则

Optimize for reliable agent behavior, not document aesthetics.
Make trigger conditions explicit and searchable.
Keep instructions executable and verifiable.
Avoid implicit project context unless explicitly required.

以Agent的可靠行为为优化目标，而非文档美观性。
使触发条件明确且可被搜索。
确保指令可执行且可验证。
除非明确需要，否则避免隐含项目上下文。

Writing Style Rules

写作风格规则

Use imperative voice.
Keep sections short and high-signal.
Prefer concrete constraints over abstract advice.
Use
```
MUST
```
/
```
NEVER
```
for true invariants (safety, correctness, irreversible failure).
For normal guidance, use direct action verbs and clear defaults.
Avoid weak modal wording for hard rules (
```
should
```
,
```
could
```
,
```
may
```
,
```
consider
```
,
```
usually
```
).
Remove narrative text that does not change execution.

使用祈使语气。
保持章节简短且信息密度高。
优先使用具体约束而非抽象建议。
对于真正的不变规则（如安全性、正确性、不可逆故障相关），使用
```
MUST
```
/
```
NEVER
```
。
对于常规指引，使用直接的动作动词和明确的默认规则。
对于硬性规则，避免使用模糊的情态用词（如
```
should
```
、
```
could
```
、
```
may
```
、
```
consider
```
、
```
usually
```
）。
删除不影响执行的叙述性文本。

Metadata and Discovery

元数据与可发现性

Write frontmatter
```
description
```
in third person.
Include both what the skill does and when to use it.
Keep trigger terms concrete (
```
file type
```
,
```
task type
```
,
```
user phrasing
```
).
Do not put workflow details in
```
description
```
; keep those in the body.

以第三人称撰写前置元数据中的
```
description
```
。
需同时说明技能的功能及其适用场景。
触发术语要具体（如
```
文件类型
```
、
```
任务类型
```
、
```
用户表述
```
）。
不要将工作流细节放入
```
description
```
中，应放在正文部分。

Workflow

工作流

Phase 1 - Define Contract

阶段1 - 定义约定

Define who uses the skill and when it triggers.
Define non-negotiable behavior and failure boundaries.
Define deterministic vs heuristic decisions.

定义技能的使用者及其触发时机。
定义不可协商的行为规则与故障边界。
定义确定性决策与启发式决策的区别。

Phase 2 - Structure Content

阶段2 - 内容结构化

Write trigger and constraints first.
Keep
```
SKILL.md
```
as execution logic and decision constraints.
Move bulky detail to
```
references/
```
and keep one source of truth per schema.
Add
```
scripts/
```
only for repeatable deterministic operations.
When composing with other skills, invoke them by name and never copy their instruction bodies.

先撰写触发条件与约束规则。
将
```
SKILL.md
```
作为执行逻辑与决策约束的载体。
将冗余细节移至
```
references/
```
目录，每个模式仅保留单一可信来源。
仅为可重复的确定性操作添加
```
scripts/
```
目录。
与其他技能组合时，通过名称调用它们，切勿复制其指令内容。

Phase 3 - Author/Refactor SKILL

阶段3 - 编写/重构SKILL

Tighten description and trigger wording.
Convert soft guidance into explicit, executable instructions.
Provide one default path first; add alternatives only when necessary.
Remove duplicate or contradictory instructions.

精简描述与触发语句的措辞。
将模糊指引转化为明确、可执行的指令。
先提供一条默认路径，仅在必要时添加替代方案。
删除重复或相互矛盾的指令。

Phase 4 - Align README (Human-Facing)

阶段4 - 对齐README（面向人类）

Keep README value-first: problem -> value -> example -> activation.
Treat
```
README.md
```
as style charter for future AI output quality.
Keep implementation internals out of README.
Keep claims behavior-accurate.

README要以价值为核心：问题 -> 价值 -> 示例 -> 激活方式。
将
```
README.md
```
视为未来AI输出质量的风格规范。
不要在README中包含实现细节。
确保所述内容与实际行为一致。

Phase 5 - Validate

阶段5 - 验证

Run available validator for your environment.
If no validator exists, run manual consistency checks.
Confirm no repository-specific assumptions remain unless explicitly intended.

运行适用于当前环境的验证工具。
若没有可用的验证工具，则进行手动一致性检查。
确认不存在特定仓库的隐含假设，除非是明确有意保留的。

Progressive Disclosure Rules

渐进式披露规则

Keep
```
SKILL.md
```
body compact (target under 500 lines).
Put advanced or domain-specific detail in
```
references/
```
.
Link reference files directly from
```
SKILL.md
```
(avoid deep nested references).
For long reference files (100+ lines), add a short table of contents.

保持
```
SKILL.md
```
正文简洁（目标少于500行）。
将高级或领域特定的细节放入
```
references/
```
目录。
从
```
SKILL.md
```
直接链接到参考文件（避免深层嵌套引用）。
对于较长的参考文件（100行以上），添加简短的目录。

README Rules

README规则

In this skill,
```
README.md
```
means the skill-level README (for example
```
skills/<skill-name>/README.md
```
), not the repository root README.
```
README.md
```
is not required by Agent Skills Specification.
```
README.md
```
is recommended for faster human understanding and adoption.
Keep README focused on outcomes, style expectations, and activation cues.

在本技能中，
```
README.md
```
指的是技能级别的README（例如
```
skills/<skill-name>/README.md
```
），而非仓库根目录的README。
Agent Skills规范不强制要求
```
README.md
```
。
为了让人类更快理解和采用，建议添加
```
README.md
```
。
README应聚焦于成果、风格预期和激活提示。

Anti-Patterns

反模式

Hardcoded local paths as universal defaults.
Tool lock-in with no fallback path.
Copying external skill instruction bodies instead of invoking the source skill.
Workflow summary inside frontmatter
```
description
```
.
Duplicated schema definitions across files.
Long narrative prose with no executable instruction.
Repeating
```
MUST
```
/
```
NEVER
```
for non-critical guidance.
Offering too many equivalent options without a default recommendation.

将硬编码的本地路径作为通用默认值。
工具锁定且无备选方案。
复制外部技能的指令内容而非调用源技能。
在前置元数据的
```
description
```
中包含工作流摘要。
在多个文件中重复定义模式。
冗长的叙述性文本但无任何可执行指令。
对非关键指引重复使用
```
MUST
```
/
```
NEVER
```
。
提供过多等效选项但未给出默认推荐。

Done Checklist

完成检查清单

```
SKILL.md
```
has explicit trigger contract and executable workflow.
Frontmatter
```
description
```
clearly states what + when.
```
README.md
```
defines style expectations for future contributions.
```
references/
```
contains heavy details only when needed.
No stale terms, duplicated schema ownership, or contradictory rules.
Validation evidence is recorded (tool-based or manual).

Example validation command:

npx --yes skills-ref validate ./skills/<skill-name>

```
SKILL.md
```
包含明确的触发约定和可执行工作流。
前置元数据的
```
description
```
清晰说明功能+适用场景。
```
README.md
```
定义了未来贡献的风格预期。
```
references/
```
仅在必要时包含冗余细节。
不存在过时术语、重复的模式所有权或相互矛盾的规则。
已记录验证证据（工具验证或手动验证）。

示例验证命令：

npx --yes skills-ref validate ./skills/<skill-name>

。