# PR #6391 完整报告

- 仓库：`verl-project/verl`
- 标题：[misc] fix: use directory-symlink layout for shared skills
- 合并时间：2026-05-18 18:29
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6391

---

# 执行摘要

此 PR 将共享 agent skills 从文件级符号链接重构为目录级符号链接，同时将规范技能文件组织为目录包结构（`<skill>/SKILL.md`）。变更不涉及运行时代码，但统一了技能文件的布局，使得未来添加辅助文件时所有框架自动同步。主要风险是 `SKILL.md` 中相对链接可能断裂，以及框架自定义能力受限。

# 功能与动机

根据 PR 描述，此变更旨在将共享 agent skills 从文件符号链接转为目录符号链接，使得在技能旁边添加支持文件时能自动传递到每个框架，无需逐个文件配置。这是对 #5846（最初的 `.agent/skills` 引入）的后续改进，解决文件级符号链接需要手动更新每个框架的问题。

# 实现拆解

1. **移动规范技能文件**：将 `.agent/skills/issue.md` 重命名为 `.agent/skills/issue/SKILL.md`，同理处理 `pr.md`。文件内容保持不变（100% 相似重命名），但位置变为子目录，形成技能包结构。
2. **替换符号链接**：删除 `.claude/skills/issue.md` 和 `.claude/skills/pr.md` 文件级符号链接，并分别创建目录符号链接 `.claude/skills/issue` 和 `.claude/skills/pr`，指向 `../../.agent/skills/issue` 和 `../../.agent/skills/pr`。对 `.codex/skills/` 下的对应文件做相同处理。目录符号链接使得整个技能目录（包括未来可能新增的辅助文件）自动对每个框架可见。
3. **更新贡献文档**：在 `docs/contributing/editing-agent-instructions.md` 中新增技能布局约定，说明 canonical 技能应放在 `.agent/skills/<skill>/SKILL.md`，各框架的目录应使用目录符号链接。同时更新了 Last updated 日期。

## 关键源码片段

### 以下为 `docs/contributing/editing-agent-instructions.md` 中新增的关于技能文件布局的约定说明：

```markdown
<!-- 这是新增的技能布局约定段落，解释了 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` 引入）的后续改进，属于同一技能共享基础设施的演进。未来可能进一步调整布局以解决框架自定义能力的问题。