agent-skill-management

Agent 技能管理

使用此功能管理双层项目中的 Agent 技能，验证其发现和主动加载情况，或建立由执行者本地负责的获取、保留和恢复机制。管理操作包括添加、编辑、重命名、移动和移除技能。可分发技能——其他项目可安装的可移植能力——在源目录中编写（通常为 skills/，即事实来源），并使用 vercel-labs/skills CLI（npx skills）安装到技能根目录（即 Agent 实际加载技能的目录——Claude Code 使用 .claude/skills/，Codex 和其他几个工具使用 .agents/skills/）；skills-lock.json 文件会记录已安装的内容。仓库本地技能——用于记录单个项目自身流程、并且必须在编辑某个界面时触发，而不是项目自身的说明可按需引导至的文档——直接提交到技能根目录下，CLI 永远不会修改它们。

发现机制决定了如何路由到任一层级中的技能：每项技能都会通过自身的 description 声明其适用条件，因此不需要书面索引。有些宿主会维护索引（例如 AGENTS.md 表格），这就意味着还要维护第二份记录，确保其保持最新。

此技能是独立自包含的：它没有指定任何仓库专属文件或布局，也不引用任何仓库根目录索引，因此可以单独安装使用。以下目录名称均为惯用默认值——源目录为 skills/，Claude Code 的技能根目录为 .claude/skills/，Codex 的技能根目录为 .agents/skills/。如果宿主项目采用了不同路径，请替换为项目所选路径；请注意，面向这两种宿主的项目有两个根目录，其中一个可能是指向另一个的符号链接。

指南：

• 若宿主项目维护书面技能索引，则每当任一层级中的技能被添加、重命名、移动或移除时，MUST 根据项目的技能编写规范同步更新索引；若项目不维护索引，则每项技能 frontmatter 中的 description 就是完整的发现机制，无需提供索引。

本文档中的关键词“MUST”“MUST NOT”“REQUIRED”“SHALL”“SHALL NOT”“SHOULD”“SHOULD NOT”“RECOMMENDED”“MAY”和“OPTIONAL”，应按照 RFC 2119 中的说明进行解释。

这些材料适合做成技能吗？

在询问某项技能属于哪个层级之前，先问问这些材料是否应该成为技能。与文档相比，技能唯一的功能优势在于可发现性——编辑匹配的内容时，它会在无人询问的情况下触发，不需要任何人记得去查阅它——而这也正是它持续产生的全部成本：每项技能的 description 都会占用每个会话技能列表的空间，无论当前任务是否需要它。对于永远不必主动触发的材料来说，这笔成本毫无意义，因为始终加载的指令文件可以在需要时按需引导用户查看这些材料。

一个事件可能暴露出几类不同的指导内容。项目要求 Agent 指派谁、可复用的验证指派流程，以及主机配置的权限，各自有不同的归属者。在选择存放位置之前，请先拆分这些内容；不必把整段内容放在一起。

这些材料是……	将其归入
产品是什么、意味着什么、做什么，以及受到哪些限制	项目自身持续维护的产品文档
仅针对 Agent 的项目特定义务	项目的 Agent 指令，例如 AGENTS.md
人类贡献者和 Agent 如何规划、编写、构建、操作和运行项目	项目的贡献者文档
实际的个人、主机或环境偏好，或已配置的值	所有者支持的配置入口及工作流
在处理匹配的任务或内容时需要被发现的能力	该能力现有的技能归属者；若有理由创建新技能，则参阅下方的选择层级

配置这一行指的是设置本身，而不是使用该设置的可复用流程。针对特定主机的操作手册可以说明该工作流，但把可移植规则复制到每个人的设置中，只会让它有多个归属者，并不会让它变得依赖特定环境。项目明确规定的放置策略和当前主机的指令层级仍然适用。

下面的可移植性问题无法替你做出这个判断。关于仓库布局的_文档_与关于仓库布局的_技能_同样不可移植，因此对于两者，可移植性问题的答案都是“否”——如果先问这个问题，读者就会得出结论：这些材料必须做成仓库本地技能，却从未先问过它们是否应该成为技能。

指南：

