Claude CodeLesson
Claude Code Skills
A procedure written into CLAUDE.md costs every session its full length, even the sessions that never do that job. A Skill moves the procedure into its own folder. A session sees one line about it, and reads the rest only when the job comes up.
Know Skills already? Skip to In Terrarium.
Outside the box · General
The concept
A Skill is a folder holding a SKILL.md file: YAML frontmatter, then the instructions in Markdown. A project's Skills live in .claude/skills/<name>/ and are committed, so everyone who clones the project has them. The folder can hold other files too, such as a longer reference or a script, which the instructions point to.
---
name: release-notes
description: Write release notes. Use when asked for a changelog.
---
1. List the PRs merged since the last tag.
2. …
name defaults to the folder's name. description is what Claude reads to decide when the Skill applies, and it stays in context all session. The rest of the file loads only when the Skill runs: because Claude judged it relevant, or because you typed /release-notes. Once loaded, the instructions stay in the conversation for later turns. Claude Code doesn't read the file again, so write them as standing instructions, not as steps to do once.
Two fields decide who may start a Skill. disable-model-invocation: true means only you can: Claude can't start it on its own, and its description leaves the context. The docs suggest it for jobs with side effects, or jobs whose timing you want to control, like a deploy. user-invocable: false is the reverse: only Claude can start it, and it is hidden from the / menu.
Full referenceClaude Code docs: Extend Claude with skills
In Terrarium
Terrarium's are committed in .agents/skills/, one folder each. .claude/skills/ holds only a link to each folder, which Claude Code follows to find the Skill. A Skill is Platform code: it changes through a gated PR like any other code.
A Skill reads as a goal and numbered steps. close-session, which a session runs at Session closure, opens like this:
6You've reached **Session closure**. Goal: the Journal holds an honest log of
7this session, with its final status.
8
91. **Check this session against CLAUDE.md and the always-loaded rules** (already
10 in your context; do not reopen the files). For every rule or step in them that
11 this session broke or skipped, log a Friction that names the rule, even if you
12 fixed it later. Say what impact breaking it had or could have had, and what
13 would have made you read it at the time.
Each Skill makes the invocation choice in its frontmatter. A Skill that sessions must reach on their own, such as close-session, code-review or dispatch-subagents, keeps a description that spells out its triggers and sets no disable-model-invocation. A Skill that a person or a starts turns model invocation off, and its description shrinks to a one-line summary for people. Glass Box's own Lesson-writing Skill is one:
1---
2name: glassbox-lesson
3description: Write one Glass Box Lesson, a page about one concept with Terrarium as the worked example.
4disable-model-invocation: true
5---
The test comes from the outside pack's .agents/skills/writing-for-agents/SKILL-MECHANICS.md, part of the Skill that ADR-0005 (docs/adr/0005-skill-model.md) names as how to write one: a Skill keeps model invocation only when the agent must reach it on its own, or another Skill must; one that only ever starts by hand turns it off. Scheduled tasks shows what a scheduled Skill says about its timer.
Skills from an outside pack (a set of ready-made Skills installed from another repository) sit beside Terrarium's own, kept exactly as installed (Skill packs). The Journal keeps one entry per Skill in use, its . An entry's importance and role are the Inventory's own judgement, which the Skill Inventory page shows.
Why it's built this way
- Committed Skills. Cloud and scheduled sessions start from a fresh clone, so a Skill in someone's personal folder isn't there. Committing Skills fixes that and puts them in review with the code they change. The cost: every edit, even one word, is a PR that passes the Gate. ADR-0005 (docs/adr/0005-skill-model.md).
- Schedule apart from steps. The Skill holds what a scheduled run does; a outside the repo holds when it runs. A schedule changes without a PR, and the Skill can still be started by hand. The cost: the repo alone doesn't tell you when a Skill runs. ADR-0005 (docs/adr/0005-skill-model.md).
- Who may start it. A description stays in every session's context so Claude can start the Skill itself; turning that off saves space, but a person must remember it. With model invocation off, a job that opens its own PR, such as writing the day's , never starts unasked. .agents/skills/writing-for-agents/SKILL-MECHANICS.md.
What to watch for
- A Skill reads no file, so its rules don't load. Terrarium adds them with a hint: Path-specific rules explains how.
- No Skill can start a user-invoked one. With no description in context, nothing but a person can reach it. Reference that two such Skills share goes in a plain file both point to.
- The description is the whole trigger. A model-invoked Skill fires on its description alone, and a weak one shows up only as a Skill that should have fired and didn't. The audit in the Self-improvement loop looks for that.
- A slash command already pastes the Skill's text. A guard refuses a
Skillcall for a Skill the session received inline (Claude Code hooks); follow the text you already have.
Try it in your project
Find a procedure in your CLAUDE.md that only some sessions follow and move it into .claude/skills/<name>/SKILL.md. Write the description as the triggers, not a summary. Then ask Claude for that job without naming the Skill and check that it fired; if it didn't, add the words you used to the description. If only you will ever start it, add disable-model-invocation: true instead and start it with /<name>.
Where next
- LessonCLAUDE.md
- LessonPath-specific rules
- LessonScheduled tasks
- LessonSelf-improvement loop
- JournalSkill Inventory
Walkthroughs through this Lesson
- WalkthroughAsking an agent for a change
Last updated · Latest source on GitHub ↗