Agent-Skills: Instructions file for Codex

agent-skills Agent Guide

Agent Skills Kit is the canonical control plane for authoring, validating, discovering, and syncing Codex skills, operator docs, and agent workflows.

Root Essentials

• On a fresh checkout, run bash scripts/bootstrap-ask.sh --json before requiring ./bin/ask; if the wrapper is unavailable, verify the fallback with python3 bin/ask repo status --json.
• Use ./bin/ask for repo operations; it forwards to Infrastructure/bin/ask.
• The repository root has no package manager install step. Use repo wrappers at the root, and use package commands only inside verified package roots.
• Inspect YAML through the managed wrapper lane, not ad hoc system Python: ./bin/ask repo yaml-inspect <repo-relative-yaml> --json --robot or mise run yaml-inspect -- <repo-relative-yaml>. Plain python3 is not a PyYAML contract for this repo.
• Run Infrastructure Python tests through the locked Infrastructure environment, not the system Python from the repo root. Use bash Infrastructure/scripts/run-infrastructure-python.sh -m unittest tests.<module> or bash Infrastructure/scripts/run-infrastructure-python.sh -m pytest <path> so dependencies from Infrastructure/uv.lock are available.
• Before changing skills, sync policy, runtime projections, or agent-facing docs, read UBIQUITOUS_LANGUAGE.md.
• Before changing Skills SDK plans, specs, atlas visuals, capability claims, or product-direction docs, use the product-boundary terms in UBIQUITOUS_LANGUAGE.md: /Users/jamiecraik/dev/skills-foundry is the source-only Foundry for retained packages; agent-skills implements and dogfoods the Skills SDK and owns active SDK candidates; Tessl is distribution and external proof; and local runtime truth is a separate installed-behavior lane. A package's explicit owner decision—not a runtime path—decides its canonical source.
• For a package selecting skills-sdk.gold-standard.v1, read Skills SDK Authoring Contract, update references/contract.yaml: authoring_contract with the skill, and run ./bin/ask skills package verify <skill-path> --json --robot. That is a structural admission gate only: run the declared behavioral proof and the selected runtime or external lane before claiming the skill is ready.
• Edit canonical sources, not runtime projections. See Path Ownership Boundaries.
• Finish the named outcome through the smallest local change and focused proof. Feedback is diagnostic evidence, not automatic authority to stop delivery or add process. Select the High-Signal Steering Feedback only for its named conditions. Routine delivery does not require a steering ledger entry or new process artifact. When that route is selected, opening and reading it in the current turn is required; record the result in .harness/quality/steering-uptake.md and run python3 Infrastructure/scripts/validation-and-linting/validate_steering_uptake.py --json.
• Keep runtime handles candidate-bound: wait, poll, or resume only the active handle returned by the immediately preceding tool result, and perform those operations serially for that handle. See High-Signal Steering Feedback for recovery rules.
• Skills SDK PM thread coordination: when Jamie designates one thread as the Skills SDK PM decision surface, use PM Thread Coordination.
• Keep local, runtime, cloud, Tessl, and release proof separate. Use Tessl Live Skill Eval Workflow and Skills SDK Runtime Lane Contract only when those lanes are selected.