Cathryn Lavery
dbc4abd965
- SKILL.md: confirm type/pattern/size/cuts with the user before rendering; checklist hooks for the checkpoint and the packaged self-check - scripts/verify-docs-sync.py: CI now fails when the frontmatter description loses a type's lexical hook, the gallery can't reach a shipped example, or the README tree names a missing file - skills/diagram-design/scripts/self_check.py: distilled output checker that ships with the skill so installed agents can verify their own diagrams; adversarial suite in scripts/test-self-check.py - assets/index.html: six new tabs (OAuth sequence + five single-variant examples with a data-single variant lock) so every shipped example is browsable - docs/adr/0001-0004: settled policies recorded (pinned controller, taxonomy freeze, reveal-only autoplay, byte cap + trigger-rich description) - README: It's-working-if section, new gates documented; CONTRIBUTING: gate table, ADR guidance, type-addition invariants; CI: two new steps
1.3 KiB
1.3 KiB
ADR 0004 — SKILL.md byte cap and the trigger-rich description
Status: accepted (v2.3, cap raised after review)
Context
SKILL.md loads into an agent's context on every skill invocation, so it must stay lean; a byte cap keeps growth honest. But v2.3 initially set the cap at 35,000 bytes and slimmed the frontmatter description to fit — deleting all 27 type names. The description is the only text an agent sees before deciding to load the skill: removing "flowchart", "Gantt", "org chart" from it removes the lexical hooks that make "make me a flowchart" invoke the skill at all.
Decision
Two rules, in priority order:
- The frontmatter
descriptionmust name every visual type in the selection table (enforced byscripts/verify-docs-sync.py) plus the import formats and major feature vocabulary. Routing surface is never traded for body prose. MAX_SKILL_BYTESis 40,000 (enforced byscripts/verify-semantic-motion.py). When the file approaches the cap, cut body prose or move detail intoreferences/— never the description.
Consequences
- Adding a visual type requires touching the description; CI fails otherwise, by design.
- The cap is measured on raw bytes with
core.autocrlf=falsepinned in CI checkout; Windows contributors should keep LF endings forSKILL.md.