External/agent-skills
1
0
Fork 0
mirror of https://github.com/addyosmani/agent-skills.git synced 2026-08-12 18:07:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #401 from kevglynn/contrib/329-shared-references-rationale

Browse Source 
docs(skill-anatomy): explain the shared references/ design
This commit is contained in:
Federico Bartoli
2026-07-18 15:19:55 +02:00
committed by GitHub
parent 06300e258e aca5326aba
commit 2fbfa004a0
1 changed files with 11 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/skill-anatomy.md
+11 -1
View File
@@ -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/<name>/` 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