skill-maker

技能编写

为 Claude Code、Codex 和 OpenCode 编写、检查和发布技能。通过 skills 包管理器分发的技能将源代码存放在单独的 git 仓库中；仓库自有的本地技能则可以直接放在使用它们的仓库中。

包管理器策略：始终使用 skills@latest。 本技能及其 README 示例中的交互式工作站命令和 SessionStart 钩子均使用 npx -y skills@latest。这样做是为了自动获取包管理器的修复和功能更新，代价是在会话启动时允许新发布的第三方安装程序代码无人值守地执行；技能源代码的 URL 和引用仍由各自独立控制。在 CI、特权自动化或其他要求可审查、可复现可执行代码的环境中，应固定包管理器版本。

编辑前先判断技能类型

技能路径可能是自行编写的源代码，也可能是由包管理器管理的已安装副本。只编辑自行编写的源代码。

类型	位置	是否编辑？
已发布的源代码	技能的源代码仓库（<name>/SKILL.md）	是
仓库本地源代码	跨 Agent 技能位于 <repo>/.agents/skills/<name>/；仅在有意限定为 Claude 时，才放在 <repo>/.claude/skills/<name>/	是
通过 npx 安装的副本	全局或项目目标目录，或规范的 .agents/skills 存储目录及其映射目录	否 — 它是派生副本；npx -y skills@latest add/update 会覆盖它

对于已发布的技能，发布流程采用拉取方式，而不是实时编辑。修改源代码仓库，然后运行 npx -y skills@latest update 重新拉取并改写已安装副本。直接修改已安装副本的内容会在下次更新时丢失。对于仓库本地源代码，应在使用它的仓库中提交实际目录及其兼容性符号链接；这不需要执行包管理器安装步骤。

• 如果你拥有源代码仓库：编辑 <name>/SKILL.md，提交、推送，然后运行 npx -y skills@latest update。
• 如果你不拥有源代码仓库（只是安装了技能）：实际上，已安装副本是只读的。若要修改，请派生源代码仓库并运行 npx -y skills@latest add <your-fork>，或向上游提交 PR/问题。你无法推送到自己不拥有的仓库。

要查找已安装技能的来源，可查看锁文件中的记录：全局安装对应 ~/.agents/.skill-lock.json（如果已设置 $XDG_STATE_HOME/skills/.skill-lock.json，则对应该文件），项目安装对应 <project-root>/skills-lock.json。如果锁文件中包含该名称，即使磁盘上的技能位于 .agents/skills 下，看起来像普通目录，也应将其视为派生副本。

面向 Claude Code、Codex 和 OpenCode 的仓库本地技能

对于仅在单个仓库中编写并使用的技能，请在仓库根目录下的 .agents/skills 中保留规范的实际目录。Codex 会从当前目录向上扫描至仓库根目录中的 .agents/skills，并支持符号链接技能文件夹，而 OpenCode 会扫描相同的项目级和全局路径。Claude Code 会在 .claude/skills 下发现项目技能，因此请通过以下两种受版本控制的目录布局之一提供相同内容。

一个目录符号链接

如果仓库中的所有技能都适用于多个 Agent，且仓库从不使用项目范围的 npx skills add，优先采用这种更简单的形式。确认不存在 skills-lock.json：

<repo>/
├── .agents/skills/
│   └── <name>/
│       ├── SKILL.md
│       └── scripts/                  # optional
└── .claude/skills -> ../.agents/skills

如果所有现有技能都位于真实的 .claude/skills 目录中，且 .agents/skills 尚不存在，请在移动整个目录树时保留其历史记录：

mkdir -p .agents
git mv .claude/skills .agents/skills
ln -s ../.agents/skills .claude/skills

如果 .agents/skills 中已包含技能，请按名称使用 git mv 移动其余技能目录，然后将空的 .claude/skills 目录替换为相对符号链接。

