0003 · The Invocation Model

We cross from methodology into authoring craft here. Lesson 02 ended on a teaser: every orchestrating skill in the flow carries disable-model-invocation: true. That single frontmatter line is the most consequential decision you make when authoring a skill, and it turns on one question — who is allowed to invoke this?[wgs]

The root virtue. A skill exists to "wrangle determinism out of a stochastic system." The goal is predictability — the agent taking the same process every run (not producing the same output). Every lever below, invocation included, serves that.[wgs]

Two kinds of skill

Model-invoked

Keeps a description, so the agent can fire it autonomously and other skills can reach it (you can still type its name too). Mechanics: omit disable-model-invocation; write a model-facing description rich in trigger phrasing ("Use when the user wants…, mentions…").

User-invoked

Strips the description from the agent's reach: only you, typing its name, can invoke it — and no other skill can. Mechanics: set disable-model-invocation: true; the description becomes human-facing — a one-line summary, trigger lists stripped.

In the flow from Lesson 02: the orchestrators (grill-with-docs, to-spec, to-tickets, implement) are user-invoked — you walk them. The reusable disciplines beneath (tdd, code-review, domain-modeling) are model-invoked so the orchestrators can reach them. The README states the constraint crisply: a user-invoked skill may invoke model-invoked ones, but never another user-invoked one.[readme]

The choice is a trade between two loads

This is the heart of the lesson. Invocation isn't free either way — each kind spends a different, scarce resource:

Context load — a model-invoked description sits in the context window every turn, whether or not the skill fires. More model-invoked skills = a heavier window all the time.

Cognitive load — a user-invoked skill costs the window nothing, but you become the index that has to remember it exists. More user-invoked skills = more for your own memory to carry.[wgs]

So the rule for choosing: 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.[wgs]

Map this onto your own Pi setup: every model-invoked skill you keep loaded is rent you pay on every turn of every session, even the ones where it never triggers. That's the real cost of a big always-on skill library — and the reason "just make everything model-invoked so I never have to remember" is a trap.

When cognitive load piles up: the router

Push everything to user-invoked to save context load, and eventually you can't remember what you have. That piled-up cognitive load has a specific cure: a router skill — one user-invoked skill that names the others and says when to reach for each.[wgs]

You've already met one. ask-matt from Lesson 02 — "you don't remember every skill, so ask" — is the router over this repo's user-invoked skills. It converts "which of my 15 skills fits this?" (your memory) back into "ask the agent" (the window, but only when you invoke it). The router is how the repo scales past what a human can hold without making every skill pay perpetual context load.[askmatt]

Writing the description (when model-invoked)

A model-invoked description does two jobs: state what the skill is, and list the branches that should trigger it. Every word adds context load, so it earns even harder pruning than the body:[wgs]

Check yourself

A skill only ever fires when you type its name by hand. How should it be invoked?

If it only fires by hand, user-invoked pays no context load. The description becomes human-facing (triggers stripped) — the agent can't reach it, which is the point.

What does a model-invoked skill's description cost, and when?

A model-invoked description sits in the context window every turn, firing or not — that perpetual rent is context load. Cognitive load is the user-invoked cost.

Too many user-invoked skills to remember. What's the prescribed cure?

Piled-up cognitive load is cured by a router (like ask-matt) — it keeps them user-invoked (no context load) but hands the "which one?" job back to the agent.

Primary source

Read the Invocation and Writing the description sections of writing-great-skills/SKILL.md. This file is the textbook for the rest of the authoring arc — Lessons 04–06 all come from it. The README's Reference section states the "never invoke another user-invoked skill" rule.[wgs][readme]

Ask me anything. Good follow-ups: "Which of my Pi skills should flip to user-invoked?" · "Help me draft a description with one-trigger-per-branch" · "Do I need a router yet, or am I not big enough?" Or say next for Lesson 04: the information hierarchy and progressive disclosure — how to decide what lives in SKILL.md and what gets pushed behind a pointer.

The invocation model