执行摘要
此 PR 将共享 agent skills 从文件级符号链接重构为目录级符号链接，同时将规范技能文件组织为目录包结构（<skill>/SKILL.md）。变更不涉及运行时代码，但统一了技能文件的布局，使得未来添加辅助文件时所有框架自动同步。主要风险是 SKILL.md 中相对链接可能断裂，以及框架自定义能力受限。
功能与动机
根据 PR 描述，此变更旨在将共享 agent skills 从文件符号链接转为目录符号链接，使得在技能旁边添加支持文件时能自动传递到每个框架，无需逐个文件配置。这是对 #5846（最初的 .agent/skills 引入）的后续改进，解决文件级符号链接需要手动更新每个框架的问题。
实现拆解
- 移动规范技能文件：将
.agent/skills/issue.md 重命名为 .agent/skills/issue/SKILL.md，同理处理 pr.md。文件内容保持不变（100% 相似重命名），但位置变为子目录，形成技能包结构。
- 替换符号链接：删除
.claude/skills/issue.md 和 .claude/skills/pr.md 文件级符号链接，并分别创建目录符号链接 .claude/skills/issue 和 .claude/skills/pr，指向 ../../.agent/skills/issue 和 ../../.agent/skills/pr。对 .codex/skills/ 下的对应文件做相同处理。目录符号链接使得整个技能目录（包括未来可能新增的辅助文件）自动对每个框架可见。
- 更新贡献文档：在
docs/contributing/editing-agent-instructions.md 中新增技能布局约定，说明 canonical 技能应放在 .agent/skills/<skill>/SKILL.md，各框架的目录应使用目录符号链接。同时更新了 Last updated 日期。
关键源码片段
以下为 docs/contributing/editing-agent-instructions.md 中新增的关于技能文件布局的约定说明：
<!-- 这是新增的技能布局约定段落，解释了 canonical 技能文件的位置和各框架目录符号链接的要求 -->
For skills, keep canonical content under `.agent/skills/<skill-name>/SKILL.md`.
Variant trees such as `.codex/skills/<skill-name>` and `.claude/skills/<skill-name>` should be directory symlinks to the canonical `.agent` skill directory, not directories containing only a symlinked `SKILL.md`.
Codex documents support for symlinked skill folders and can skip file-level `SKILL.md` symlinks during discovery. Claude Code discovers the file-level symlink layout in current versions, but directory symlinks match the shared skill-package structure and keep supporting files in sync across frameworks.
评论区精华
代码审查机器人 gemini-code-assist[bot] 提出了三个高优先级问题：
- 链接断裂风险：移动文件到子目录会破坏
SKILL.md 中相对路径引用（例如 ../../../.github/...），需要更新引用路径。
- 框架自定义受限：目录符号链接使得无法为特定框架添加自定义文件，与之前允许框架特定内容的原则相悖，建议改为目录中包含 symlinked
SKILL.md 的方式。
- 文档歧义：关于 Claude Code 对两种符号链接布局的支持描述不清晰，需要明言两者皆支持。
以上问题均未在 PR 中得到回应或解决，但 PR 已合并。
风险与影响
- 链接断裂：
SKILL.md 中如果存在指向父目录的相对 Markdown 链接，例如链接到 .github/ISSUE_TEMPLATE/，由于文件位置从 .agent/skills/ 变更为 .agent/skills/issue/，路径将需要调整（可能需要从 ../../.github/... 变为 ../../../.github/...）。
- 框架自定义限制：未来如果某个框架需要为特定技能增加专属文件（如 Claude 专用的配置文件），目录符号链接会使得该文件也出现在其他框架的技能目录中，造成混乱。
- 文档表述模糊：更新后的文档描述可能导致贡献者混淆关于技能布局的正确做法。
影响范围限于存储库中的技能文件和贡献者文档，对系统行为无影响。
关联脉络
此 PR 是 #5846（最初的 .agent/skills 引入）的后续改进，属于同一技能共享基础设施的演进。未来可能进一步调整布局以解决框架自定义能力的问题。
参与讨论