Agent Skill 工作流

Agent Skill 怎么写，取决于准备封装的流程是否会在不同任务中重复、是否需要根据现场信息作判断，以及执行后能否观察到项目结果。始终成立的仓库事实属于项目规则，只发生一次的需求属于当前 Prompt，无论模型怎样判断都必须执行的事件动作属于 Hook；外部服务和数据连接则由 MCP 或其他工具提供。

一个全栈项目若经常变更已有 API 契约，每次都要找到实际生产者、确认批准后的字段含义、同步直接消费者，再运行项目已有检查并观察界面或调用结果。具体字段和影响范围每次都变，但判断顺序保持稳定。这段流程适合成为项目级 Skill；某次新增的字段名、接口路径和验收结果仍由当次 Prompt 提供。

先判断这段内容是不是 Skill

“经常复制一大段 Prompt”只能说明存在重复，不能单独证明需要 Skill。复制内容若只是“使用 pnpm 安装依赖”或“生成物不能手改”，它们是长期项目事实，应该由 AGENTS.md 或 CLAUDE.md 项目规则保存。复制内容若只是一次需求的状态、截图和范围，它们在任务结束后就失效，应该留在当前任务 Prompt 里。

API 契约变更不能机械地把某个字段搜索替换掉：生产者可能是服务端类型、Schema 或生成源，消费者可能包括前端适配器、管理端、SDK 和异步事件。确定事实源、沿调用关系找到受影响消费者的方法可以跨任务复用，即使每次输入和改动范围都不同。

API 契约同步 Skill 的输入是已经批准的契约变化、当前项目和期望的软件状态；执行完成时，生产者与直接消费者使用相同的字段定义，并由项目已有测试或当前页面证明。字段含义没有得到确认时，Skill 应指出缺失决定并停止，而不是替用户发明定义。

Skill 只拥有可复用方法

把同一项目的下一项契约变更代入这段文字：“先读当前目录适用的项目规则”仍然正确；“把 status 改成三个枚举值”已经失效。前者进入 Skill，后者留在任务 Prompt。

项目规则和 Skill 都可能写指令，但加载时机不同。项目规则描述进入该目录后始终适用的事实和约束；Skill 描述某类任务出现后才需要的方法或参考。Claude Code 的扩展机制说明（在新标签页打开）也把 CLAUDE.md 用于始终要知道的项目约定，把 Skill 用于偶尔需要的参考资料或可复用工作流。把长操作流程塞进规则，会让无关任务也携带它；把项目命令复制进 Skill，则会在命令更新后形成第二份旧事实。

Hook 与 Skill 的区别在于动作是否需要模型判断。变更契约前要不要修改数据库、是否存在生成源、哪些客户端是直接消费者，都需要读取代码后决定，属于 Skill。文件写入后必须运行格式化器、危险命令必须阻断、任务停止时必须发送通知，这些动作由确定事件触发，更适合 Hook 或已有工程工具。

MCP 解决的是“能不能连接”，Skill 解决的是“连接后按什么方法完成任务”。一个 Skill 可以要求查询工单或读取设计稿，但不应假设工具一定存在，也不能绕过工具权限。缺少必要连接时，它应返回所缺能力和未完成结果。

全局 Skill 和项目 Skill 分别放在哪里

只依赖通用输入、在多个仓库里都成立的方法适合个人级 Skill，例如把一份公开技术文档整理成带来源的摘要。需要当前项目架构、命令、生成链或团队责任边界的流程属于项目级 Skill。API 契约同步依赖项目内的生产者、消费者和验证入口，因此应随项目维护，而不是依赖某台电脑的个人配置。

Claude Code 当前从个人目录 ~/.claude/skills/<name>/SKILL.md 和项目目录 .claude/skills/<name>/SKILL.md 发现 Skills；项目 Skill 可以随版本控制共享。Codex 当前从用户目录 ~/.agents/skills 以及由工作目录向仓库根目录逐级出现的 .agents/skills 发现 Skills。两端都支持个人与项目范围，但一个客户端的目录和覆盖行为不能直接套到另一个，接入时以 Claude Code Skills 文档（在新标签页打开）和 OpenAI Build skills 文档（在新标签页打开）的当前说明为准。

