/ai

Own the cognition, not the substrate

ai owns the model-powered behavior — the part of a product whose core uncertainty or capability comes from a model: model choice and routing, the prompt/context harness, structured outputs, tool and MCP consumption, the agent loop, retrieval behavior, memory, evals, guardrails, and AI-specific cost and observability. It is the intelligence layer of the Build stage — peer of frontend and backend. It references the substrates the cognition runs on rather than re-teaching or overriding them: backend serves, data governs, frontend renders, quality verifies, operate runs.

Implement inside the decision. When compatible upstream artifacts are supplied — a solution-architecture doc, contracts, an NFR budget, a threat model, a handoff.yaml — ai builds against them. When they don't exist (a standalone run), it says so explicitly rather than inventing a contract or threat model to fill the gap.

The faceted router

SKILL.md is a router, not a script. Every request selects the smallest sufficient route: one primary job — the ten below — combined with at most one base surface that reshapes how the job applies to the deployment shape, plus the additive multi-agent overlay when the system is also multi-agent. Read the selected references completely; load two or three at most, never the whole pack. Ten jobs and five surfaces compose across deployment shapes without ever reading all sixteen references at once.

The ten primary jobs

Each job is one reference, read fully only when its route is selected — grounded in named canon, producing a running implementation plus the decision record behind it. This is the whole surface, not a headline slice.

Full router table & invariants: SKILL.md.

Five surface overlays

One base surface, at most, reshapes every job for the deployment shape — the same eval job is bounded differently on an interactive assistant than on an unattended batch pipeline. The multi-agent overlay is additive — it stacks on top of whichever base you picked, never replaces it — and carries a distinct teal identity throughout this page.

The evaluation flagship

Most of the field treats evals as an afterthought; here evals are the completion gate. A route never asserts "it works" from memory — it builds the dataset error-analysis-first, aligns a binary judge against human labels, runs the right suites, and reports pass^k for reliability. This is the distinctive that separates a demo from a system, and it is a first-class job, not a footnote.

# evals are the completion gate, not an afterthought
dataset:     error-analysis-first  # open-code failures → taxonomy
judge:       binary + aligned      # precision/recall vs human labels
method:      Critique-Shadowing    # + jury for high-stakes
suites:      offline · online · regression · safety
reliability: pass^k                # not a single lucky pass
subtract:    decompose the judge   # one axis per call, not one mega-rubric

What makes this different

Two stances set ai apart from the vendor-SDK collections and single-topic skills: it subtracts where the field only adds, and it treats the churning model/price/license layer as a first-class, date-stamped concern rather than frozen trivia.

The universal invariants

Six rules govern every route, whichever references it loads — the behavioral spine, condensed.

• Retrieval-first / anti-stalenessThe flagship stance. The model/SDK/price/spec layer changes monthly; memorized names and numbers are stale. Every model name, price, version, and spec revision is date-stamped and re-verified against the live source before use. Teach the method of staying current; never freeze a volatile fact. Carry volatile_facts into the handoff.
• Implement inside the decisionOwn the cognition, not the boundary / NFR / threat-model decision (→ architecture), the serving substrate (→ backend), the governed pipeline + vector store as dataset (→ data), the chat UI/render (→ frontend), the independent gate (→ quality), the deploy/monitoring platform (→ operate), or deterministic workflows (→ automation). Consume upstream artifacts; when none exist, say so.
• Verify-and-subtract, not just assembleEvery recommendation names what to build, what NOT to build, and what to remove. Prune the harness on each model upgrade; better models need less scaffolding. Cap each pass at 3–5 decisions.
• Evals are the completion gateNot an afterthought. Error-analysis-first; binary judges aligned via precision/recall; offline + online + regression + safety; report pass^k for reliability. Distinct from quality's independent gate — never assert "it works" from memory.
• Cost is an architectural constraintFrom the first line. Design for prompt caching first; order the levers (routing cascade → cache → batch's flat 50% → effort floor); budget tokens (cheaper ≠ less spend). Teach the per-model $ math and the license spread (open ≠ open-source; BSL/SSPL/ELv2/open-core).
• Distinguish facts, decisions, assumptions & proposalsPreserve upstream decisions and user constraints, or flag the conflict explicitly; prefer repository and artifact evidence over generic defaults; state unknowns as TBD rather than inventing a value.

What a pass produces

ai's deliverable is a running behavior plus the decision record behind it, closed on an eval that was run, not asserted. A full pass emits up to four kinds of artifact — the behavior, its eval suite, its guardrails/telemetry, and the fillable checklists that ship in the pack — plus the machine-readable handoff.yaml companion when downstream work is expected. Each records the decision and options, the trade-off accepted (including what was removed), and — for any model/SDK fact — the date it was verified and how to re-verify it.

The handoff seam

ai consumes architecture's artifacts upstream — boundaries, NFR budgets, the threat model, build-vs-buy — and, when downstream build/verify work is expected, emits a compact handoff.yaml beside the running behavior: a routing index into the behavior, eval suite, guardrails, and telemetry, never a copy of them, always carrying volatile_facts. Standalone by default; the companion appears only when a consumer will actually read it.

skill: ai
status: complete
objective: ""   # only required field
artifacts_created: [behavior, evals,
  guardrails, telemetry]
decisions: · assumptions: · constraints:
evaluation: suite run · pass^k reported
volatile_facts: [model, price, ver +
  date + re-verify pointer]
recommended_next: quality · operate
  · backend · frontend · data

Seam discipline. The running behavior and its eval suite are the real deliverables; if a consumer needs more than the index gives, the artifact itself is incomplete — the yaml never grows to compensate. Every volatile model/SDK/price/spec fact leaves date-stamped with a re-verify pointer. Never silently invoke a build skill; name it in recommended_next.

Start here

Install once. It's a plain SKILL.md router — no flags, no config, no scripts — so it activates on natural-language phrasing ("route a cheaper model", "add RAG with citations", "write an eval set", "add a guardrail", "build the agent loop", "instrument token cost") rather than a fixed command.

The same install runs on any Agent Skills host. Codex installs to ${CODEX_HOME:-$HOME/.codex}/skills and triggers with $ai; agents remains a separate cross-agent installation target.