同一个 SKILL.md 装进四个宿主：Agent Skills 的目录约定、冲突优先级与安装坑

Agent Skills 是一套开放、基于文件系统的格式，用来封装过程性知识——可复用的指令、脚本、参考资料，宿主只在需要时才把它们读进 LLM 上下文。Anthropic 在 2025 年 12 月把它作为独立于 Claude 实现的开放标准发布，站点在 agentskills.io。

它不是网络协议。没有 JSON-RPC 握手，也没有 tools/list 之类的调用。宿主启动时把目录元数据读进系统提示，需要时再用 bash 读完整文件。

目录结构

一个 skill 就是一个目录，至少包含一个 SKILL.md，文件夹名就是技能名。

skill-name/
├── SKILL.md      # 必需：元数据 + 指令
├── scripts/      # 可选：可执行代码
├── references/   # 可选：参考文档
└── assets/       # 可选：模板、资源

SKILL.md 是 YAML frontmatter 加 Markdown 正文：

正文建议控制在 500 行 / 5000 token 以内，更详细的内容挪到 references/。

三级渐进披露

1. 元数据（约 100 token）：所有技能的 name + description，启动时加载。
2. 指令（建议 --path skills`。

• Command Code：~/.commandcode/skills/（用户）、.commandcode/skills/（项目），同时兼容 .agents/skills/ 与 ~/.agents/skills/，在 /skills 菜单里显示 [.agents] 徽标。发现时会从工作目录向上最多走 10 层找 .agents/skills/，在 home 目录停止，避免把 ~/.agents/skills/ 当项目级来源。

Command Code 的位置优先级从高到低：

1. .commandcode/skills/（项目）
2. .agents/skills/（项目）
3. ~/.commandcode/skills/（用户）
4. ~/.agents/skills/（用户）
5. 额外位置（--skill 标志优先，然后 settings 里的 skills 数组）
6. 自带的 bundled skills

项目级永远压过用户级；同级里 .commandcode/ 压过 .agents/。同名冲突时高优先级副本生效，被遮蔽的副本不会静默丢弃，会以 Duplicate names 警告出现在 /skills 的问题视图和 cmd skills list --debug。

冲突时的调用方式值得记一下：键入 / 永远解析到高优先级的所有者（比如内置命令），技能不会被调用。要用 /skill:——这个命名空间完全跳过优先级阶梯，只解析到技能，被遮蔽的也能跑。单独输入 /skill: 会列出全部技能。

额外位置通过 settings.json 的 skills 数组指定，可指向任意目录（~/team/shared-skills、./vendor/skills、/opt/company/skills），~/ 展开为 home，相对路径相对项目根（git root）。settings 分层是整体覆盖数组，最高层定义者胜出。启动旗标 --skill 可重复，为单次会话加位置；--no-skills 完全跳过发现，但 --skill 给的路径仍加载。

递归发现有一点容易踩：技能可以分组在中间目录下，但每个技能仍是直接包含 SKILL.md 的那一级目录，name 匹配技能自己的目录（如 changelog-writer），不是分组目录。技能自己的 scripts/、references/、assets/ 不会再被扫描成技能。

校验失败的表现

• name 与目录名不一致，技能被跳过。
• description 缺失或为空，永远不加载。
• 违反规则不会让会话失败，只给出分类警告，可见于 /skills 与 cmd skills list --debug。

官方参考库 skills-ref（Python CLI）可以校验 frontmatter 合法性。

扩展字段与可移植性

Command Code 额外认这些字段，其中若干与 Agent Skills / Claude Code frontmatter 对齐，所以为别的 agent 写的技能能原样加载，不认识的工具会安全忽略：

• argument-hint：在 / 菜单里显示参数提示
• when_to_use：额外触发上下文，追加到面向模型的目录说明里
• disable-model-invocation：为 true 时对模型完全隐藏，只能显式 /skill-name 调用，用于破坏性或高度上下文相关的流程
• user-invocable：为 false 时模型可调用，但对 / 菜单隐藏
• disallowed-tools、arguments（声明位置参数名，启用 $issue/$branch 占位符）、model、effort

占位符替换支持 $ARGUMENTS、$ARGUMENTS[N]/${N}、声明的 $name、${COMMANDCODE_SKILL_DIR}、${COMMANDCODE_PROJECT_DIR}、${COMMANDCODE_SESSION_ID}、${COMMANDCODE_EFFORT}。其中 ${CLAUDE_SKILL_DIR}、${CLAUDE_PROJECT_DIR}、${CLAUDE_SESSION_ID}、${CLAUDE_EFFORT} 是别名，解析到同样的值，所以为 Claude Code 写的技能能原样工作。只替换这些已知 token，其他 ${...}（比如字面 ${HOME}）原样保留。所有占位符单遍替换，参数文本里看起来像占位符的内容不会被二次展开。

实操：addyosmani/agent-skills 作为可移植技能包

仓库：github.com/addyosmani/agent-skills，MIT，Shell 为主，约 49.2k stars，最新 release 0.6.1（2026-05-23）。

25 个技能（24 个生命周期技能 + using-agent-skills 元技能），映射 DEFINE / PLAN / BUILD / VERIFY / REVIEW / SHIP 六个阶段。

走 vercel-labs/skills CLI 的一行安装，可装进 70+ agent：

npx skills add addyosmani/agent-skills            # 装全部 25 个技能
npx skills add addyosmani/agent-skills --list     # 装前浏览
npx skills add addyosmani/agent-skills --skill code-review-and-quality

各宿主原生命令：

# Claude Code
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

# Codex（直接读根 skills/ 目录，通过 .codex-plugin/plugin.json）
codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills

# Gemini CLI
gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

# Antigravity CLI
agy plugin install https://github.com/addyosmani/agent-skills.git

Claude Code 走 SSH 报错时，可以换成完整 HTTPS URL，或者：

git config --global url."https://github.com/".insteadOf git@github.com:

per-skill 安装的坑：只单独装一个技能时，npx 的 per-skill 安装只复制 skills//，不含仓库级 references/ 目录。技能仍能用，但指向共享检查清单的路径会失效。解决办法是整仓库集成、clone 仓库，或把需要的清单拷进已安装技能的 references/。这个缺口记录在 issue #361。

每个技能的结构固定为 Overview / When to Use / Process / Rationalizations（借口与反驳表）/ Red Flags / Verification（证据要求）。设计原则四条：Process, not prose；Anti-rationalization；Verification is non-negotiable；Progressive disclosure。

仓库分层：skills/（可移植核心）、agents/（4 个 persona）、references/（7 个检查清单），以及各宿主适配目录（.claude/commands、.gemini/commands、.codex-plugin/ 等）。宿主特定路径是原生发现约定，不是品牌别名，改名或合并会破坏扫描这些位置的工具。与 Superpowers（obra/superpowers）、Matt Pocock 技能包的对比见 docs/comparison.md。

边界与未解点

一些周边事实值得记着：2026 年论文 SkillsBench 的经验结论是，Skill 是可单独测量、常显著提升表现的工程变量；社区统计口径称约 40 个产品支持该格式，技能市场上架总量超 49 万（不同来源口径不一，未逐一独立核实）。Claude API 上启用 Skills 需要三个 beta 头：code-execution-2025-08-25、skills-2025-10-02、files-api-2025-04-14。例示技能是 Apache-2.0；Anthropic 预置的文档技能（docx/pdf/pptx/xlsx）是 source-available，不是开源。

真正没定论的是 .agents/skills/ 会不会成为跨宿主的事实标准——Command Code 兼容它，Codex 用它，Claude Code 目前还认 .claude/skills/。另一处是扩展字段的兼容边界：disable-model-invocation、arguments、model 这类字段，不认识它们的宿主会安全忽略，但"忽略"意味着行为降级，而不是行为一致。一个技能在 A 宿主里只能显式调用，到 B 宿主里可能就对模型可见了。

参考链接：

• agentskills.io/specification
• platform.claude.com — Agent Skills overview
• github.com/anthropics/skills
• github.com/vercel-labs/skills
• commandcode.ai/docs/skills
• github.com/addyosmani/agent-skills