reference

Reference shape for a Crumbtrail archetype skill

Every archetype skill in this plugin uses the five sections below, in this order. The gate at plugins/__tests__/skills.test.ts checks that they are all present, and checks every tool name and parameter name against the live MCP tool table. Copy this file, keep the headings, replace the content.

The worked example running through it is deliberately plain: a user reports that an action in the app failed, and nobody knows yet which archetype it is. That is the state every real skill starts from.

Symptom

State what the reporter or the failing test actually saw, in their words rather than in a diagnosis. One or two sentences.

For the worked example: a user completed an action, the page reported success, and the effect never appeared.

Do not write a cause here. The point of an archetype skill is that several causes produce the same symptom, and the call sequence is what separates them.

What Crumbtrail can see

Name the signals a recorded session actually carries for this archetype, and name the ones it does not. Being explicit about the second list is the whole value of the section. A skill that implies a signal exists sends the agent to run a query that answers nothing, which costs a turn and teaches it a wrong picture of the product.

For the worked example, a session carries console errors and unhandled rejections, every request and response with status and timing, navigation, storage and cookie changes, backend spans where the backend SDK is installed, and database row changes where the database adapter is installed.

It does not carry a stack trace for code that never threw, and it does not carry the value of a variable that was never logged or sent. When an archetype turns on something in that second category, say so in this section and say what the closest available proxy is.

Call sequence

Give the calls as json fenced blocks holding either one object or an array of objects, each shaped {"tool": ..., "params": {...}}. Use real parameter names. The gate rejects a parameter the tool does not accept and rejects a call missing a required parameter, so a sequence that passes the gate is a sequence that will at least dispatch.