Marcos Paulo
ab2308441c
The repository had two skill directories. `skills/` held the four written for this project; `.agents/skills/` held the ones the agent context refers to. Nothing said which an agent should read, and `.agents/ORCHESTRATOR.md` only ever pointed at the second. Move the first four into `.agents/skills/` so there is one location, and add the vendored packages this chapter work used: `animation-vocabulary` and `improve-animations` (emilkowalski/skills), `teach` (mattpocock/skills), plus a local `translation` skill and `audit-translations.mjs` for the EN/PT pairs. `skills-lock.json` pins the vendored three by source and content hash, so a later re-vendor is a diff rather than a guess. `.claude/skills/` is symlinks into `.agents/skills/`, which is what makes them loadable here without a second copy on disk. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
49 lines
2.1 KiB
Markdown
49 lines
2.1 KiB
Markdown
# GLOSSARY.md Format
|
||
|
||
`GLOSSARY.md` is the canonical language for this teaching workspace. All
|
||
explainers, exercises, and learning records should adhere to its terminology.
|
||
Building it is itself part of learning: compressing a concept into a tight
|
||
definition is evidence the user understands it.
|
||
|
||
## Structure
|
||
|
||
```md
|
||
# {Topic} Glossary
|
||
|
||
{One or two sentence description of the topic this glossary covers.}
|
||
|
||
## Terms
|
||
|
||
**Hypertrophy**: Muscle growth driven by mechanical tension and metabolic stress
|
||
over repeated training sessions. _Avoid_: Bulking, getting big
|
||
|
||
**Progressive overload**: Systematically increasing the demand on a muscle over
|
||
time, via load, volume, or intensity. _Avoid_: Pushing harder, levelling up
|
||
|
||
**RPE (Rate of Perceived Exertion)**: A 1–10 self-rating of how hard a set felt,
|
||
where 10 is failure and 8 means two reps left in the tank. _Avoid_: Effort
|
||
score, intensity rating
|
||
```
|
||
|
||
## Rules
|
||
|
||
- **Add a term only when the user understands it.** The glossary is a record of
|
||
compressed knowledge, not a dictionary the user reads to learn. If the user
|
||
has just been introduced to a concept, wait until they can use it correctly
|
||
before promoting it here.
|
||
- **Be opinionated.** When several words exist for the same concept, pick the
|
||
best one and list the rest as aliases to avoid. This is how language
|
||
compresses.
|
||
- **Keep definitions tight.** One or two sentences. Define what the term IS, not
|
||
what it does or how to do it.
|
||
- **Use the glossary's own terms inside definitions.** Once a term is in the
|
||
glossary, prefer it everywhere, including inside other definitions. This is
|
||
what makes complex terms easier to grasp later.
|
||
- **Group under subheadings** when natural clusters emerge (e.g. `## Anatomy`,
|
||
`## Programming`). A flat list is fine when terms cohere.
|
||
- **Flag ambiguities explicitly.** If a term is used loosely in the wider field,
|
||
note the resolution: "In this workspace, 'set' always means a working set;
|
||
warm-ups are tracked separately."
|
||
- **Revise as understanding deepens.** A definition the user wrote in week one
|
||
may be wrong by week six. Update in place; do not leave stale entries.
|