Background
While reviewing #2311, the security reviewer noticed that docs/reference/file-formats.md links to the FAQ as ../faq.md#.... That path is correct inside docs/reference/, but scripts/sync-skill-docs.ts copies all docs into the flat skills/rulesync/ directory, where faq.md is a sibling — so the copied ../faq.md links resolve to a nonexistent path in the distributed skill.
This is a pre-existing characteristic of the sync script (other unchanged paragraphs in the same file carry identical ../faq.md links), not something introduced by #2311.
Possible solution
Teach scripts/sync-skill-docs.ts to rewrite relative links during sync: strip directory segments so cross-doc links point at the sibling file in the flat mirror (e.g. ../faq.md#anchor → faq.md#anchor, ./configuration.md stays as-is). A check could also assert that all relative links in skills/rulesync/ resolve to files in that directory.
Noted by Claude Code review agents during #2311.
Background
While reviewing #2311, the security reviewer noticed that
docs/reference/file-formats.mdlinks to the FAQ as../faq.md#.... That path is correct insidedocs/reference/, butscripts/sync-skill-docs.tscopies all docs into the flatskills/rulesync/directory, wherefaq.mdis a sibling — so the copied../faq.mdlinks resolve to a nonexistent path in the distributed skill.This is a pre-existing characteristic of the sync script (other unchanged paragraphs in the same file carry identical
../faq.mdlinks), not something introduced by #2311.Possible solution
Teach
scripts/sync-skill-docs.tsto rewrite relative links during sync: strip directory segments so cross-doc links point at the sibling file in the flat mirror (e.g.../faq.md#anchor→faq.md#anchor,./configuration.mdstays as-is). A check could also assert that all relative links inskills/rulesync/resolve to files in that directory.Noted by Claude Code review agents during #2311.