# Script & Skill Documentation

Every script in `claude-foundations` and every skill in `custom-claude-skills` must have a corresponding memory file in `claude-foundations/memory/`:

- **Scripts:** `memory/script-<name>.md` — purpose, usage, how it works, gotchas
- **Skills:** `memory/skill-<name>.md` — purpose, usage, how it works, gotchas, which projects use it

Each memory file should be self-contained and referenced from `claude-foundations/MEMORY.md` (the index). Future sessions can then understand what tooling exists without reading every script and SKILL.md from scratch.

**When creating a new script or skill:** create the memory file and update the MEMORY.md index as part of the same commit.

**When creating or editing a skill:** run `validate-skill <path/to/SKILL.md>` before committing. The validator catches known restriction violations that have repeatedly broken skills — `$VAR` in paths, `${VAR}` syntax, `$()` substitution, uncovered binaries in `allowed-tools`, and more. A skill must pass with zero errors before it is committed. Warnings should be reviewed but are acceptable.