Agent Skills 的基础格式可以跨客户端复用，客户端发现路径却不是开放规范的一部分。只使用一个客户端时，直接放进该客户端的项目目录即可；需要两端使用时，应把同一份 Skill 内容接入两个发现位置并分别测试，不能手工维护两份逐渐分叉的正文。两端怎样指向同一份文件，应沿用项目现有的配置管理方式；这不是创建 Skill 前必须解决的问题。

现有项目使用 Codex 时，文件落在 .agents/skills/api-contract-sync/SKILL.md；使用 Claude Code 时，落在 .claude/skills/api-contract-sync/SKILL.md。先为实际使用的客户端建立一个入口并完成触发验证，再接入第二个客户端。两端同时存在时，修改正文后必须确认两个入口仍指向同一内容；如果项目没有可靠的共享方式，宁可先维护一个入口，也不要复制后靠人工记忆同步。

项目级 Skill 不应硬编码作者电脑上的绝对路径。Skill 只要求 Agent 从当前工作目录和适用的项目规则取得仓库事实，引用附属资源时使用 Skill 目录内的相对路径。换一台电脑或换一个 worktree 后，它仍能读到当前仓库的规则和路径。

Agent 先看到描述，再决定是否加载正文

Skill 通过渐进加载减少无关上下文。Codex 初始只向模型提供可用 Skill 的名称、描述和文件路径，选中后才读取完整 SKILL.md；Claude Code 也利用描述判断何时加载 Skill，正文只在使用时进入上下文。这意味着 description 不是文件简介，而是触发边界。Agent Skills 规范（在新标签页打开）要求 name 和 description，并把完整指令与附属资源留到后续加载阶段。

“处理 API”过于宽泛：查询接口文档、修复内部实现和修改公开契约都可能误触发。“只在变更用户接口时使用”又没有说明流程负责什么，相关任务可能匹配不到。API 契约同步 Skill 可以写成：

---
name: api-contract-sync
description: >-
  Trace and update an existing API contract and its direct consumers.
  Use when an approved contract change affects a producer plus frontend,
  admin, SDK, or event consumers. Do not use for local implementation
  changes that leave the contract unchanged.
---

处理对象是“已有 API 契约及直接消费者”，触发条件是“批准后的契约变化跨过生产者与消费者”，排除条件是“不改变契约的局部实现”。这三个信息让相关任务能够匹配，也避免局部实现任务误触发。名称只负责稳定标识；自然触发主要依赖描述能否区分边界。

描述发生变化时，显式调用通常仍能找到 Skill，自然触发却可能改变。流程适用范围、客户端发现机制或项目责任边界更新后，都要重新运行相关和无关请求，而不是只确认文件仍然存在。

自动触发不等于工具授权

description 只帮助 Agent 选择 Skill，不会授予文件、终端或外部服务权限。API 契约同步可以在相关修改请求中自然触发，因为用户已经要求改变本地项目，Skill 仍受当前权限与停止条件限制。部署生产环境、删除数据、发送外部消息或发起付款具有额外副作用，这类 Skill 应要求用户明确点名，不能仅凭描述相似自动运行。

Claude Code Skills 文档（在新标签页打开）允许在 SKILL.md Front Matter 中设置 disable-model-invocation: true，让 Skill 只能由用户调用。OpenAI Build skills 文档（在新标签页打开）把 policy.allow_implicit_invocation: false 放在 Skill 的 agents/openai.yaml 中，保留显式 $skill 调用并关闭隐式选择。这些字段属于各自客户端的调用策略，不是 Agent Skills 基础格式中的共同保证；同一流程接入两端时，要分别配置并验证。

# Claude Code: SKILL.md
disable-model-invocation: true

# Codex: agents/openai.yaml
policy:
  allow_implicit_invocation: false

关闭隐式调用也不会扩大权限。Skill 被用户点名后，文件写入、命令执行、网络访问和外部副作用仍由客户端权限策略与当前授权决定。需要更高权限时，应停在授权边界，不能让 Skill 的文字绕过确认。

Agent Skill 怎么写：从重复流程得到最小实现