这种形式有两个代价。第一，所有技能都会对 Codex 和 OpenCode 可见，因此无法将仅供 Claude 使用的技能对 Claude 之外的环境保密。第二，请勿将这种形式与项目范围的 npx 安装搭配使用：包管理器生成的 .claude/skills/<name> 映射会解析到规范的 .agents/skills/<name> 存储位置之上，而不是作为独立映射存在。如果这两个代价中任意一个不适用，请使用下面的逐技能形式。

逐技能符号链接

如果仓库混合了适用于多个 Agent 的技能和仅供 Claude 使用的技能，或者存在项目范围的 npx 安装，请使用这种形式。将 .claude/skills 本身保留为真实目录，以便适用于多个 Agent 的符号链接、仅供 Claude 使用的技能和由 npx 管理的映射可以共存：

<repo>/
├── .agents/skills/<name>/
│   ├── SKILL.md
│   └── scripts/                  # optional
└── .claude/skills/<name> -> ../../.agents/skills/<name>

对于新的根目录范围、适用于多个 Agent 的技能，请先创建真实目录，再创建 Claude 映射：

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

对于现有的仓库编写的 Claude 技能，请先确认其名称未出现在 skills-lock.json 中，然后在移动它时保留历史记录：

mkdir -p .agents/skills
git mv .claude/skills/<name> .agents/skills/<name>
ln -s ../../.agents/skills/<name> .claude/skills/<name>

跟踪真实目录和符号链接。请勿以这种方式移动由锁定文件管理的依赖项；应更改其上游来源或包选择，然后让 npx 重新生成存储位置和映射。真正仅供 Claude 使用的技能应保留为真实的 .claude/skills/<name> 目录。

无论采用哪种布局，都应使用 <repo>/.agents/skills，而不是 ~/.agents/skills：波浪号路径是用户全局路径，会使仓库契约依赖于特定机器。共享路径让同一份内容可被发现，但不会转换特定宿主环境的行为。声明某个技能适用于多个 Agent 之前，请检查其 frontmatter、工具名称、斜杠命令、生命周期假设，以及字面形式的 .claude/skills/... 路径。保持 name、description 和正文具有可移植性；仅在宿主环境需要时保留特定于该环境的元数据，绝不可将其他宿主环境会忽略某个字段作为安全边界。应通过运行时提供的技能基础目录引用辅助文件，而不要硬编码任何一种发现路径。

产品注意事项：uzi 的 worker 目前只会从真实的 .claude/skills 目录枚举仓库技能，并且在其 ADR-0246 containment guard 下会跳过这两种符号链接形式。在 repo_skills_enabled 已启用的仓库中，worker 运行时将无法使用这些技能，直到 vtmocanu/uzi#1205 将 .agents/skills 加入第二个真实目录根路径。

Agent 定义并非可移植的技能目录

不要将 .agents/skills 布局照搬到 .agents/agents。这些运行时之间没有通用的 Agent 定义发现路径或文件架构：

• Claude Code 从 .claude/agents/ 读取 Markdown Agent 定义。

• Codex 从 .codex/agents/ 读取 TOML 自定义 Agent 定义；每个文件都必须包含 name、description 和 developer_instructions。

• OpenCode 从 .opencode/agents/ 读取 Markdown Agent 定义，并使用 OpenCode 专属的 frontmatter。

• Cursor 会读取 .cursor/agents/，也会读取 .claude/agents/ 和 .codex/agents/，并按同名优先级处理；它是否会将生成到后两者中的同一角色显示两次，尚未验证。

• Claude Code、Codex、OpenCode、Cursor 和 Gemini CLI 均不会读取 .agents/agents/。

不要在这些目录之间为同一个 Agent 定义文件创建符号链接。若要维护跨 Agent 的角色目录，请保留 roles.yaml 这类中立的源数据，然后为每种运行时生成并验证一个原生格式的投影。在适配器就绪之前，agent-team 技能仅原生支持 Claude Code（vtmocanu/skills#43）。

