Matt PocockandClaude Opus 4.8
17f22a371b
The reference now covers any document an agent consumes — skills, AGENTS.md/CLAUDE.md, docs reached by a pointer. GLOSSARY.md merged into SKILL.md as a dedup (Avoid-lists and the standalone Predictability definition pruned); skill-only mechanics disclosed to SKILL-MECHANICS.md; the skill is now model-invoked. Clean rename, no alias. Spec: mattpocock/personal-wiki#187 · ships via mattpocock/personal-wiki#193 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2.6 KiB
Skill mechanics
The skill-specific branch of writing-for-agents: what changes when the document is a skill — frontmatter, the invocation choice, and router skills. Everything else about writing it is the universal reference in SKILL.md.
Invocation
Two choices, trading the two loads:
- A model-invoked skill keeps a
description, so the agent can fire it autonomously — and other skills can reach it. You can still type its name: model-invocation always includes user reach; a description only ever adds agent discovery, never removes the human's. The description is the skill's top-level context pointer, forced to stay loaded at all times — permanent context load in exchange for discoverability. A model-invoked skill whose content is all reference is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Mechanics: omitdisable-model-invocation, and write a model-facing description carrying the trigger branches (the pointer-writing rules inSKILL.mdapply in full). - A user-invoked skill strips the description from the agent's reach: only the human typing its name can invoke it, and no other skill can. Zero context load, but it spends cognitive load — you are the index that must remember it exists. Mechanics: set
disable-model-invocation: true; thedescriptionbecomes human-facing — a one-line summary, trigger lists stripped.
Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
Shared reference that two user-invoked skills both need can live in neither — with no descriptions, neither can fire the other. Push it to a plain file outside the skill system: external reference any skill can point at.
Splitting by invocation
The invocation cut of splitting (the sequence cut lives in SKILL.md): split off a model-invoked skill when you have a distinct leading word that should trigger it on its own — a trigger word you actually use in your prompts — or another skill must reach it. You pay context load for the new always-loaded description, so that independent reach has to be worth it.
Router skills
When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a router skill: one user-invoked skill that names the others and when to reach for each, so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no description, so nothing but the human can reach them.