• 对于新材料，以及即将添加到现有技能中的变更内容，MUST 在选择层级之前回答这个问题。
• MUST 按项目范围、目标执行者和实际环境依赖性拆分混合指导，然后为每条内容指定归属者。
• MUST 将可复用流程保留在适用能力的归属者处，不要复制到项目指令或个人设置中；实际设置应遵循受支持的配置工作流。
• MUST NOT 为始终加载的指令文件已经能够按需引导的材料编写技能；在该文件中添加一行即可完成引导，且不会占用其他会话技能列表的空间。
• 当此问题重新判定现有技能的归属时，MUST 停用该技能——根据适用的变更门槛，将其内容移至归属对应的指令、文档或受支持的配置中，并删除该技能，而不是让两者并存。

选择层级

每个技能都属于且仅属于一个层级，由一个问题决定：将此技能安装到另一个项目中后，它能否原样使用？

• 自包含且可移植的技能——不涉及特定仓库的文件、工作流或布局——属于可分发技能：在源目录（skills/<name>/）下编写，并通过 CLI 安装。
• 将某个项目自身的流程编码为一种能力的技能——项目定制的技能编写规则、项目自身的变更循环、针对项目自身差异编写的审核策略——属于仓库本地技能：直接提交到技能根目录下（.claude/skills/<name>/，或在读取该路径的宿主环境中提交到 .agents/skills/<name>/）。

指南：

• 一旦素材是否属于技能？确定它确实是技能，就必须在编写其 SKILL.md 之前，使用上述可移植性问题将每个新技能归入且仅归入一个层级。
• 绝不能将仓库本地技能存放在源目录下，也不能使用 npx skills 管理；它不会出现在 skills-lock.json 中。
• 当技能的适用范围发生变化时，必须有意将其移到另一个层级——后来泛化为可共享技能的仓库本地技能，应将源移至 skills/<name>/，并通过 CLI 重新安装——绝不能在两个位置都保留副本。
• 可以根据 skills-lock.json 判断技能的层级：列在其中的技能是可分发且已安装的；不在其中的技能是仓库本地的。

仓库本地技能

技能根目录下提交的仓库本地技能副本就是其事实来源。禁止手动编辑已安装副本的规定不适用于此处——直接编辑这些文件才是正确的工作流。

指南：

• 必须直接在技能根目录下编辑仓库本地技能（.claude/skills/<name>/，或宿主环境读取的对应路径）——包括其 SKILL.md、references/ 和任何 scripts/——并提交这些文件；它没有单独的源目录，也不需要安装步骤。
• 必须按照项目的技能编写规范，以与其他任何技能相同的标准编写，包括前置元数据、命名、发现元数据和渐进式披露。
• 必须使用 git mv 重命名仓库本地技能的目录，同时更新匹配的前置元数据 name，并在同一次变更中更新所有引用旧名称的内容。

可分发技能：安装与刷新

可分发技能的源文件位于 skills/<name>/SKILL.md（其 references/ 目录与之并列），并通过 CLI 安装。CLI 通过 npx 运行；当环境不支持符号链接时，安装时使用 --copy（副本会作为真实目录放在技能根目录下）。

命令：

• 安装或刷新所有受管理的技能：

  npx skills add ./skills --agent claude-code --skill '*' --yes --copy
  

• 按名称刷新单个技能：

  npx skills add ./skills --agent claude-code --skill <name> --yes --copy
  

• 刷新多个指定名称的技能——每个技能使用一个 --skill 标记：

  npx skills add ./skills --agent claude-code --skill <name> --skill <other-name> --yes --copy
  

• 列出已安装的技能：npx skills list

• 移除已安装的技能：npx skills remove <name>（然后删除其 skills/<name>/ 源目录，并更新宿主保留的技能索引，如有）。

指南：

