Keep identical sections across skills in sync

[PaulRBerg]

Problem

Several skills share verbatim-identical sections that must be kept in sync manually. The most obvious example is the Scope Resolution section, which is copy-pasted across code-review and code-simplify (and referenced by code-polish). Any edit to one requires remembering to update the other — and forgetting is guaranteed over time.

Files Affected

Toggle to see affected files

• code-review/SKILL.md
• code-simplify/SKILL.md
• code-polish/SKILL.md

Solution

A few options worth considering:

1. Shared references/ partials

Extract the duplicated section into a shared file (e.g., skills/_shared/scope-resolution.md or a references/ file), and have each skill reference it:

## Scope Resolution

See `references/scope-resolution.md`.

This is the simplest approach and already aligns with how code-review loads its profile references. The downside is that Claude Code doesn't natively support cross-skill references/ — each skill's references are resolved relative to its own directory.

2. Symlinks

Symlink a shared reference into each skill's references/ directory:

skills/code-review/references/scope-resolution.md -> ../../_shared/scope-resolution.md
skills/code-simplify/references/scope-resolution.md -> ../../_shared/scope-resolution.md

Works transparently with the existing references/ resolution. Symlinks are well-supported on macOS/Linux but can be finicky on Windows and in some git configurations.

3. CI lint check

Keep the duplication but add a validation script (similar to code-review/scripts/validate-references.sh) that asserts the duplicated sections are byte-identical. Fails in CI if they drift. Doesn't remove the duplication but makes drift impossible to miss.

4. Single canonical skill + delegation

Consolidate the shared logic into a single "base" skill (e.g., code-base) that handles scope resolution, and have code-review and code-simplify delegate to it. This is the cleanest architecturally but adds indirection and may complicate the skill dispatch model.

Note

This isn't limited to Scope Resolution — other sections like "Verification" and "Stop Conditions" also have significant overlap between the two skills. Worth considering a general-purpose solution rather than a one-off fix.