skill-writing

技能编写

在 .agents/skills/ 中创建项目本地技能。通过相对符号链接将其提供给 Claude Code。使用仓库的规范技能验证器验证结果。

提示词编写指南

为当前的 Claude 和 GPT Agent 模型编写所有新技能及其内容，而不是针对某一个模型。不要在技能正文中提及模型名称、模型版本或特定于某个模型的默认行为。选择或配置模型，或说明模型归属的内容除外，例如 model: 字段或 API 参数。

以官方厂商指南为基础编写技能。在设计或编写复杂、长时间运行、多工具或编排工作繁重的技能之前，请阅读两份指南。指南中的建议可能会变化。

• Anthropic 提示词编写最佳实践： 涵盖所有当前 Claude 模型。其中的模型特定指南表链接到各个模型的提示词页面。
• OpenAI 最新模型指南： 涵盖当前 GPT 模型系列。其中的提示词建议来自对该系列中一个模型的测试。

将提及模型的建议视为在该模型上测得的结果。只有跨模型指南支持时，才将其应用于其他模型。如果指南针对不同模型给出相反的修正，请直接说明期望的行为。不要针对某个模型的默认行为编写修正，例如“简洁一些”或“写得更详细”。

以下摘要用于提醒你哪些指南适用于当前模型。它们不能替代指南。

• 说明用户指令优先于技能。
• 在已说明的假设下完成已获授权的工作。指出要避免的过早停止，以及应该停止的情形。将只有文本的轮次视为报告，而非完成工作。
• 行动前先探索相关来源。
• 指定写作风格、进度更新和委派偏好。不要依赖模型的默认行为。
• 指明应避免的具体模式，而不是给出泛泛的风格建议。
• 验证工作量应与改动相称。
• 调整投入程度，而不是提示进行更多思考。绝不要在回复文本中要求推理过程。

STE 编写与审查

在编写或修改技能正文之前，请完整阅读 references/asd-ste100.md。将其中基于 STE 的规范应用于描述、指令、参考资料、示例和面向 Agent 的元数据描述。在报告完成之前，完成其中的含义和风格审查。保留义务强度和受保护的技术内容。该规范不代表官方 ASD 词典合规性。

输入

• skill-name（可选）：采用 kebab-case 格式的名称，例如 my-skill。如果未提供，请为技能用途推导一个最短且明确的 kebab-case 领域名称。不要将仓库或应用名称重复作为上下文，例如使用 price-estimator，而不是 budget-price-estimator。如果你推导了名称，请在完成报告中说明。只有在提供的名称无效或与现有技能冲突时才停止。请参阅步骤 2 中的冲突检查。

拒绝 --global、明确的目标路径及其他范围覆盖选项。调用时的工作目录是唯一受支持的范围。

工作流

1. 应用仓库目录防护规则

在解析项目本地路径之前，请先阅读适用于调用工作目录的仓库说明。如果其中定义了技能源目录和生命周期，请停止此工作流，并遵循仓库规定的工作流。不要在此类仓库中创建 .agents/skills/ 或 .claude/skills/ 路径。

2. 解析并验证本地作用域

将 <scope> 设为调用该技能时的工作目录。在 <scope>/.agents/skills/<name>/ 下创建源文件。在 <scope>/.claude/skills/<name> 创建 Claude Code 符号链接。从嵌套项目或工作区调用时，不要将作用域重定向到仓库根目录。切勿在 ~/.agents、~/.claude、~/.codex 或其他全局安装目录下创建或修改技能。

符号链接目标始终为相对路径 ../../.agents/skills/<name>。

写入前，如果源目录或符号链接路径中任意一个已存在，请停止。

3. 阅读当前格式规范来源

相对于此技能目录解析 scripts/fetch-agentskills-spec.sh。运行一次 scripts/fetch-agentskills-spec.sh [--refresh]。完整阅读返回的文件。该辅助脚本会重用 24 小时内通过完整性验证的规范，并有条件地重新验证较旧的条目。如果在线获取失败，它可能会返回七天内验证过的缓存。如果默认用户缓存位置不可用或不可写，请设置 AGENTSKILLS_CACHE_DIR。

对于明确要求最新信息或对变更敏感的工作、存在争议的可移植格式指南，或与验证器行为冲突时，使用 --refresh。使用 stale 结果前先阅读。如果最终报告中使用了该结果，请说明其验证时间戳和获取失败的情况。如果辅助脚本无法返回有效文件，请在写入前停止。切勿直接获取 agentskills.io 规范，也不要在仓库或技能安装目录中创建其缓存。

使用 WebFetch 获取当前的 Claude Code frontmatter 参考。根据这两个来源确认字段形式、命名规则和渐进式披露约定。由于格式会变化，不要凭猜测判断。

4. 定义契约和目录布局

在选择契约或目录布局之前，完整阅读 references/writing-great-skills.md。该文件定义了编写原则、内容路由阈值、辅助程序运行时默认设置以及沟通契约。

