skill-package

Capability: skill package

The artifact is a whole skill directory — SKILL.md plus references/, scripts/ and assets/ — and all of it is editable: materialize() exposes every file as a component, apply() can rewrite or CREATE one (a new bundled script included), and validate() checks the result against the skill-creator authoring rules (first-party sources in references/concepts.md).

What you can change (highest leverage first)

Pick the lever that fixes the biggest failure cluster; depth is in the references.

1. The description / trigger — the only text loaded before the skill fires, so the single highest-leverage edit. Third person; state what it does AND when to use it; use the keywords a user would actually say. Lean slightly pushy for under-trigger, tighten the boundary and name near-miss cases for over-trigger, and front-load the key use case (hosts truncate the listing — 1,536 chars on Claude Code by default). Ex: "Formats data" → "Exports records to CSV. Use when the user asks to export or download a table." Playbook + the measurable loop: references/description-optimization.md.
2. A skipped step → a bundled script (the determinism lever). Prose is only likely to be followed; code that runs is repeatable. When the traces show the agent skipping a step, re-deriving the same helper, or doing a deterministic transform by hand, write it into scripts/ and make the body invoke it by command line. Write real, working code — never ... or a docstring-only stub — give it a --self-check entry point (validate() runs it, so a broken script is caught before any rollout is paid for), and say execute, don't read: a script's source never enters the agent's context, only its output.
3. The body — improve clarity and altitude, delete dead weight, fix the instruction the agent misreads. The body loads on every trigger and stays in context all session — a recurring cost — so keep it ≤500 lines (enforced), imperative, and explain a rule's why briefly instead of piling on ALL-CAPS MUSTs.
4. References — move mutually-exclusive or rarely-co-used detail into references/*.md. Keep them one level deep (a ref must not point at another ref — the agent may read only part of it), link each directly from SKILL.md with a pointer saying what it holds and when to load it, and give a long ref (>300 lines) a table of contents at the very top, above any orientation prose — the check is positional because a TOC the head-reader never reaches is not a TOC. Multiple variants/domains → one ref per variant (references/aws.md, gcp.md, …) plus a selection body, so only one is read.
5. Assets — assets/ holds files the skill emits (templates, icons, fonts), not context the agent reads. Edit one only when the skill's output depends on it.