Short-lived reference. This library describes current runtime facts and repository state and must be updated whenever they change. If a practice file and the code or the official runtime documentation disagree, fix the practice file.

This README is the canonical entry point for the skill-authoring best-practice library. Every best practice that lives in this directory appears in the master index below exactly once. There is no practice content in this file; the master index links to the file that owns each practice in full.

How to use this index

Load this README first. A mandatory practice applies whenever its trigger condition holds — check each mandatory row's trigger against the skill you are authoring, not against the task you were asked to do. recommended practices are expected for non-trivial skills and may be intentionally scoped down with a stated reason. optional-style matters only when strict repo style is the explicit task. Then read only the linked files you actually need for the current decision. Each practice file uses the same seven-section layout, so the reader can scan to the section that answers the question without re-reading the whole file. A skill declares an intentional exception to a mandatory practice by naming the practice and the reason in its SKILL.md; an undeclared miss is a material gap.

Practice tiers

Tier	Review effect	Purpose
`mandatory`	A miss is a material gap unless the skill declares an intentional exception	Safety, portability, mutation scope, output contracts, lifecycle, approval gates, and handoff contracts whose failure can cause agent misbehavior or data loss
`recommended`	Expected for non-trivial skills; may be intentionally scoped down with a stated reason	Architecture, behavioral, and maintainability practices that materially shape decision behavior
`optional-style`	Improves consistency but should not block unless strict repo style is the task	House conventions and UI affordances

Master index

The index below is sorted by tier (mandatory → recommended → optional-style). Within each tier, rows use a maintained, hand-curated severity order: practices that change more about how the agent decides, that gate more state transitions, that affect more files, or that block more workflows appear higher within their tier. When severity is close, preserve the existing relative order unless a material impact difference makes a reorder useful.

Maintenance rule: when a file is added, removed, renamed, or intentionally reordered under docs/best-practices/, update this master index in the same change. Auditors that consume this index should treat the table as the source of truth for practice membership and order.