定义契约。识别工作流在任何受支持分支上要求、调用或交接工作的每个技能。建议、示例、相关技能引用以及底层工具能力都不是依赖项。只创建所选布局所需的目录。始终需要 SKILL.md 和 agents/openai.yaml。

5. 创建技能

mkdir -p "<scope>/.agents/skills/<name>/agents"
# Add only the subdirectories the layout calls for:
# mkdir -p "<scope>/.agents/skills/<name>/scripts"
# mkdir -p "<scope>/.agents/skills/<name>/references"

编写 <scope>/.agents/skills/<name>/SKILL.md，内容包括：

• 按字母顺序排列的 Frontmatter，并将 description 放在最后。将发现阶段的触发短语放在 description 的开头。

• 如果路由过程中确定了依赖项，则添加 skill-dependencies 数组。同一仓库中的技能使用不带限定符的名称，外部技能使用 ORG/REPO#SKILL。先按目标技能名称（不带限定符的名称或 # 后的子串）排序，再按完整标识符排序。

  字符串必须唯一。解析同一仓库中的所有不带限定符的依赖项。不要将所属技能本身列为不带限定符的依赖项。验证器不会检查外部仓库是否存在。没有依赖项时省略此字段。

• 一个简短的 # Title。

• 用一句话概述技能的功能。

• 仅当技能与 Claude 的默认设置不同时，才添加 disable-model-invocation: true 或 user-invocable: false。省略 disable-model-invocation: false 和 user-invocable: true，因为省略这些字段已表示对应的值。

• 仅当技能声明的默认工作流不会写入仓库文件，或只会写入仓库元数据时，才设置 coordination: exempt。选择此项时，应在新技能正文中添加以下普通文本声明。下面的代码围栏用于记录本编写技能的声明，并非该技能自身的声明：

  This skill is coordination-exempt: skip the ai-coord gate for its declared work.
  

  明确授权的升级操作超出已声明行为时，必须重新进入门禁。

• 添加 ## Arguments（如有）和精简的命令式工作流。仅在顺序很重要时使用固定步骤；否则，说明约定并依据仓库证据执行。

• 明确链接到工作流可能需要的每个 references/ 文件，并用一句话说明何时阅读。

• 为每个随附的辅助工具提供 CLI 签名，包括参数、输出、默认值和运行时命令，确保 Agent 无需阅读源码即可调用。

使用命令式表述。references/、scripts/、examples/ 和 assets/ 的路径均相对于所属技能目录解析。不要添加运行时 Agent 不会使用的仓库风格支持文件或编写材料。包含冒号后跟空格的 YAML 普通标量必须加引号，否则 Frontmatter 解析器可能会拒绝。

编写 <scope>/.agents/skills/<name>/agents/openai.yaml，内容如下：

policy:
  allow_implicit_invocation: true

将 allow_implicit_invocation 设置为 SKILL.md 中 disable-model-invocation 的反值。之后若添加 Codex UI 元数据或 MCP/工具依赖项，应合并到同一个文件中。保留该策略。

6. 创建 Claude Code 符号链接

始终创建相对符号链接，让 Claude Code 能从自身的发现路径找到该技能：

mkdir -p "<scope>/.claude/skills"
ln -s "../../.agents/skills/<name>" "<scope>/.claude/skills/<name>"

7. 验证并报告

• 补丁工具会以 0644 模式创建文件。在首次运行验证前，对 scripts/ 和 tests/ 下的所有可执行文件执行 chmod 755。如果脚手架生成的测试首次运行时因 Permission denied (os error 13) 失败，说明存在此模式问题。
• test -f "<scope>/.agents/skills/<name>/SKILL.md"
• test -f "<scope>/.agents/skills/<name>/agents/openai.yaml"
• readlink "<scope>/.claude/skills/<name>" 的结果为 ../../.agents/skills/<name>，且该链接能解析到源目录。
• 对 scripts/* 和 tests/* 中的所有可执行文件执行 test -x，这样遗漏的 chmod 会立即报错，而不是之后才以权限错误的形式出现。
• ai-skillet doctor --root "<scope>/.agents/skills/<name>" 以状态码 0 退出。这是本地规范和策略检查的权威关卡。
• 对每个撰写或更改的文本目标，按照 references/asd-ste100.md 完成含义和风格审查。将现有文本与其来源进行比较，将新文本与权威契约进行比较。明确审查受保护内容和精确性例外。
• 最后给出 ### 🧩 Skill created: <name>、已创建路径的目录树，以及包含准确检查项的 ### ✅ Verified。文件链接必须使用 .agents/skills/<name>/ 下的绝对源路径，绝不可通过 .claude/skills/<name> 符号链接。
• 仅在请求或长期有效的指示授权时提交。否则，询问是否需要提交。对于已获得的授权，不要再次询问。

除非新技能的输出契约另有要求，否则辅助工具的标准输出、命令、路径、frontmatter 和生成的技能内容均不得添加装饰。