feat(skills): inline references/ at load time for Anthropic Skills compat (#2214)#2230
Conversation
…lls compat (esengine#2214) Skills following the Anthropic Skills spec ship a references/ subdirectory with depth material. Reasonix only loaded SKILL.md, leaving [[references/...]] wikilinks as dead text and making the depth content invisible to the model. Append each references/*.md file to the skill body at load time under a '## Reference: <slug>' header (sorted alphabetically). This follows Option A from the issue: zero protocol overhead, all depth material available immediately. Only dir-layout skills (those with a SKILL.md) can have a sibling references/; flat <name>.md skills are unaffected.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
@codex review |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
esengine
left a comment
There was a problem hiding this comment.
Reviewed — clean and safe. loadBodyWithReferences derives refsDir as a fixed sibling of SKILL.md (join(dirname(skillFilePath), "references")), gated on existsSync, and inlines the .md entries it reads from readdirSync(refsDir). Since the filenames come from the actual directory listing (not from parsing user-controlled [[references/...]] paths out of the body), there's no path-traversal exposure — join(refsDir, entry) can't escape the skill's own references dir. Skills without a references/ dir are untouched. Good Anthropic-Skills-spec compat (#2214). One minor note (non-blocking): there's no size cap on the inlined material, so a very large references/ dir bloats the skill body / prompt — fine for v1 since that's the skill author's call and the spec's intent, but a cap or lazy-load could be a follow-up if it bites. CI green. Merging.
|
我对这里的语义变化有个 concern：这个 PR 现在会在 skill 被解析/读取时，把该 skill 同级 我看了一下 OpenCode 和 Codex 的实现，它们对这类 skill 目录的处理更偏渐进式：
所以我担心这个 PR 虽然解决了 “reference 内容不可见” 的问题，但会把原本的 progressive disclosure 语义变成 eager/bulk loading。对于 |
问题
关闭 #2214。遵循 Anthropic Skills spec 的技能会在 SKILL.md 旁边放一个
references/目录存放深度参考资料，通过[[references/xxx]]引用。Reasonix 目前只读 SKILL.md，reference 内容对模型不可见，来自 OpenKB 等工具生成的技能会失去核心参考材料。方案（Option A — 加载时 inline）
在
parse()时检测同级references/目录，把找到的.md文件按字母序追加到 body：只影响 dir-layout 技能（带 SKILL.md 的目录形式），flat
<name>.md不受影响。验证
npm run verify通过