writing-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Skills

编写Skill

A skill supplies task-specific knowledge or a reliable operation the model would otherwise have to rediscover. Optimize for correct outcomes, useful evidence, and low overhead. Identical process on every run is useful only where ordering is part of the contract.

Skill为模型提供特定任务的知识或可靠操作流程，否则模型需要自行重新探索这些内容。优化方向为正确的结果、有用的依据以及低开销。仅当顺序是约定的一部分时，每次运行都采用完全相同的流程才是有意义的。

Choose the Scope

选择适用范围

Follow the user's requested outcome and existing authorization. A skill does not add approval steps or override repository policy.
Keep a rule only when it changes a relevant decision or prevents an evidenced failure. Delete generic advice, duplicated rules, obsolete model assumptions, and rhetorical pressure.
Name concrete triggers and exclusions in the description. Avoid firing on every code edit, every test, or every completion when the procedure is only needed for a narrower problem.
Distinguish shared guidance from repository-specific policy. Edit shared sources first; preserve local variants when synchronizing. Check whole-directory differences before an installer overwrites a skill.

遵循用户要求的结果和现有授权。Skill不得添加审批步骤或覆盖仓库策略。
仅保留会改变相关决策或可预防已证实故障的规则。删除通用建议、重复规则、过时的模型假设以及冗余的话术要求。
在描述中明确具体的触发条件和排除场景。当流程仅针对更窄范围的问题时，避免在每次代码编辑、每次测试或每次生成内容时触发该Skill。
区分共享指南与仓库特定策略。优先编辑共享源文件；同步时保留本地变体。在安装程序覆盖Skill前，检查整个目录的差异。

Create or Revise

创建或修订

Identify the outcome, owning files, known failure, and existing instructions. Reuse the current conversation's evidence; recollect only missing or stale material.
Keep the minimum common contract in
```
SKILL.md
```
; link branch-specific references with a condition and the section needed. Read a complete schema or tightly coupled procedure when its whole contract is necessary, not every reference by default.
State required order only for dependencies, mutations, authorization, or cleanup. Let independent searches batch and let the agent choose routine implementation details.
Define completion by the requested deliverable and its applicable checks. Reuse evidence for unchanged inputs. Do not add a mandatory report, subagent round, test suite, or confirmation merely because the skill is installed.
Check changed triggers, links, metadata, and any affected helper behavior. For a small prose edit, summarize this review; for a new skill or broad rewrite, use
```
references/checklist.md
```
. Fix material failures at their source.

For a new package, read

references/authoring-procedure.md

;

assets/SKILL.template.md

is an optional skeleton. Resolve bundled helpers from the skill's actual directory. The read-only metadata helper is

python3 <writing-skills-dir>/scripts/validate-metadata.py --name "[name]" --description "[description]"

明确目标结果、所属文件、已知故障以及现有说明。复用当前对话中的依据；仅补充缺失或过时的内容。
在
```
SKILL.md
```
中保留最精简的通用约定；通过条件语句和所需章节链接分支特定的参考内容。仅当完整约定必要时才读取完整的架构或紧密耦合的流程，而非默认读取所有参考内容。
仅在涉及依赖关系、变更操作、授权或清理步骤时规定必要的执行顺序。允许独立搜索任务批量处理，并让Agent选择常规实现细节。
根据请求的交付成果及其适用检查来定义完成标准。对未变更的输入复用已有依据。不得仅因Skill已安装就强制添加报告、子Agent轮询、测试套件或确认步骤。
检查已更改的触发条件、链接、元数据以及任何受影响的辅助工具行为。对于小型文本编辑，总结审查结果；对于新Skill或大范围重写，使用
```
references/checklist.md
```
。从根源修复实质性故障。

若创建新包，请阅读

references/authoring-procedure.md

；

assets/SKILL.template.md

是可选的模板文件。从Skill的实际目录解析绑定的辅助工具。只读元数据辅助工具的调用命令为

python3 <writing-skills-dir>/scripts/validate-metadata.py --name "[name]" --description "[description]"

。

Diagnose and Measure

诊断与评估

If a necessary reference was missed, use

references/loading-diagnosis.md

to distinguish a bad trigger, inaccessible path, conflicting rule, stale content, and model error. Strengthen the relevant pointer or fix the helper; extra emphasis is not the default repair.

Evaluate behavior-changing guidance on representative tasks under the same model/harness when practical: correctness, rework, unnecessary questions, tool calls, and elapsed time. Include successful runs as controls. Count reference reads and skill invocations as costs or diagnostics, never success by themselves. State when only static review was performed; do not claim measured improvements without comparative runs.

Terminology, when needed:

references/glossary.md

若遗漏了必要的参考内容，请使用

references/loading-diagnosis.md

来区分触发条件错误、路径不可访问、规则冲突、内容过时以及模型错误。强化相关指向或修复辅助工具；默认不采用额外强调的方式进行修复。

在可行的情况下，在相同模型/测试环境下，针对代表性任务评估行为变更指南的效果：正确性、返工率、不必要的问题、工具调用次数以及耗时。将成功运行作为对照。将参考内容读取次数和Skill调用次数视为成本或诊断指标，而非成功的标准。说明仅进行了静态审查的情况；若无对比运行数据，不得声称有可衡量的改进。

术语说明（如需）：

references/glossary.md

。