布局：文件夹形式的技能

将每项技能都编写为包含 SKILL.md 的文件夹——skills CLI 只会发现 <name>/SKILL.md，不会发现独立的 <name>.md 文件：

<name>/
├── SKILL.md            # required — frontmatter + body
├── scripts/foo.sh      # optional supporting files
└── references/bar.md   # optional

通过技能自身的基目录引用辅助文件；技能加载时，运行环境会提供该目录（以 Base directory for this skill: … 行的形式）。例如 <this skill's directory>/scripts/foo.sh。不要使用 ./scripts/foo.sh 这样的裸相对路径：运行时的工作目录是用户的项目，而不是技能目录，因此 ./ 会指向错误位置。直接调用随附脚本（<dir>/scan.sh，不要使用 bash <dir>/scan.sh）——将脚本设为可执行（0o755）；直接调用符合 Claude Code 的 Bash(/path/to/scan.sh:*) 权限范围，而 bash … 则需要范围宽泛得多的 Bash(bash:*)。

使用文件夹的原因在于辅助文件。只包含 SKILL.md 的文件夹表现得像扁平提示词——仍应使用文件夹形式，以便 npx 发现它。

嵌套在子路径下时需要 .claude-plugin/plugin.json 清单

整个仓库安装（容器 skills/）会发现最多嵌套 3 层的目录（skills/<cat>/<name>/SKILL.md、skills/<cat>/<cat>/<name>/SKILL.md），无需额外配置。子路径安装（npx -y skills@latest add owner/repo/skills/<sub>）则不会：CLI 只会向下遍历子路径目录 一层，因此位于 <sub>/<group>/<name>/SKILL.md 的技能会被 静默丢弃（没有错误；打包内容只是不会包含它）。此深度限制与获取引擎无关——CLI 仅对硬编码的所有者允许列表（vercel、vercel-labs、heygen-com，以及几个自托管仓库）使用快速 GitHub tree-API；其他所有者的仓库都会被克隆并遍历文件系统，而两种路径都会将子路径限制为一层。

解决方法：添加 <sub>/.claude-plugin/plugin.json 清单。清单声明的技能路径会跳过深度遍历（npx：“在其声明的深度搜索，不受有界深度 3 的目录遍历限制”）。

// skills/agent-kit/.claude-plugin/plugin.json
{ "name": "agent-kit", "skills": ["./agent-team", "./prd/prd-create", "./prd/prds-get"] }

CLI 会解析子路径目录下的每个条目并注册其 父 目录，然后在该目录下遍历一层以查找 SKILL.md。因此，条目 ./prd/<any-skill> 会注册整个 prd/ 文件夹，并找到其中的所有直接子级技能——添加到已注册文件夹中的新技能会 自动加入，无需修改清单。清单本身无法弥补的缺口：没有任何条目注册的全新嵌套文件夹。请在 CI 中通过覆盖检查来防范此问题：重新计算子路径安装会找到的内容，并在磁盘上的任何 SKILL.md 无法访问时失败（参见 scripts/check_bundle_coverage.py）。

通过实际对默认分支执行 add 来验证目录布局变更。add --branch <x> 和 add … -l 可能使用与 SessionStart 钩子所用默认分支安装不同的路径。

Frontmatter

name：

• 必填。 这是安装/显示名称；目录名仅作为后备值。
• 最多 64 个字符；只能使用小写字母、数字和连字符；不能包含 XML 标签。
• 保留子串 anthropic、claude——不要在 name: 中使用它们。

description——发现技能依赖此字段，请务必写好：

