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>
223 lines
9.3 KiB
Markdown
223 lines
9.3 KiB
Markdown
---
|
|
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.
|