Back to Details

skill-authoring

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Authoring

技能创作

Create predictable Agent Skills through progressive disclosure, strong context pointers, checkable completion criteria, and single-sourced behavior.
通过渐进式披露、明确的上下文指引、可验证的完成标准和单一来源行为，创建可预测的Agent Skills。

Principles

原则

  • One skill per trigger phrase. A skill claims one thing a user would say. Two skills that would answer the same utterance are one skill; one skill that answers several unrelated utterances is several skills.
  • Split by verb, never by noun. Verbs route; nouns collide. 
    create
    and 
    refine
    are two skills. Feature, Epic, and Story are one skill that infers the type, because the user often does not know which they want.
  • Weight the split by what a misroute costs. Merge where a misroute produces a wrong write; split where it produces an obvious wrong answer. A read-only misroute is visible immediately; a wrong mutation is not.
  • A skill needing a disambiguating sub-command is two skills. If the body opens by asking which mode the user wants, the router should have decided.
  • Keep every-branch steps in 
    SKILL.md
    ; disclose branch-only reference behind a pointer that says when to read it.
  • Keep references one level deep and independently usable.
  • Keep descriptions below 1024 characters and skill bodies below 500 lines. The body limit governs 
    SKILL.md
    only — measure the whole directory too, and settle it with the question the line count only hints at: which of these vocabularies does a caller have to learn? One trigger phrase commits the caller to one. Two skills in this pack reached 4,029 and 7,784 total lines while their 
    SKILL.md
    files stayed comfortably compliant.
  • Put deterministic validation and transformation in scripts.
  • 每个触发短语对应一项技能。一项技能对应用户可能说出的一个需求。两个能响合同一表述的技能应合并为一个；一个能响应多个无关表述的技能应拆分为多个。
  • 按动词拆分，而非按名词。动词用于路由；名词易冲突。
    create
    （创建）和
    refine
    （优化）是两项技能。Feature（特性）、Epic（史诗）和Story（用户故事）属于同一项技能，可推断类型，因为用户通常不清楚自己需要哪一种。
  • 根据路由错误的代价决定拆分方式。若路由错误会导致错误的「写入」操作，则合并技能；若会导致明显错误的「回答」，则拆分技能。只读操作的路由错误会立即显现；错误的变更操作则不会。
  • 需要明确子命令来消除歧义的技能应拆分为两项。如果技能主体开头就询问用户想要哪种模式，那么路由环节就应该提前做出判断。
  • 将所有分支通用的步骤放在
    SKILL.md
    中；将仅特定分支需要的参考内容放在带有「何时阅读」指引的链接后。
  • 保持参考内容仅一层深度，且可独立使用。
  • 保持描述内容不超过1024字符，技能主体不超过500行。行数限制仅针对
    SKILL.md
    文件——同时也要统计整个目录的行数，并思考行数背后的核心问题：**调用者需要学习哪些术语？**一个触发短语对应一套术语。本集合中有两项技能的总目录行数分别达到了4029和7784行，但它们的
    SKILL.md
    文件仍完全符合规范。
  • 将确定性验证和转换逻辑放在脚本中。

Duplication

重复内容处理

Judge it by layer, not by volume.
Prompt duplication is forbidden. When the same instructions, protocol, or domain rule would appear in two skills: extract a reference skill when nothing owns it, enforce the existing interface when a module already does, or document it once when it is a rule rather than a capability. Two callers is the threshold for extracting; one caller means it belongs inside its owner.
Code duplication is expected. Bundled scripts are self-contained so a skill can be installed alone. Copy the helper rather than reaching across a seam.
A rule the agent needs at runtime, in whatever repository it is working in, has to live in a skill. A repository's own 
AGENTS.md
, decision records, and glossary govern work inside that checkout and do not travel with an installed skill — so a skill that cites them is broken for everyone who installs it.
按层级判断，而非按体量。
提示语重复是禁止的。当相同的指令、协议或领域规则出现在两项技能中时：若没有归属主体，则提取为参考技能；若已有模块实现，则遵循现有接口；若属于规则而非能力，则统一记录一次。当有两个调用者时，就达到了提取的阈值；只有一个调用者时，内容应归属于其所属主体。
代码重复是允许的。捆绑脚本是独立封装的，因此技能可单独安装。复制辅助代码，而非跨模块调用。
代理在运行时需要的规则，无论在哪个仓库中工作，都必须包含在技能中。仓库自身的
AGENTS.md
、决策记录和术语表仅适用于该仓库内的工作，不会随安装的技能一同迁移——因此引用这些内容的技能对其他安装者来说是无法正常使用的。

Naming

命名规则

