diff --git a/docs/skill-anatomy.md b/docs/skill-anatomy.md index 5f0d336..2a1ca86 100644 --- a/docs/skill-anatomy.md +++ b/docs/skill-anatomy.md @@ -107,6 +107,16 @@ Keep patterns and principles inline when under 50 lines. If a skill does not need runnable helpers, do not create an empty `scripts/` directory just to mirror other skills. Empty directories add noise without changing how the skill works. +## Shared References + +Checklists used by more than one skill — testing, security, performance, accessibility, definition-of-done — live in `references/` at the repository root, deliberately *not* inside any skill directory. + +This is a pack-level design choice. The Agent Skills spec describes a skill as a self-contained directory, but several skills here point at the same checklists. Colocating those would force one of two options: copy the checklist into every skill that uses it, or pick one skill to "own" it and have the others reach into that directory. Both drift over time. A single repo-root copy stays the source of truth. + +The tradeoff is portability: a whole-repo install (such as the Claude Code marketplace plugin) carries `references/` along, but a per-skill install that copies only `skills//` leaves the repo-root sibling behind, and those links resolve to nothing. That gap is tracked in [#361](https://github.com/addyosmani/agent-skills/issues/361). + +Current convention: material used by exactly one skill is a supporting file inside that skill's directory; material shared across skills goes in `references/`. + ## Context Efficiency Skills load on demand: only the skill name and description sit in context at startup. The full `SKILL.md` loads only when an agent decides the skill is relevant. To keep that load cheap: @@ -142,7 +152,7 @@ When a skill ships runnable helpers under `scripts/`, each script follows these - Skill directories: `lowercase-hyphen-separated` - Skill files: `SKILL.md` (always uppercase) - Supporting files: `lowercase-hyphen-separated.md` -- References: stored in `references/` at the project root, not inside skill directories +- References: stored in `references/` at the project root, not inside skill directories (see [Shared References](#shared-references) for why) ## Cross-Skill References