• 单行。 为确保可移植性（Anthropic Skills API）和干净的自动调用，请将描述保持为一行。
• 不要出现未加引号的 : （冒号加空格）。 普通 YAML 标量中的冒号加空格会被解析为映射指示符：skills CLI 解析器会拒绝它（mapping values are not allowed here），返回 null，并 静默跳过该技能——显示 ⚠ Skipped 警告，不报错，退出码为 0——因此该技能永远不会安装。请改写以避开 : ，或用双引号括起整个描述。
• 使用第三人称（“Generates X”“Manages Y”）。描述会注入系统提示词；使用第一或第二人称会破坏自动调用。
• 将所有“何时使用”信息放在此处，而不是正文中：Use when (1)… (2)… 和 Triggers include "…".
• 适当主动引导——模型调用技能的频率偏低。请将触发条件写成能促使模型调用的形式，而不是“相关时使用”。
• 风格目标约为 500–700 个字符；Anthropic Skills API 的 硬性上限为 1024 个字符（npx 本身不会强制执行；agnix 会将其报告为错误）。添加触发条件后重新运行 lint。描述会在每个会话中加载，因此不要填充无关内容。

持续加载成本 / 仅名称调用。 无论技能是否触发，description 都会在每个会话中加载，因此小众或匹配范围过宽的技能可能会产生实际的单会话成本。Claude Code 支持通过 settings.json 中的 skillOverrides（"<skill>": "name-only"）将技能设为仅显式调用时触发——描述将不再加载，但名称仍可用于调用。此设置适用于单一用途的技能，或触发范围过宽的技能。

设计原则

改编自 Anthropic 上游的 skill-creator（Apache 2.0）。

• 简洁。 只补充模型尚不了解的内容。使用祈使句（“提交前运行 agnix”），不要使用含糊措辞（“你应该”“我们建议”）。
• 受众是运行时的模型，而不是人类。省略入门说明、冗长的理由解释、变更日志和安装指南。
• 写指令，不做考古。 保留规则、触发条件、命令、约束和例外。删除日期、事件叙述、观察／验证／测量所得的轶事、解释添加原因的文字和根因历史。证据放在提交记录或 PR 中。只有行为取决于版本时才保留版本号。
• 发布时保留字节。 刷新或发布脚本绝不能自动改写文字。通过审阅精简编写的源内容。
• 探索发现，不要硬编码。 对于可变值（版本、IP、命名空间、密钥路径），提供发现它们的命令，而不是直接给出值——“如何查找 X”始终有效，“X 是 1.2.3”则会过时。任何具体值都要标注为示例，并告知模型重新查询。
• 具体程度应与易变程度相匹配。 判断因情况而异时使用文字说明；存在固定模式时使用参数化脚本；顺序至关重要时使用专用脚本。
• 提供默认方案，而非选项菜单。 选定一个推荐的工具／方法；只有在适用情形明显不同时才提供替代方案。
• 术语保持一致。 同一技能中，每个概念只使用一个术语。

正文预算与渐进式加载

层级	内容	加载时机	建议预算
1. 元数据	frontmatter（name + description）	始终加载，每个会话都会加载	约 100 个单词
2. 正文	frontmatter 后的 SKILL.md	技能触发时加载	< 500 行 / < 5K 个 token
3. 资源	scripts/、references/、assets/	按需加载	不限

