chore: consolidate the skill packages under .agents/
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>
This commit is contained in:
Marcos Paulo
@@ -0,0 +1,48 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,69 @@
|
||||
# Learning Record Format
|
||||
|
||||
Learning records live in `./learning-records/` and use sequential numbering:
|
||||
`0001-slug.md`, `0002-slug.md`, etc. Create the directory lazily: only when the
|
||||
first record is written.
|
||||
|
||||
They are the teaching equivalent of ADRs: they capture non-obvious lessons, key
|
||||
insights, and stated prior knowledge that will steer future sessions. They are
|
||||
used to calculate the zone of proximal development.
|
||||
|
||||
## Template
|
||||
|
||||
```md
|
||||
# {Short title of what was learned or established}
|
||||
|
||||
{1-3 sentences: what was learned (or what prior knowledge was established), and
|
||||
why it matters for future sessions.}
|
||||
```
|
||||
|
||||
That is the whole format. A learning record can be a single paragraph. The value
|
||||
is recording _that_ this is now known and _why_ it changes what to teach next,
|
||||
not in filling out sections.
|
||||
|
||||
## Optional sections
|
||||
|
||||
Only include these when they add genuine value. Most records won't need them.
|
||||
|
||||
- **Status** frontmatter (`active | superseded by LR-NNNN`): useful when an
|
||||
earlier understanding turns out to be wrong and is replaced.
|
||||
- **Evidence**: how the user demonstrated the understanding (a question
|
||||
answered, an exercise completed, prior experience cited). Useful when the
|
||||
claim might be revisited.
|
||||
- **Implications**: what this unlocks or rules out for future sessions. Worth
|
||||
recording when non-obvious.
|
||||
|
||||
## Numbering
|
||||
|
||||
Scan `./learning-records/` for the highest existing number and increment by one.
|
||||
|
||||
## When to write a learning record
|
||||
|
||||
Write one when any of these is true:
|
||||
|
||||
1. **The user demonstrated genuine understanding of something non-trivial**: not
|
||||
just exposure, but evidence they can use the concept correctly. This sets a
|
||||
new floor for what to teach next.
|
||||
2. **The user disclosed prior knowledge**: "I already know X." Record it so
|
||||
future sessions don't re-teach it. Also record the _depth_ claimed.
|
||||
3. **A misconception was corrected**: the user previously believed something
|
||||
wrong and now sees why. These are high-value: they predict future stumbling
|
||||
blocks for related topics.
|
||||
4. **The mission shifted in response to learning**: the user discovered they
|
||||
cared about something different than they thought. Cross-link to
|
||||
[[MISSION.md]] and update it.
|
||||
|
||||
### What does _not_ qualify
|
||||
|
||||
- Material that was merely covered. Coverage is not learning. Wait for evidence.
|
||||
- Anything already captured tersely in [[GLOSSARY.md]] as a term definition.
|
||||
Don't duplicate.
|
||||
- Session-by-session activity logs. Learning records are not a journal: they are
|
||||
decision-grade insights.
|
||||
|
||||
## Supersession
|
||||
|
||||
When a later record contradicts an earlier one (the user's understanding
|
||||
deepened or corrected), mark the old record `Status: superseded by LR-NNNN`
|
||||
rather than deleting it. The history of how understanding evolved is itself
|
||||
useful signal.
|
||||
@@ -0,0 +1,47 @@
|
||||
# MISSION.md Format
|
||||
|
||||
`MISSION.md` lives at the workspace root. It captures the _reason_ the user is
|
||||
learning this topic. Every teaching decision (what to teach next, which
|
||||
resources to surface, which exercises to design) should trace back to this
|
||||
document.
|
||||
|
||||
## Template
|
||||
|
||||
```md
|
||||
# Mission: {Topic}
|
||||
|
||||
## Why
|
||||
|
||||
{1-3 sentences. The concrete real-world goal the user is chasing. What changes
|
||||
in their life or work when they have this skill? Avoid abstract framings like
|
||||
"to understand X"; push for the underlying outcome.}
|
||||
|
||||
## Success looks like
|
||||
|
||||
- {A specific, observable thing the user will be able to do}
|
||||
- {Another specific thing}
|
||||
- {…}
|
||||
|
||||
## Constraints
|
||||
|
||||
- {Time, budget, prior commitments, learning preferences, anything that bounds
|
||||
the approach}
|
||||
|
||||
## Out of scope
|
||||
|
||||
- {Adjacent topics the user explicitly does not want to chase right now,
|
||||
protecting the zone of proximal development}
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- **One mission per workspace.** If the user wants to learn two unrelated
|
||||
things, that is two workspaces.
|
||||
- **Concrete over abstract.** "Run a half marathon by October" beats "get
|
||||
fitter." "Ship a Rust CLI to my team" beats "learn Rust."
|
||||
- **Push back on vagueness.** If the user cannot articulate why, interview them
|
||||
before writing anything. A bad mission is worse than no mission.
|
||||
- **Revise when reality shifts.** Missions change. When the user's goal moves,
|
||||
update this file: don't leave a stale mission steering future sessions.
|
||||
- **Keep it short.** If `MISSION.md` runs past a screen, it has stopped being a
|
||||
compass and started being a plan.
|
||||
@@ -0,0 +1,46 @@
|
||||
# RESOURCES.md Format
|
||||
|
||||
`RESOURCES.md` is the curated set of trusted sources for this topic. Knowledge
|
||||
for explainers should be drawn from here, not from parametric guesses. Wisdom
|
||||
comes from the communities listed here.
|
||||
|
||||
## Structure
|
||||
|
||||
```md
|
||||
# {Topic} Resources
|
||||
|
||||
## Knowledge
|
||||
|
||||
- [Book: _The Science and Practice of Strength Training_ by Zatsiorsky & Kraemer](https://example.com)
|
||||
Foundational text on programming and adaptation. Use for: anything to do with
|
||||
periodisation, recovery, intensity zones.
|
||||
- [Article: "How Much Should I Train?" by Greg Nuckols (Stronger By Science)](https://example.com)
|
||||
Evidence-based review of volume landmarks. Use for: weekly set targets per
|
||||
muscle group.
|
||||
|
||||
## Wisdom (Communities)
|
||||
|
||||
- [r/weightroom](https://reddit.com/r/weightroom) High-signal subreddit,
|
||||
moderated against bro-science. Use for: programme critique, plateau
|
||||
troubleshooting.
|
||||
- Local: Tuesday strength class at {gym name} Use for: real-time coaching
|
||||
feedback on lifts.
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- **High-trust only.** Prefer primary sources, recognised experts, peer-reviewed
|
||||
work, and communities with strong moderation. If a resource is marketing
|
||||
dressed as education, leave it out.
|
||||
- **Annotate every entry.** A bare link is useless in three months. Add one
|
||||
line: what it covers and when to reach for it.
|
||||
- **Group by Knowledge / Wisdom.** Mirrors the philosophy in
|
||||
[SKILL.md](./SKILL.md). It is fine for a resource to appear in only one group.
|
||||
- **Surface gaps explicitly.** If no good resource exists for an area the
|
||||
mission needs, write a `## Gaps` section listing what is missing. This drives
|
||||
future search.
|
||||
- **Prune ruthlessly.** A resource that turned out to be wrong, shallow, or
|
||||
off-mission should be removed, not buried. Better five sharp sources than
|
||||
thirty mediocre ones.
|
||||
- **Record community preferences.** If the user has opted out of joining
|
||||
communities, note it here so future sessions don't keep proposing them.
|
||||
@@ -0,0 +1,222 @@
|
||||
---
|
||||
name: teach
|
||||
description: Teach the user a new skill or concept, within this workspace.
|
||||
disable-model-invocation: true
|
||||
argument-hint: 'What would you like to learn about?'
|
||||
---
|
||||
|
||||
The user has asked you to teach them something. This is a stateful request -
|
||||
they intend to learn the topic over multiple sessions.
|
||||
|
||||
## Teaching Workspace
|
||||
|
||||
Treat the current directory as a teaching workspace. The state of their learning
|
||||
is captured in this directory in several files:
|
||||
|
||||
- `MISSION.md`: A document capturing the _reason_ the user is interested in the
|
||||
topic. This should be used to ground all teaching. Use the format in
|
||||
[MISSION-FORMAT.md](./MISSION-FORMAT.md).
|
||||
- `./reference/*.html`: A directory of reference materials. These are the
|
||||
compressed learnings from the lessons - cheat sheets, reference algorithms,
|
||||
syntax, yoga poses, glossaries. They are the raw units of learning. They
|
||||
should be beautiful documents which print out well, and are designed for quick
|
||||
reference.
|
||||
- `RESOURCES.md`: A list of resources which can be explored to ground your
|
||||
teaching in contextual knowledge, or to acquire knowledge and wisdom. Use the
|
||||
format in [RESOURCES-FORMAT.md](./RESOURCES-FORMAT.md).
|
||||
- `./learning-records/*.md`: A directory of learning records, which capture what
|
||||
the user has learned. These are loosely equivalent to architectural decision
|
||||
records in software development - they capture non-obvious lessons and key
|
||||
insights that may need to be revised later, or drive future sessions. These
|
||||
should be used to calculate the zone of proximal development. They are titled
|
||||
`0001-<dash-case-name>.md`, where the number increments each time. Use the
|
||||
format in [LEARNING-RECORD-FORMAT.md](./LEARNING-RECORD-FORMAT.md).
|
||||
- `./lessons/*.html`: A directory of lessons. A **lesson** is a single,
|
||||
self-contained HTML output that teaches one tightly-scoped thing tied to the
|
||||
mission. This is the primary unit of teaching in this workspace.
|
||||
- `./assets/*`: Reusable **components** shared across lessons. See
|
||||
[Assets](#assets).
|
||||
- `NOTES.md`: A scratchpad for you to jot down user preferences, or working
|
||||
notes.
|
||||
|
||||
## Philosophy
|
||||
|
||||
To learn at a deep level, the user needs three things:
|
||||
|
||||
- **Knowledge**, captured from high-quality, high-trust resources
|
||||
- **Skills**, acquired through highly-relevant interactive lessons devised by
|
||||
you, based on the knowledge
|
||||
- **Wisdom**, which comes from interacting with other learners and practitioners
|
||||
|
||||
Before the `RESOURCES.md` is well-populated, your focus should be to find
|
||||
high-quality resources which will help the user acquire knowledge. Never trust
|
||||
your parametric knowledge.
|
||||
|
||||
Some topics may require more skills than knowledge. Learning more about
|
||||
theoretical physics might be more knowledge-based. For yoga, more skills-based.
|
||||
|
||||
### Fluency vs Storage Strength
|
||||
|
||||
You should be careful to split between two types of learning:
|
||||
|
||||
- **Fluency strength**: in-the-moment retrieval of knowledge
|
||||
- **Storage strength**: long-term retention of knowledge
|
||||
|
||||
Fluency can give the user an illusory sense of mastery, but storage strength is
|
||||
the real goal. Try to design lessons which build long-term retention by
|
||||
desirable difficulty:
|
||||
|
||||
- Using retrieval practice (recall from memory)
|
||||
- Spacing (distributing practice over time)
|
||||
- Interleaving (mixing up different but related topics in practice - for skills
|
||||
practice only)
|
||||
|
||||
## Lessons
|
||||
|
||||
A lesson is the main thing you produce: the unit in which knowledge and skills
|
||||
reach the user. Each lesson is one self-contained HTML file, saved to
|
||||
`./lessons/` and titled `0001-<dash-case-name>.html` where the number increments
|
||||
each time.
|
||||
|
||||
A lesson should be **beautiful**, with clean, readable typography and layout,
|
||||
since the user will return to these later to review. Think Tufte.
|
||||
|
||||
The lesson should be short, and completable very quickly. Learners' working
|
||||
memory is very small, and we need to stay within it. But each lesson should give
|
||||
the user a single tangible win that they can build on. It should be directly
|
||||
tied to the mission, and should be in the user's zone of proximal development.
|
||||
|
||||
If possible, open the lesson file for the user by running a CLI command.
|
||||
|
||||
Each lesson should link via HTML anchors to other lessons and reference
|
||||
documents.
|
||||
|
||||
Each lesson should recommend a primary source for the user to read or watch.
|
||||
This should be the most high-quality, high-trust resource you found on the
|
||||
topic.
|
||||
|
||||
Each lesson should contain a reminder to ask followup questions to the agent.
|
||||
The agent is their teacher, and can assist with anything that's unclear.
|
||||
|
||||
## Assets
|
||||
|
||||
Lessons are built from reusable **components**, stored in `./assets/`:
|
||||
stylesheets, quiz widgets, simulators, diagram helpers, and anything else a
|
||||
second lesson could reuse.
|
||||
|
||||
Reuse is the default, not the exception. Before authoring a lesson, read
|
||||
`./assets/` and build from the components already there. When a lesson needs
|
||||
something new and reusable, write it as a component in `./assets/` and link to
|
||||
it; never inline code a future lesson would duplicate.
|
||||
|
||||
A shared stylesheet is the first component every workspace earns: every lesson
|
||||
links it, so the lessons look like one consistent course rather than a pile of
|
||||
one-offs. As the workspace grows, so should the component library.
|
||||
|
||||
## The Mission
|
||||
|
||||
Every lesson should be tied into the mission - the reason that the user is
|
||||
interested in learning about the topic.
|
||||
|
||||
If the user is unclear about the mission, or the `MISSION.md` is not populated,
|
||||
your first job should be to question the user on why they want to learn this.
|
||||
|
||||
Failing to understand the mission will mean knowledge acquisition is not
|
||||
grounded in real-world goals. Lessons will feel too abstract. You will have no
|
||||
way of judging what the user should do next.
|
||||
|
||||
Missions may change as the user develops more skills and knowledge. This is
|
||||
normal - make sure to update the `MISSION.md` and add a learning record to
|
||||
capture the change. Confirm with the user before changing the mission.
|
||||
|
||||
## Zone Of Proximal Development
|
||||
|
||||
Each lesson, the user should always feel as if they are being challenged 'just
|
||||
enough'.
|
||||
|
||||
The user may specify an exact thing they want to learn. If they don't, figure
|
||||
out their zone of proximal development by:
|
||||
|
||||
- Reading their `learning-records`
|
||||
- Figuring out the right thing to teach them based on their mission
|
||||
- Teach the most relevant thing that fits in their zone of proximal development
|
||||
|
||||
## Knowledge
|
||||
|
||||
Lessons should be designed around a skill the user is going to learn. The
|
||||
knowledge in the lesson should be only what's required to acquire that skill.
|
||||
You teach the knowledge first, then get the user to practice the skills via an
|
||||
interactive feedback loop.
|
||||
|
||||
Knowledge should first be gathered from trusted resources. Use `RESOURCES.md` to
|
||||
keep track of them. Lessons should be littered with citations - links to
|
||||
external resources to back up any claim made. This increases the trustworthiness
|
||||
of the lesson.
|
||||
|
||||
For acquiring knowledge, difficulty is the enemy. It eats working memory you
|
||||
need for understanding.
|
||||
|
||||
## Skills
|
||||
|
||||
If knowledge is all about acquisition, skills are about durability and
|
||||
flexibility. Make the knowledge stick.
|
||||
|
||||
For skill acquisition, difficulty is the tool. Effortful retrieval is what
|
||||
builds storage strength. Skills should be taught through interactive lessons.
|
||||
There are several tools at your disposal:
|
||||
|
||||
- Interactive lessons, using quizzes and light in-browser tasks
|
||||
- Lessons which guide the user through a list of real-world steps to take (for
|
||||
instance, yoga poses)
|
||||
|
||||
Each of these should be based on a **feedback loop**, where the user receives
|
||||
feedback on their performance. This feedback loop should be as tight as
|
||||
possible, giving feedback immediately - and ideally automatically.
|
||||
|
||||
For quizzes, each answer should be exactly the same number of words (and
|
||||
characters, if possible). Don't give the user any clues about the answer through
|
||||
formatting.
|
||||
|
||||
## Acquiring Wisdom
|
||||
|
||||
Wisdom comes from true real-world interaction - testing your skills outside the
|
||||
learning environment.
|
||||
|
||||
When the user asks a question that appears to require wisdom, your default
|
||||
posture should be to attempt to answer - but to ultimately delegate to a
|
||||
**community**.
|
||||
|
||||
A community is a place (online or offline) where the user can test their skills
|
||||
in the real world. This might be a forum, a subreddit, a real-world class
|
||||
(budget permitting) or a local interest group.
|
||||
|
||||
You should attempt to find high-reputation communities the user can join. If the
|
||||
user expresses a preference that they don't want to join a community, respect
|
||||
it.
|
||||
|
||||
## Reference Documents
|
||||
|
||||
While creating lessons, you should also create reference documents. Lessons can
|
||||
reference these documents - they are useful for tracking raw units of knowledge
|
||||
useful across lessons.
|
||||
|
||||
Lessons will rarely be revisited later - reference documents will be. They
|
||||
should be the compressed essence of the lesson, in a format designed for quick
|
||||
reference.
|
||||
|
||||
Some learning topics lend themselves to reference:
|
||||
|
||||
- Syntax and code snippets for programming
|
||||
- Algorithms and flowcharts for processes
|
||||
- Yoga poses and sequences for yoga
|
||||
- Exercises and routines for fitness
|
||||
- Glossaries for any topic with its own nomenclature
|
||||
|
||||
Glossaries, in particular, are an essential reference. Once one is created, it
|
||||
should be adhered to in every lesson.
|
||||
|
||||
## `NOTES.md`
|
||||
|
||||
The user will sometimes express preferences of how they want to be taught, or
|
||||
things you should keep in mind. This is the place to record those preferences,
|
||||
so you can refer back to them when designing lessons or working with the user.
|
||||
@@ -0,0 +1,5 @@
|
||||
interface:
|
||||
display_name: 'Teach'
|
||||
short_description: 'Learn a concept in a guided workspace'
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
Reference in New Issue
Block a user