A name describes its subject. Name by domain then verb, matching the trigger phrase the skill claims: 
<domain>-create
, 
<domain>-review
. Sibling skills use the same word for the same thing.
Ask what the skill is about, and let the answer decide the name. A skill about one product or system takes that product's name; a skill that is genuinely generic takes a generic name, even when it is published alongside product-specific ones. A prefix that overstates scope is worse than none — it promises knowledge the skill does not have.
Names are read by people, in a flat list where the folder is gone. Routing is a separate problem, solved by the description: keep the literal proper nouns — project keys, repository names, file names, tool names, an example identifier — because a literal token is the strongest anchor available.
That anchoring works on presence, so never put a literal in a description in order to disclaim it. "A key such as ABC-123 is not a sprint" makes the skill a candidate for exactly the request it is refusing. State the exclusion without the token: "works on a team and a board, never on a single issue key".
名称应描述技能的主题。按领域+动词的方式命名，与技能对应的触发短语匹配：
<领域>-create
、
<领域>-review
。同系列技能对同一事物使用相同的表述。
思考技能的核心内容，以此决定名称。针对某一产品或系统的技能使用该产品的名称；真正通用的技能使用通用名称，即使它与特定产品的技能一同发布。夸大范围的前缀比没有前缀更糟——它会承诺技能不具备的知识。
名称由人阅读，且显示在扁平列表中（文件夹结构不可见）。路由是另一个问题，由描述内容解决：保留字面专有名词——项目键、仓库名称、文件名、工具名称、示例标识符——因为字面标记是最有效的锚点。
锚点的作用基于标记的存在，因此不要为了否定某个内容而在描述中加入字面标记。例如，「类似ABC-123的键不是迭代」会让该技能恰好成为它所拒绝的请求的候选。应在不使用标记的情况下说明排除项：「适用于团队和看板，不适用于单个问题键」。

Working inside a host repository

在宿主仓库内工作

Before designing a skill, read whatever conventions the repository states — typically 
AGENTS.md
, a glossary, and any decision records. Those bind the skill you are about to write. They do not bind the skill once installed, so nothing you write into the skill may depend on being able to read them.
Where the repository publishes a collection, expect it to define: which skills are human-invoked, whether a name prefix applies, how skills compose, where the membership manifest lives, and what the tests protect. Follow its answers.
在设计技能之前，请阅读仓库中规定的所有约定——通常是
AGENTS.md
、术语表和所有决策记录。这些约定约束你即将编写的技能。但这些约定不会约束已安装的技能，因此你编写的技能中不得依赖读取这些内容的能力。
如果仓库发布了技能集合，它通常会定义：哪些技能可由人工调用、是否需要名称前缀、技能如何组合、成员清单的位置以及测试保护的内容。请遵循这些定义。

Interview dependency

访谈依赖

Creating or interviewing for a skill requires an interview skill that stress-tests scope before drafting — 
/grilling
in this collection. If the host cannot invoke it by name, stop before drafting anything and say that creation is gated on it. Audit and consolidation do not require it unless they open an interview.
创建或访谈技能需要一个能在起草前测试范围的访谈技能——即本集合中的
/grilling
。若宿主无法通过名称调用该技能，请停止起草并说明创建技能需以该访谈技能为前提。审核和整合操作无需依赖该技能，除非它们需要开启访谈。

Conditional references

条件式参考

Load exactly one branch. Its own pointers name any specification, description, architecture, script, or quality reference needed later.
  • Read references/create.md to interview, draft, and review a new skill from scratch — "create a skill", "draft a SKILL.md", "package this expertise".
  • Read references/audit.md to review, repair, or diagnose an existing skill — "why does this never trigger", "check this SKILL.md", "improve this skill".
  • Read references/consolidation-guide.md to merge overlapping skills into fewer, or to test whether a merge already went too far. Finish through the Phase 5 review in references/create.md.
仅加载一个分支。该分支自身的链接包含后续所需的任何规范、描述、架构、脚本或质量参考内容。
  • 阅读references/create.md以访谈、起草和审核全新技能——适用于「创建技能」「起草SKILL.md」「打包专业知识为技能」等场景。
  • 阅读references/audit.md以审核、修复或诊断现有技能——适用于「为何此技能从未触发」「检查此SKILL.md」「优化此技能」等场景。
  • 阅读references/consolidation-guide.md以将重叠技能合并为更少的技能，或测试合并是否过度。完成后需通过references/create.md中的第5阶段审核。

Completion

完成标准

Work is complete when the selected branch's review checklist passes, every referenced resource resolves, and no behavior remains duplicated under an old skill name.
当所选分支的审核清单全部通过、所有引用资源均可访问、且旧技能名称下无重复行为残留时，工作即完成。