最小 Skill 只需要一个目录和 SKILL.md。基础 Front Matter 保留开放规范中的 name 与 description，正文写清输入、不可交换的判断顺序、停止条件和完成结果。Claude Code、Codex 各自支持的扩展字段只有在确实需要对应行为时再加入，不能把某端字段当成跨客户端保证。

api-contract-sync/
└── SKILL.md

---
name: api-contract-sync
description: >-
  Trace and update an existing API contract and its direct consumers.
  Use when an approved contract change crosses a producer-consumer boundary.
  Do not use for implementation-only changes that preserve the contract.
---

# API contract sync

## Required inputs

Require the approved contract change and an observable end state.
Read the project rules that apply to the current working directory.

## Workflow

1. Find the source of truth that produces the existing contract.
2. Trace the contract to its direct consumers before editing.
3. Change the owning source and only the affected consumers.
4. Run the project's existing deterministic checks.
5. Observe the affected consumer and the behavior that must remain unchanged.

## Stop conditions

Stop and name the missing input when the intended field meanings are not approved,
the source of truth cannot be identified, or the required consumer is unavailable.
Do not invent paths, commands, field meanings, or approval.

## Completion

Report the changed contract, affected consumers, project checks, observed result,
and any boundary that could not be verified.

这份 Skill 没有保存项目目录、测试命令或某个字段；这些事实继续由当前仓库的规则与代码维护。Skill 要求读取适用规则，再从代码识别事实源和消费者。项目换语言或重组目录时，只要规则与代码同步，Skill 不需要因为目录变化再改一遍路径。

把原来反复粘贴的任务文字按有效期拆开，迁移后不再保留一份“大 Prompt”：

迁移完成后，用下一次不同的契约变更检查边界。新的 Prompt 应只替换已批准的字段定义、影响范围和目标状态；如果还要复制判断顺序，Skill 漏了稳定流程；如果必须修改 Skill 中的路径或命令，项目事实放错了位置。

步骤顺序不能交换。先写消费者再找事实源，容易把兼容代码加在错误位置；没有先追踪消费者就修改契约，可能让服务端检查通过而界面或 SDK 继续读取旧结构；只运行测试却不观察消费者，无法证明消费者已经使用新契约。

停止条件同样属于实现。字段含义没有得到确认时，Skill 只指出缺失决定；事实源无法确认时，Skill 不修改代码，并说明调查停在哪里。继续猜测会把不确定输入固化为公共契约，后续测试即使通过也只证明猜测被一致实现。

资源在减少重复读取或操作时再拆分

SKILL.md 过长时，不按文件类型机械拆目录。入口文件必须保留触发边界、核心流程、资源用途和停止条件；只有某份内容在执行时并非总要读取，或某个动作每次执行都必须得到相同结果，才拆成附属资源。

项目已有测试、代码生成器或格式化命令时，Skill 直接按项目规则调用，不再套一层同名脚本。只有现有工具无法表达一个稳定动作，而且该动作会在多次执行中重复，才值得加入脚本。脚本还要自行处理输入、依赖和失败码；模型负责决定何时运行，脚本负责给出确定结果。

参考文件必须从 SKILL.md 明确链接，并说明在哪个分支读取。跨客户端共享时使用相对路径，避免某台电脑的绝对目录。主文件只保留每次都要读取的流程，脚本、参考和资源在需要时再打开；如果每次调用都会立即读取所有附属文件，拆分只增加跳转，没有减少上下文。

项目命令变化就改 Rules，判断顺序变化就改 Skill，某次字段变化只改 Prompt，固定事件动作变化则改 Hook。相同事实同时存在于多个位置，任何一次更新都可能留下冲突版本。

Skill 与项目规则和任务 Prompt 怎样接上

一次契约变更需要三类输入。项目规则提供仓库结构、项目命令、生成物边界和架构约束；Skill 提供查找事实源、追踪消费者、处理缺参和验证结果的方法；任务 Prompt 只提供这次批准的变化、已知现状、影响范围和目标状态。

显式调用的任务只需补入本次变量：

使用 api-contract-sync。产品已经批准把现有账户状态契约从两个状态扩展为三个；服务端当前返回两个状态，管理端和用户端都会显示账户状态，它们是否直接消费同一契约需要从代码确认。保持权限拒绝行为不变，完成后用项目已有检查和两个界面的实际显示证明结果。

