Skillet Authoring

Run every Skillet command through the current package: npx -y @sentry/skillet@latest, or pnpx @sentry/skillet@latest in a pnpm environment. Never prefer a bare skillet executable from PATH; if one reports an update, rerun that command through the explicit latest package before continuing. Treat spec.md as the behavior contract, SKILL.md as the agent instructions, and eval cases as repeatable runs of the spec scenarios. Never write these files from a remembered format.

Steps

1. Run npx -y @sentry/skillet@latest status <dir> --json and do what next says. For a brand-new skill, run npx -y @sentry/skillet@latest new <name> first. Never guess a skill's state or start over when artifacts already exist.
   • When status reports uppercase SPEC.md, preserve or rename that legacy document before creating lowercase spec.md; never parse it as the active Skillet spec.
   • When status marks lowercase spec.md invalid, preserve or rename legacy content and derive a valid Skillet spec before rendering SKILL.md or adding coverage.
2. When migrating, inventory behavior-bearing material before drafting: triggers, ordered workflow, exact lists, protocols and output formats, thresholds, failure and stop rules, constraints, runtime references, and maintenance docs that describe active behavior. Every accepted behavioral rule must land in spec.md; verbose execution detail may additionally remain in a linked runtime reference after the spec defines the observable contract. Explicitly supersede or reject non-behavior content.
3. When spec.md is next, fetch npx -y @sentry/skillet@latest instructions spec <dir> --json. If intent remains ambiguous after inspecting the available evidence, ask 2–4 pointed questions before writing. Then write the spec with the served Skillet version footer as its final non-empty line, run npx -y @sentry/skillet@latest validate <dir>, and fix every spec error before deriving anything.
4. When SKILL.md is next, fetch npx -y @sentry/skillet@latest instructions skill <dir> --json and render it from the validated spec. When migrating, do not weaken exact formats, enumerations, thresholds, delegation rules, or stop conditions. Move long protocols to references/ when useful, link them from SKILL.md, then compare the old and new runtime surfaces and account for every removed rule. Search README and provenance docs for stale artifact paths, prompt locations, runtime-section claims, frontmatter descriptions, and coverage claims. Validate again before adding evals.
5. When eval coverage is next, fetch npx -y @sentry/skillet@latest instructions evals <dir> --json, add at least one case per behavior, then validate with the same package command until no errors or uncovered-behavior warnings remain.
6. Run npx -y @sentry/skillet@latest eval <dir> --dry to find checks that pass before the agent runs. Then run npx -y @sentry/skillet@latest eval <dir> --baseline to compare the tested results with and without the skill. Add --trials <n> only when repeated observations are useful, and --report <file> when the user wants a shareable run artifact (npx vitest-evals serve <file> renders it).

When evals fail

Classify the failure before editing anything, then fix at that layer only:

• Wrong intent — the spec asks for the wrong thing: fix spec.md, then re-render SKILL.md.
• Weak wording — SKILL.md expresses the behavior ambiguously: tighten SKILL.md, leave the eval case untouched.
• Unfair eval — the case punishes a legitimately better outcome: fix the case and say explicitly why it was unfair.

Never delete or loosen an eval case just to get to green.

Never

• Never report a skill as done while npx -y @sentry/skillet@latest validate reports errors.
• Never scaffold or modify skill artifacts when the user only asked a question or an unrelated task.