From b7e7c9587d8e8282e1d810cc079c810128a499f3 Mon Sep 17 00:00:00 2001 From: Kevin Glynn Date: Tue, 14 Jul 2026 13:00:52 -0400 Subject: [PATCH 1/2] docs(skill-anatomy): explain the shared references/ design (closes addyosmani#329) Issue addyosmani#329 asked why shared checklists live in repo-root references/ instead of being colocated per skill directory as the Agent Skills spec suggests. The rationale existed only in a comment: several skills point at the same checklists, and colocating means either duplication or a single "owner" skill, both of which drift. Fold that rationale into skill-anatomy.md as a Shared References section, including the per-skill install portability tradeoff (addyosmani#361) and a rule of thumb for supporting file vs shared reference. Cross-link from Naming Conventions. Co-authored-by: Cursor --- docs/skill-anatomy.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/skill-anatomy.md b/docs/skill-anatomy.md index 5f0d336..32f6744 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). + +Rule of thumb: 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 From aca5326abab9f169a1d5d44f6a3a604c2e83e67f Mon Sep 17 00:00:00 2001 From: Kevin Glynn Date: Wed, 15 Jul 2026 01:46:16 -0400 Subject: [PATCH 2/2] docs(skill-anatomy): reword rule of thumb to current convention per review --- docs/skill-anatomy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/skill-anatomy.md b/docs/skill-anatomy.md index 32f6744..2a1ca86 100644 --- a/docs/skill-anatomy.md +++ b/docs/skill-anatomy.md @@ -115,7 +115,7 @@ This is a pack-level design choice. The Agent Skills spec describes a skill as a 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). -Rule of thumb: material used by exactly one skill is a supporting file inside that skill's directory; material shared across skills goes in `references/`. +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