• 必须在源目录（skills/<name>/）下编写可分发技能，绝不要直接写入技能根目录。
• 如果你拥有已安装副本对应的源文件，切勿手动编辑技能根目录下的已安装副本；应编辑源文件并重新安装。
• 编辑任何技能源文件后，必须重新运行安装，以确保已提交的安装副本和 skills-lock.json 与源文件一致。
• 必须将每个已安装的技能根目录——.claude/skills/<name>/、.agents/skills/<name>/ 或两者——以及 skills-lock.json 与 skills/ 源目录一同提交；它们是受 Git 跟踪的文件，不会被 gitignore 忽略。
• 当不支持符号链接时，必须传入 --copy；符号链接安装会导致此类环境中的技能根目录为空或链接失效。
• 大范围更改后，必须使用 --skill '*' 刷新所有受管理的技能；定向刷新时使用 --skill <name>。每个 --skill 标记只能指定一个技能，因此安装多个技能时必须重复使用该标记（--skill <name> --skill <other-name>），不能传入列表。
• 必须将 No matching skills found 响应——CLI 在本应显示安装摘要的位置返回源目录中可用技能列表——视为一次未安装任何内容的运行：没有技能进入技能根目录，也不会写入锁定文件。常见原因是使用逗号分隔的 --skill a,b,c，因为 CLI 不会拆分该值，因此一个技能也匹配不到；而返回的可用技能列表看起来像普通帮助信息，不像失败提示。
• 建议从仓库根目录运行 npx skills add，这样 ./skills 才能正确解析，并且 skills-lock.json 会写入该目录。
• 提交前，建议确认安装摘要将所有预期技能都列为 copied；这项检查可以发现运行时未匹配到任何内容、因此未安装任何内容的情况。
• 如果 npx skills 因 could not determine executable to run 而中止，建议使用明确的版本说明符重试（npx --yes skills@latest …）；上面的普通形式仍为规范用法，而版本说明符是在 npx 无法解析裸包名时使用的备用方案。

发现与主动加载

请参阅 active-loading.md，了解：

• 如何通过分别观察安装、源文件一致性、发现情况和已加载内容，验证安装或刷新
• 如何诊断未发现技能或加载了意外内容的问题，包括同名优先级、过期会话和源文件证据不可用
• 在获准更改安装前进行诊断

参与者本地获取与恢复

请参阅 actor-local-acquisition.md，了解：

• 如何在每个受控内部参与者的当前上下文中，确保具备适用内容及其引用文件的完整正文
• 如何应用对任务敏感的开发或内部审查选择，并明确输出评估的归属
• 如何区分原生加载、直接获取和保留文本，并标明覆盖情况为完整、部分、未知、不匹配或不可用
• 如何关联预期材料与观察到的材料，而不根据父级或复用的任务分配标识推断材料已获取
• 如何基于一个已验证版本恢复截断或丢失的保留内容，而不重复读取已完整保留的文本
• 如何区分内容获取、输出验证和验证证据评估，且不添加外部审查证明

引用可选防护声明

评估某项可选防护是否会在不干扰获取的情况下进行观察，或阻止依赖项变更时，请在有相应实践的情况下，参考获取防护资格认定实践。若没有该所有者，则报告资格评估未执行；仅有获取覆盖范围，不能为防护或其审计回退方案认定资格。明确获取的含义本身并不要求进行防护资格认定，也不要求针对同一问题重新加载资格认定调用方。

提议更改已安装的技能

请参阅 installed-rule-changes.md，了解如何：

• 根据技能层级，将错误、过时或缺失的已加载规则路由到其实际来源
• 区分增补的本地约定、获批的有限偏离和未采纳的上游提案
• 检查人工采纳情况、宿主优先级、范围和重新评估要求，而无需专门的登记表
• 在适用的变更关卡下修正自有来源，或发布经授权的第三方请求

锁文件

skills-lock.json 是安装锁文件，类似于 package-lock.json。它记录每个可分发技能的 source、sourceType，以及已安装内容的 computedHash，并会提交到版本库，以确保已安装状态可复现并能检测到偏差。仓库本地技能不会出现在其中。

