github-featured/addyosmani--agent-skills
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: document skill-local references/ directory in skill anatomy

Browse Source
This commit is contained in:
Joan Leon
2026-06-10 23:38:06 +02:00
parent 2fbfa004a0
commit 8fd208160c
2 changed files with 5 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+1 -1
View File
@@ -31,7 +31,7 @@ docs/ → Setup guides for different tools
- YAML frontmatter with `name` and `description` fields
- Description starts with what the skill does (third person), followed by trigger conditions ("Use when...")
- Every skill has: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification
- References are in `references/`, not inside skill directories
- Shared references are in the root `references/` directory; the emerging convention for self-contained, distributable skills keeps a skill's own references inside `skills/<name>/references/`
- Supporting files only created when content exceeds 100 lines
## Contributing
docs/skill-anatomy.md
+4 -2
View File
@@ -11,10 +11,11 @@ skills/
skill-name/
SKILL.md # Required: The skill definition
scripts/ # Optional: Runnable helpers used by the skill workflow
references/ # Optional: Skill-specific reference documentation
supporting-file.md # Optional: Reference material loaded on demand
```
`SKILL.md` is the only required file. Add `scripts/` only when the skill actually ships runnable helpers, and omit the directory entirely for markdown-only skills.
`SKILL.md` is the only required file. Add `scripts/` or `references/` only when the skill actually needs them, and omit them entirely for simpler skills.
## SKILL.md Format
@@ -152,7 +153,8 @@ 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 (see [Shared References](#shared-references) for why)
- Shared references: stored in the root `references/` directory, not inside skill directories (see [Shared References](#shared-references) for why).
- Skill-specific references: the emerging convention for self-contained, distributable skills is a `references/` directory inside the skill directory, so the skill carries its own supporting docs.
## Cross-Skill References