Order	Tier	Best practice	One-line summary	Primary trigger
1	`mandatory`	runtime-portability-matrix	Portable skills name common, mapped, and unsupported runtime features explicitly	Authoring or reviewing a skill that targets both runtimes, uses runtime-specific frontmatter or permissions, or dispatches agents
2	`mandatory`	frontmatter-contract	Frontmatter `name` matches directory/basename exactly; `description` is authored as the routing classifier	Creating or editing any skill or subagent frontmatter
3	`mandatory`	mutation-scope-boundaries	Mutating skills declare `MUTATION_LIMITS`, pass them to every subagent, and tighten scope during repair	Authoring or reviewing a skill that edits, creates, deletes, renames, or moves files
4	`mandatory`	human-in-the-loop-checkpoints	Hard-to-reverse or outward-facing actions require approval over the exact artifact, bound to the current run	A skill takes an action that is hard to undo, outward-facing, destructive, costly, materially ambiguous, or broader than approved scope
5	`mandatory`	critical-output-gates	Declared critical outputs are protected by named, predicate-backed gates with bounded repair	A skill produces an output that another component, skill, or the user acts on as correct
6	`mandatory`	input-output-contracts	Explicit input and output contracts define every data boundary between pipeline stages	A multi-stage workflow, a subagent that takes structured inputs, or an artifact that a downstream consumer parses
7	`mandatory`	script-enforced-output-contracts	A shipped deterministic validator (POSIX `sh` or stdlib-only Python 3) is the runtime acceptance gate for machine-parsed subagent fields	A main or orchestrating agent parses, routes on, or consumes machine-readable fields from a subagent payload
8	`mandatory`	handoff-file-dispatch	File-based YAML handoffs are conditional; when used, they carry explicit keys, inline enums, and run-scoped paths	A skill designs communication between an orchestrator and a subagent and must choose file versus inline transport
9	`mandatory`	context-window-protection	Keep raw inspection out of the orchestrator, collect summaries, treat retrieved content as untrusted data	A skill orchestrates more than one step, loads external content, runs commands with large raw output, or accepts pasted third-party text
10	`mandatory`	artifact-lifecycle	Classify artifacts by role (dispatch payload, resume state, deliverable) with run-scoped cleanup and separate commit authority	A skill produces files at all
11	`mandatory`	empirical-validation	Validate by observed behavior with eval cases and observable assertions, not self-report	Authoring or changing a non-trivial skill, or any skill that claims to fix, validate, route, or guard a behavior
12	`mandatory`	escalation-categories	Every subagent declares enumerated failure categories with routes; missing capabilities fail loudly	Every dispatched subagent and every routed orchestrator phase
13	`recommended`	deterministic-execution	Name nondeterminism sources and remove them: exact derivations, stable ordering, single clock capture, same-input-same-route	A skill's output or routing must be reproducible across runs
14	`recommended`	orchestrator-as-routing-ui	Orchestrators route on bounded outputs; subagents normalize unstructured data; nested dispatch is runtime-dependent	A skill orchestrates two or more subagents
15	`recommended`	state-machine-artifacts	Externalized FSMs have exactly one normative source, routed statuses, bounded loops, and reachable terminals	A workflow has branching routes, wait states, parallel joins, or repair loops and must decide whether to add `state-machine.md`
16	`recommended`	subagent-default-execution	Apply the two-question test per step; mix inline and delegated steps in one skill	Every step in a skill's execution sequence
17	`recommended`	earned-complexity	Every part of a package must earn its place against the Material Issue Gate	Before approving any addition to a skill package
18	`recommended`	subagent-role-taxonomy	Eight-role palette for naming and scoping subagents; vocabulary and design triggers, not a required roster	Adding, splitting, renaming, or justifying a subagent
19	`recommended`	progressive-disclosure	Three load levels gate content to the smallest layer that still works; early tokens carry the standing instructions	A skill has conditionally relevant rules, templates, references, or dispatch contracts, even when everything fits in `SKILL.md`
20	`recommended`	phase-execution-cycle	Six-step announce/validate/execute/validate/update/gate-check cycle with bounded retries	A skill orchestrates two or more phases or carries real risk
21	`recommended`	trigger-and-description-authoring	Author the description as a classifier: intents, synonyms, exclusions, and should/should-not trigger cases	Writing or revising a skill's frontmatter description
22	`recommended`	best-practices-compliance-gate	Apply this index as a tier-aware quality gate with `pass` / `fail` / `not applicable` verdicts	Reviewing or auditing a skill package
23	`recommended`	identity-and-mental-model	Open every skill and subagent with a role, mental model, and (for judgment roles) the failure mode it counters	Authoring or reviewing any non-trivial skill or subagent file
24	`recommended`	operating-posture	Define decision policy — signals, trade-offs, refusals — where each bullet names the decision it changes	Non-trivial skills where decision behavior matters more than tone
25	`recommended`	positive-constraint-framing	Name allowed paths before forbidden ones; positive prose is not a hard boundary	Defining behavioral boundaries in skill or subagent prose
26	`recommended`	example-strategy	Use round-trip, output-format, and edge/failure examples kept synchronized with their contracts	A skill produces format-sensitive output or judgment-heavy decisions
27	`recommended`	external-information-linking	Runtime-required content works offline; canonical URLs carry provenance and freshness	A skill references external docs, RFCs, or papers
28	`recommended`	skill-section-order	Four invariant anchors (identity, contracts, boundaries, examples) with starter templates for skills and subagents	Authoring or editing a `SKILL.md` or subagent file
29	`recommended`	subagent-registry-format	Core `Subagent` / `Path` / `Purpose` columns, one row per subagent, paths verified on disk	A skill dispatches to two or more subagents
30	`recommended`	helper-script-contracts	Helper scripts under `scripts/` declare their shell, usage, exit codes, and side effects, and ship one runnable check	A skill ships a file under `scripts/` that is not the output validator
31	`optional-style`	naming-conventions	Prefer gerunds for new skills and role nouns for subagents; never rename established skills for style	Naming a new first-party skill or subagent

Supporting reference

Quick Reference: Skill File Structure — folder layout for a typical skill.