从 [email protected] 起，CLI 会将 local source 写为相对于锁文件自身目录的路径，并使用 / 分隔，以便在不同检出目录和平台间保持可移植；只有在不存在相对路径时才会回退为绝对路径，例如来源位于不同的文件系统根目录时。刷新任何单个技能时，CLI 都会按照相同的规范化方式重写所有 local 条目的 source，而不仅仅是被刷新的条目。因此，如果锁文件差异涉及你未编辑的技能条目，这是一次规范化扫描，而非偏差。低于 1.5.22 的 CLI 仍会写入绝对路径，因此检出目录中的锁文件可能采用任一种形式，具体取决于上次运行安装命令时使用的版本。

已根据 v1.5.22 release notes 核实，该版本于 2026-08-05 发布。

指南：

• MUST 提交 skills-lock.json，并通过运行安装命令重新生成，绝不能手动编辑。
• MUST 将没有对应来源编辑的 computedHash 变更视为需要调查的安装偏差，而不是盲目提交。
• SHOULD 将仅涉及 local source 字段、且没有 computedHash 变更的差异视为上述规范化扫描，而非偏差；如果锁文件在两种形式之间反复切换，请确认上次运行安装命令时使用的 CLI 版本。

已安装副本漂移检查

已安装的副本是受版本控制的文件，而不是构建产物，因此手动编辑不会受到任何阻止——下次安装时，这些修改会被静默丢弃。此技能包含 scripts/check-installed-copies.mjs，这是一个依赖精简的 Node 检查脚本（仅使用标准库），会逐个文件、逐字节比较每个源技能与其已安装副本，确保忘记重新安装或手动编辑的问题能在合并前被发现，而不是之后才暴露出来。

示例：

# Substitute the skill root the host reads (.claude/skills, .agents/skills, …).
node skills/agent-skill-management/scripts/check-installed-copies.mjs skills .claude/skills

两个根目录都必须指定，且没有默认值：目录布局由项目自行决定，而猜测的根目录若未匹配到任何内容，就不会报告漂移——这种通过结果无法与真正的通过区分开来。它会报告四种差异（已安装副本中缺少文件、仅已安装副本中存在的文件、内容不同，以及完全没有已安装副本的源技能），此外还会报告既没有源文件、也没有仓库本地状态的已安装技能。使用可重复的 --local <name> 标记每个仓库本地技能，否则检查会将其视为漂移。它会有意忽略 skills-lock.json：锁文件只会在安装时写入，因此记录的是上次安装的结果，而不是当前磁盘上的内容；它无法证明已安装副本之后是否被编辑——而这正是此检查要发现的漂移。它的 source 字段指明技能的来源，而非其已安装副本的位置，因此无法标识此检查所比较的两个根目录。目录内容才是事实依据。

所有已安装副本均匹配时，退出码为 0；存在漂移时为 1；调用有误或根目录不是目录时为 2。

指南：

• MUST 在对可分发技能进行任何更改后运行此检查，并将退出码 1 视为忘记重新安装或副本被手动编辑，而不是编辑已安装目录的理由。
• MUST 在每个调用位置显式指定两个根目录，包括项目自身的门禁，因为检查无法推断未告知它的目录布局。
• MUST 使用 --local（或项目自身副本中的集合）注册每个仓库本地技能，而不是让没有源文件的已安装技能通过；否则，已删除的源技能就无法与有意保留的技能区分开来。
• SHOULD 将此检查接入项目的合并门禁：它离线且确定性强，正符合门禁的需求。

验证

技能更改属于文档更改：必须通过格式、lint 和相对链接完整性检查；如果项目提供了技能结构验证器，也必须通过该验证。

指南：

• MUST 在任何技能更改后（无论是直接编辑还是重新安装）运行项目的文档检查（格式、lint、相对链接完整性），并在提交前修复所有失败项。
• MUST 在技能文件或链接移动时运行相对链接检查，因为已安装副本中的失效链接与源文件中的失效链接会导致同样的检查失败。
• MUST 在添加、重命名、移动或移除技能或参考文件后，确认发现元数据和父级路由仍能解析到相应更改——这些规则由技能编写规范负责定义——因为层级移动会改变发现和路由所依赖的路径。
• SHOULD 使用技能编写规范提供的结构验证器验证已更改的技能（如果有）。
• SHOULD 将重新安装后的副本与其源文件进行差异比较（git diff --stat），以确认重新安装只更改了预期文件。