正文超过约 500 行时，将详细内容拆分到 references/*.md（仅一层深度）。信息应放在 SKILL.md 或参考文件中，绝不能两处都有——重复内容会逐渐过时。

何时捆绑脚本

当操作步骤包含以下任一情况时，优先使用捆绑脚本，而不是内嵌代码片段：重复的多步编排（同一条 curl … | jq … 链出现三次或以上）、复杂的数据转换、重要的错误处理（401 时重试、部分失败时回滚），或自然形成的 CLI 接口（list／get／add 动词）。如果只有一条命令、用户需要阅读确切措辞，或技能规模较小，则保留为内嵌代码。

脚本约定：尽可能只使用标准库（不要在运行时执行 pip install）；一个脚本只负责一项功能（不要创建包罗万象的 helpers.sh）；直接调用；即使在 Windows 上也使用正斜杠路径。

命名

动名词（processing-pdfs）、名词短语（pdf-processing）或动作动词（process-pdfs）都可以。避免含糊名称（helper、utils、tools）和过于宽泛的名称（data、documents）。

内容陷阱

• 避免时效性内容。 不要写“如果时间在 2025 年 8 月之前，则执行 X”——这会过时。应固定版本（例如“自 ripgrep 14.0 起”）。将弃用路径放入“旧模式”／<details> 部分。
• 直接解决，不要推脱（脚本技能）。在脚本中处理 FileNotFoundError／PermissionError，不要失败后再要求模型自行恢复。
• 关键区块避免使用弱措辞。 在指令中将 should 替换为 MUST／祈使句；用户语音触发示例中的引用内容除外（将其放入代码围栏，使代码检查工具将其视为数据）。用正向替代方案表达否定要求（“使用常规克隆”，而不只是“不要浅克隆”）。

切勿在代码块中直接使用 $1 / $2

使用参数调用技能（/<skill> some args）时，运行器会将参数标记替换为 $N，包括围栏代码块在内的渲染正文中的所有位置。避免在代码块中使用 $N；优先使用 cut -f1、jq -r '.[0]' 或命名正则捕获组。如果无法避免使用 $N，请在代码片段旁注明 $1 是字面值。不要假设 $$1 / \$1 这样的转义方式有效，除非经过验证。

使用 agnix 进行 Lint 检查

提交任何技能更改前，将 <skill-file> 解析为实际编写的源文件：已发布文件夹源使用 <name>/SKILL.md，仓库本地的跨 Agent 源使用 .agents/skills/<name>/SKILL.md。然后运行 Lint 检查——agnix 能发现令牌冗余、措辞不够明确、指令含糊和关键词位置不当等问题：

agnix --target claude-code <skill-file>

对于跨 Agent 技能，请验证两种使用方：

agnix --target claude-code <skill-file>
agnix --target codex <skill-file>

--target 仍然有效，也会列在 agnix --help 中，但近期版本的 agnix 会提示 Field 'target' is deprecated，并建议改用配置文件中的 tools 数组（没有 --tools CLI 标志）；此警告无碍。如果你经常在某个仓库中运行 Lint 检查，可添加 .agnix.toml（agnix init），并设置 tools = ["claude-code"]，然后去掉该标志：agnix <skill-file>。

添加 --show-fixes 可预览改写结果；添加 --fix-safe 可应用可信度较高的修复（务必重新检查差异——“可修复”不等于“在当前上下文中正确”）。除了文件，也要对技能目录运行 Lint 检查：agnix <skill-dir> 还会检查 references/ 和其他附带的 Markdown 文件，而 agnix <skill-file> 会跳过这些文件。

agnix 会将换行的行内代码跨度中的 <placeholder> 识别为 Unclosed XML tag 错误；同一跨度若写在一行中则不会报错。请将每个行内代码跨度放在一行中，或将占位符写成 UPPER_CASE。

提交前必须修复错误；警告仅供参考——请修复实际存在的问题。已有警告也要处理：如果某个文件因实际更改而被打开，请指出更改前就存在的警告，并建议在同一提交中修复，而不是每次提交都让文件保留相同数量的警告。

**agnix 无法发现历史遗留问题。**Lint 检查通过后，请检查每个已编辑的 SKILL.md、引用文件、模板和资源，确认符合上述仅保留指令的规则。清除编辑过程中发现的已有杂项。

工作流

首先，检查源是否已接入 SessionStart 钩子。检查 ~/.claude/settings.json 和 ~/.codex/hooks.json；双 Agent 设置可能会将它们指向同一个共享包装器，因此也要检查包装器的源参数。如果已接入，只需提交并推送发布到该源的新技能或已编辑技能：刷新器会在下次会话开始时发现新技能并发布更新后的文件。如需立即使用，请直接调用已安装的刷新器。只有在该技能库的使用方都已关闭时，才运行会直接修改文件的 npx skills 命令；这类命令会替换正在使用的文件。钩子不会执行以下两项操作：删除已移除或重命名的技能（npx -y skills@latest remove），以及设置机器本地的 skillOverrides 状态，例如 settings.json 中的 name-only。

首次安装来源

npx -y skills@latest update 只会刷新锁定文件中已记录的技能，因此必须先添加全新技能（或尚未在此计算机上安装的来源）：

npx -y skills@latest add <source> -a claude-code codex -g  # canonical store + Claude projection; omit -g for project scope

<source> 接受 GitHub 的 owner/repo 简写或完整 URL。对于私有仓库，请使用 SSH 格式 git@host:owner/repo.git，这样克隆时会使用现有的 git 凭据（SSH 代理 / 凭据助手）。

• 审查来源而不安装：npx -y skills@latest add <source> -l 会列出仓库提供的所有技能（名称 + 描述）。可用它来查看来源，或检查上游新增的技能——update 永远不会发现新技能，因此可通过这种方式了解新技能。
• --skill 仅用于包含；没有排除标志。 如需安装除少数技能外的所有技能，可传入正向名称列表（--skill a b c），或者先安装 --skill '*'，再运行 npx -y skills@latest remove <name> -g -y。排除原因：某个技能的 name: 与内置技能重复（参见“启用 / 禁用”中的名称冲突注意事项）。

在会话启动时自动安装新技能并刷新（钩子）

使用捆绑的刷新器自动安装和更新：

~/.agents/skills/skill-maker/scripts/refresh_skills.py --source <source>

显式指定这两个目标至关重要。在 skills CLI 1.5.23 中，如果只指定非通用的 claude-code 目录，就会选择复制模式，且只写入 .claude/skills；Codex 或 OpenCode 无法发现规范的 .agents/skills 条目。指定 claude-code codex 则会选择规范目录加符号链接模式：Codex 提供通用的 .agents/skills 目标，Claude 使用符号链接，OpenCode 无需多余的第三个目标即可发现同一规范存储。更改包管理器版本时，请重新运行探测。

macOS/Linux 标准库封装程序会在暂存和发布期间持有 ~/.agents/.skills-refresh.lock 上的 fcntl.flock。它会请求 Vercel 的 CLI 使用 --skill '*' 将已配置的目录安装到临时项目中，然后按记录的名称和引用安装其他已跟踪的全局和当前项目依赖项。新目录中的技能会自动发现；skills-lock.json 中没有记录的仓库自有技能会保持不变。默认目录为此公共仓库；可重复使用 --source 指定其他必需目录，或使用 --best-effort-source 指定可选目录。Vercel 负责获取、发现和暂存安装；封装程序会将完整文件发布到实时规范目录和 Claude 存储，并调整暂存的锁定元数据。

读取方不会获取封装程序的锁。 它们通过暂存和原子文件替换获得保护，并在发布 SKILL.md 之前发布辅助文件。现有路径和已退役的辅助文件仍可读取；未更改的文件不会重写。这是逐文件原子操作，而非整个技能的快照。更改脚本、诊断缺失文件警告，或处理元数据和清理限制时，请阅读刷新安全性。

安装 skill-maker 后，请直接使用其实际安装的脚本路径。如果钩子命令必须保持稳定的信任标识，或需要提供机器本地的来源参数，请将其指向一个轻量的机器本地跳板程序，由它使用这些参数对已安装脚本执行 exec。切勿将刷新器实现复制到稳定路径：npx 会更新已安装的技能，而不会更新分离的副本，因此钩子会继续运行过时逻辑。只有在已安装脚本和任何跳板程序都已存在且可执行后，才能配置任一钩子。每个入口路径最终都必须执行已安装的刷新器；其在 ~/.agents/.skills-refresh.lock 上共享的 fcntl.flock 是串行化边界。

使用以下钩子位置和匹配器：

Agent	钩子文件	SessionStart 匹配器	额外步骤
Claude Code	~/.claude/settings.json	startup	无
Codex	~/.codex/hooks.json	startup|resume	使用 /hooks 审查处理程序并信任一次
对于 Codex，将包装器作为另一个 SessionStart 组添加，不要重新排序现有组，以保持其已保存的信任身份稳定：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "~/.agents/skills/skill-maker/scripts/refresh_skills.py",
            "timeout": 300,
            "async": true
          }
        ]
      }
    ]
  }
}

Codex 用户钩子从 ~/.codex/hooks.json 加载；新建或更改的钩子在通过 /hooks 信任之前会保持跳过状态；请参阅官方钩子文档。分阶段刷新器允许异步运行：会话可能以较旧的清单启动，同时替换操作会确保单个文件仍可读取。Codex 会在会话结束时取消未完成的后台钩子；下一次 startup 或 resume 会重试。如果刷新完成必须先于启动，请移除 async。仅采用同步运行并不能保护其他会话中的读取操作，因此无论如何都应保留分阶段机制。为两个 Agent 设置足够长的超时时间，以涵盖所有已配置和已跟踪的来源；基准值为 300 秒。

• add … --skill '*' 会安装 <source> 中当前的所有技能，因此新技能也会自动安装。--skill '*' 保留明确指定的 -a claude-code codex 范围；而 --all 会扩展到所有受支持的 Agent。

• **update 不能直接限定 Agent 范围。**其内部的 add 会面向所有检测到的 Agent。刷新器则会针对已记录的依赖项，使用分阶段且明确指定范围的 add 调用。它只会发布规范存储和 Claude 投影；OpenCode 会直接读取规范存储。它不会创建或刷新其他 Agent 的私有副本。

• 将暂存和发布操作置于同一次串行化的包装器调用中。直接运行 npx skills 命令不会遵守该锁。

• 将可选来源分别声明，这样无法访问某个目录时，已安装的文件会保持不变，刷新也不会失败：

  ~/.agents/skills/skill-maker/scripts/refresh_skills.py --source <reliable-source> --best-effort-source <vpn-only-source>
  

• 在非 TTY 钩子中，删除和重命名仍不会自动清理（请参阅“重命名 / 删除”）——使用 npx -y skills@latest remove <old> -g -y 删除旧名称。

编辑并发布现有技能

1. 在其仓库中编辑源文件 <name>/SKILL.md（以及任何辅助文件）。
2. 精简每个已编辑的软件包文件，只保留指令内容；移除编辑过程中发现的原有杂项。
3. 使用 agnix 检查；修复错误，并评估警告。
4. 在源仓库中提交并推送。只暂存你修改过的文件（git add <name>/）——不要运行 git add -A；工作树中其他技能可能有无关的进行中修改。
5. 通过调用已安装的刷新器发布，或等待它在下一次 SessionStart 调用时运行。关闭所有使用方后，仍可直接运行 npx -y skills@latest update -g -p（-g 表示全局，-p 表示当前项目）。不要在异步钩子中放入此类直接修改命令。
6. 验证规范的已安装存储和每个目标投影，因为模型读取的不是源文件：

   grep "<distinctive phrase from your edit>" ~/.agents/skills/<name>/SKILL.md
   grep "<distinctive phrase from your edit>" ~/.claude/skills/<name>/SKILL.md
   

重命名 / 删除

npx -y skills@latest update 只会同步锁文件中已跟踪的技能——它不会安装新命名的技能，也绝不会自动清理。在非交互式运行中（例如钩子运行，或没有 TTY），删除操作会显示 Skipping deletion in non-interactive mode，并将技能保留在磁盘和锁文件中；-y 不会改变这一行为，也没有 --prune 标志。因此，移除操作始终需要显式运行 npx -y skills@latest remove：

• 重命名：运行 git mv <old>/ <new>/，更新 name: 字段，使用 rg "<old>" . 搜索仓库中的引用，然后提交并推送。之后，在每台机器上运行 npx -y skills@latest add <source> 安装新名称，并运行 npx -y skills@latest remove <old> -g -y 移除旧名称。
• 删除：运行 git rm -r <name>/，搜索引用，然后提交并推送。之后，在每台机器上运行 npx -y skills@latest remove <name> -g -y（交互式运行 npx -y skills@latest update 也会提示移除；非交互式运行则不会）。

remove 接受技能名称（以空格分隔）或 --all；没有 --source <repo> 筛选选项，因此请逐一指定要删除的技能。标志用法与其他命令一致：-g 表示全局，-a <agent> 表示限定到一个 Agent，-y 表示跳过确认。

安装范围（skills CLI）

• 范围：当目标集合包含 Codex 这类通用 Agent 时，npx 会将规范安装存储保留在 .agents/skills 下，并创建特定于 Agent 的映射目录，例如 .claude/skills。单个非通用目标可以使用复制模式，完全跳过规范存储。全局安装使用 $HOME；项目安装使用代码仓库。add/update/remove 默认为项目范围；传入 -g 可指定全局范围。update -g -p 会同时执行两者。
• 锁文件：全局 → ~/.agents/.skill-lock.json；项目 → <project-root>/skills-lock.json。锁文件会记录每个已安装技能的来源；~/.claude/skills/ 下的安装副本不携带锁文件。
• 文件存放位置（共享存储 + 目标映射目录）：使用 -a claude-code codex 时，全局实际文件位于 ~/.agents/skills/<name>/ 下，项目实际文件位于 <repo>/.agents/skills/<name>/ 下，而 Claude 会获得指向对应 .claude/skills/<name> 的符号链接。OpenCode 会直接读取规范存储。其他目标组合可能会选择复制模式，因此更改目标列表后，请确认具体路径。点文件的影响：如有需要，可跟踪全局共享存储（例如，将 ~/.agents 符号链接到点文件代码仓库），并将本机专用的全局锁文件加入 gitignore；该锁文件会在每次 add/update 时重写。
• 在代码仓库中编写的本地技能有所不同：由代码仓库拥有且未出现在 skills-lock.json 中的技能，会将 <repo>/.agents/skills/<name> 用作可编辑源，并使用刻意纳入版本控制的 .claude/skills/<name> 符号链接。npx 不会管理或重写这对路径。

启用 / 禁用已安装的技能

npx 不支持启用/禁用 — 技能要么已安装（处于活动状态），要么已移除。若要保留磁盘上的技能但将其关闭，请使用 Claude Code 在 ~/.claude/settings.json 中提供的 skillOverrides。这是一个按技能名称（而非来源）索引的四态控制，比插件的布尔值 enabledPlugins 更灵活：

状态	显示给模型	在 / 菜单中	自动触发	手动 /name
on（默认）	名称 + 描述	是	是	是
name-only	仅名称（节省上下文）	是	是	是
user-invocable-only	隐藏	是	否	是
off	隐藏	隐藏	否	否

可在 /skills 菜单中切换状态（按 Space 切换，按 Enter 保存），也可直接编辑 skillOverrides。skillOverrides 会保存在 settings.json 中，因此启用/禁用状态可纳入版本控制。

• 禁用技能时，优先使用 off，而不是 permissions.deny: ["Skill(<name>)"]：deny 只会在调用时进行拦截，且技能仍会出现在上下文中；off 则会将其完全移除（不消耗上下文，不会自动触发）。
• 名称冲突注意事项：由于覆盖项按名称索引，切勿安装 name: 与内置技能重复的技能（例如 claude-api）——单个 "claude-api": "off" 也会影响内置技能。请在安装时排除这类技能（参见“安装来源”中的仅包含说明）。