api-contract-sync 提供稳定流程；三个状态、候选消费者和对照行为都是本次变量。若代码表明用户端通过另一个适配层取得状态，Skill 应沿实际调用链调整改动范围，同时保留 Prompt 要求的用户端结果验证，不能为了照抄候选范围而制造不存在的依赖。

自然触发时不写 Skill 名称：

已批准修改现有账户状态 API，并同步受影响的管理端和用户端显示。先从项目规则和当前代码确认事实源与直接消费者，保持权限拒绝行为不变，再用两个界面的结果完成验证。

请求中的“批准的契约变化”“生产者与直接消费者”“项目规则”和“消费者结果”足以让 description 区分这是一项契约同步任务。若还要读取外部工单，MCP 只负责取得工单内容；工单是否代表已批准需求、怎样映射到代码，仍由 Prompt、规则和 Skill 共同约束。

先确认 Skill 在相关任务中会被加载

显式调用先排除发现路径和名称问题。在一个新的客户端会话中进入目标项目，通过 Claude Code 的 /<skill-name> 或 Codex 的 $skill-name 选择当前 Skill，再提交一条包含完整输入的代表任务。调用入口以客户端当前界面和官方文档为准，不把一种语法套到另一端。

显式调用后，Agent 应先读取适用项目规则和事实源，再追踪直接消费者；修改范围由调用关系决定，最后运行项目已有检查并观察消费者。回复里只出现 Skill 名称不代表流程已经执行。显式调用仍跳过这些步骤时，问题在 Skill 正文或客户端扩展配置，不在 description。

自然触发要在另一个新会话里使用同一项目和同一任务，只删除 Skill 名称。新会话避免上一次已经加载的正文继续留在上下文。若客户端暴露 Skill 调用记录，可以直接核对；没有调用记录时，检查 Agent 是否真的执行了这项 Skill 独有的步骤，一次相似回答不足以证明它能稳定触发。

显式调用成功而自然触发失败，优先收紧或补全 description 中的对象与触发条件。不要把整套流程塞进 description，也不要加入所有可能的近义词；描述只需让相关任务与相邻任务可区分，具体步骤由正文承担。

无关或缺参任务不能误执行

正向请求只能证明 Skill 可能被选中，不能证明边界正确。相邻但不改变契约的任务最容易暴露描述过宽，例如“优化接口内部缓存，不改变请求和响应结构”。api-contract-sync 不应介入；如果它仍被加载，描述中的“API”覆盖了排除条件，需要改成“已批准且跨生产者—消费者边界的契约变化”。

缺参测试要省略一项足以阻断修改的输入：

把账户状态 API 改成新结构，并同步所有页面。

这条请求没有确认新字段的含义，也没有可观察目标。Skill 应先从项目规则和现有代码确认当前契约，再指出缺少哪项业务决定；它可以完成只读调查，但不能自行挑选新枚举、重命名公共字段或修改消费者。说明具体缺口后，由用户补充已批准的字段定义，再继续修改。

相关任务没有触发、无关任务频繁触发和缺参后继续修改，是三种不同故障。前两种修改 description 和发现位置；第三种修改 Skill 的输入与停止条件。把描述写得越来越长无法修复正文缺少安全边界，反而会让 Agent 更难判断何时该触发。

Skill 执行完，还要检查直接消费者

Skill 被发现后，Agent 只是取得了流程；即使步骤按顺序执行，API 契约是否可用仍要看生产者、直接消费者和必须保持的对照行为。先运行项目已有的单元测试、类型检查、契约测试或构建，再打开受影响页面、调用公开接口或观察事件消费者，确认批准后的状态出现且旧权限行为没有变化。

再换一类契约变更时，如果仍需改写 Skill 里的固定文件、字段或命令，说明这些项目事实被错误写进了流程；如果只需更换 Prompt 中的当前变量，这段流程才具备复用价值。

保存文件后统一格式化、工具调用前阻断危险命令、Agent 停止时发送通知，都不应依靠 Skill 的文字提醒。把这些固定动作交给下一篇 Hook 配置，Skill 继续负责需要读取现场、选择责任边界和判断结果的部分。