AI Engineering Skills

ai-engineering-skills is the control layer for coding agents. It keeps Claude Code, Codex CLI, and similar agents bounded, verified, and resumable through lightweight workflow gates.

One human sets direction and boundaries; one agent executes inside them.

Start here

Use this repo when a coding task benefits from bounded scope and explicit proof, but is too small for a full PRD. Add durable handoff state only when another session or agent must continue the work.

The default durable loop is:

mini-spec -> scope-freeze -> build-one -> verify-contract -> handoff

That loop helps agents stop wandering, prove what changed, and leave enough state for the next session to continue safely.

When the right route is not obvious, start with ceremony-budget: a short pre-flight that chooses the smallest workflow that still buys back enough attention and safety.

Try it in 60 seconds

Clone the repo:

git clone https://github.com/tmusser/ai-engineering-skills.git
cd ai-engineering-skills

Then choose one install target.

Claude Code:

./install.sh --claude-user --only mini-spec,scope-freeze,build-one,verify-contract,handoff

Codex CLI:

./install.sh --codex-user --only mini-spec,scope-freeze,build-one,verify-contract,handoff

Prompt to give an agent for a durable slice:

Use mini-spec, scope-freeze, build-one, and verify-contract for this bug fix.
Add handoff only if another session must continue.

Or let the agent route first:

Use ceremony-budget first, then run only the smallest safe route.

A durable route can leave a SPEC.md or equivalent contract, a verification record, and a HANDOFF.md when continuation state is actually needed.

Use test-mini as an optional add-on when the slice needs focused deterministic tests.

Use ceremony-budget as an optional front door when you are unsure whether the task is a patch, one slice, a mini workflow, or a fuller guarded route.

Starter set

Recommended starter set:

• mini-spec
• scope-freeze
• build-one
• verify-contract
• handoff

The starter set controls which skills are available. It does not require invoking all five for every task.

thin-plan is recommended when a slice needs more shape, but it is intentionally not part of the absolute starter path.

ceremony-budget is also intentionally outside the absolute starter path. It is an optional router that helps choose whether the starter set is even warranted.

For project-scoped installs, templates, and the raw Python installers, see Claude Code installation and Codex installation.

Those docs cover scripts/install_claude_code.py, scripts/install_codex.py, AI_ENGINEERING_SKILLS_VERSION.json, --dry-run, --backup, --force, --only, --uninstall, and --include-templates.

Agent support

Skills are portable because they are plain Markdown, but validation is strongest where this repo has explicit install and docs coverage.

Complements sandboxing and observability

Runtime tools can help isolate where an agent runs and observe what it does. This repo sits one layer above that: it defines the task contract, scope boundary, verification evidence, and handoff state. Sandbox and observability tools can fit into that runtime layer, but they are not required for this workflow.

ai-engineering-skills is not a replacement for sandboxing, secret scanning, permissions, or runtime isolation. It is a workflow layer that helps agents stay bounded and resumable while those controls handle execution safety.

Durable artifacts

What you can do

Use the smallest route that fits.

Why this exists

AI coding agents are powerful, but sessions still fail for predictable reasons:

• vague requests become plausible but wrong plans
• scope expands quietly
• weak verification gets accepted as completion
• long contexts hide the important constraint
• handoff state disappears between sessions

ai-engineering-skills gives the human and agent shared boundaries, checks, and durable artifacts. It reduces risk, but it does not replace judgment.

This is not just a prompt pack. Skills make behavior repeatable across sessions, templates preserve state, and verification records make claims auditable. See Why skills, not prompts.

Evidence

Proof artifact: this repo is evaluated by agent-workflow-bench, a small standalone benchmark for agent skills, verification artifacts, and fresh-session resumability.

The benchmark asks a narrower question: when an agent completes messy technical work, does it leave enough verified context for another fresh session to trust, audit, and continue it?

Supported claims:

• auditability
• verification discipline
• resumability

Not supported:

• broad pass-rate superiority
• guaranteed correctness
• universal behavior improvement

The Task 7 follow-up suggested the highest-leverage improvement was not heavier skills, but sharper invalidation: compatibility probes, diff guards, and REVIEW_REQUIRED states.

See docs/benchmark-findings.md for the fuller pilot notes.

Skill map

See docs/skill-map.md for the routing diagram, context-pressure layer, failure-mode diagram, and workflow recipes.

The failure mode this avoids

flowchart TD
  A["Vague request"] --> B["Many edits"]
  B --> C["Weak verification"]
  C --> D["Long context"]
  D --> E["Lost saliency"]
  E --> F["Buggy / bloated output"]

  G["Clarified request"] --> H["mini-spec"]
  H --> I["One vertical slice"]
  I --> J["scope-freeze"]
  J --> K["build-one"]
  K --> L["verify-contract"]
  L --> M["handoff"]
  M --> N["fresh context"]

This is the shape the repo is trying to prevent. For the full routing map, see docs/skill-map.md.

How this is different

• Raw prompting gives instructions. This repo leaves durable artifacts.
• Plan Mode approves a plan. This repo adds earlier and later gates.
• Chat scrollback disappears. Files survive the session.

Common objections

Isn't this just better prompting?

Better prompts help, but the artifact trail is the leverage: specs, scope boundaries, verification records, and handoff notes.

Is this process theater?

It can be if you use too much of it. Use ceremony-budget when the route is unclear, use the durable starter for bounded work that needs artifacts, and skip the workflow for tiny reversible edits.

Will agents ignore the skills?

Sometimes. Skills do not make agents obey. They make expected behavior explicit, inspectable, and easier to correct when the agent drifts. See Limitations for the honest failure modes.

Context-pressure control layer

Four skills form the backbone for resilient agent sessions:

• scope-freeze — limits blast radius before work
• verify-contract — records evidence after work
• context-check — detects drift during work
• handoff — preserves durable state between sessions

Together they support bounded execution and verifiable progress.

lean-mode is optional. It changes communication density, not the project workflow. Use it when token budget matters, then switch back to full reasoning when ambiguity, safety, or trade-offs require more explanation.

context-check is an optional passive guardrail. It watches for drift, compaction pressure, and active-mode loss, then recommends the smallest corrective action.

For scheduled or delegated tool-using runs, see Agent-worker safety before giving a workflow write access.

Workflow recipes

See docs/recipes.md for the small-project, debug, ML/dashboard, analytical, and cross-functional recipes.

For the routing logic behind those recipes, see docs/ceremony-budget.md.

For an isolated git worktree task, see docs/worktree-agent-run.md.

Ceremony ladder

Use the smallest workflow that still feels safe.

ceremony-budget is the optional entry move before this ladder. It replaces a larger route and should usually output no block when the route is already explicit.

Level 0 — Patch

Tiny reversible edit. Run one sanity check. Record the result.

Level 1 — Micro

One bounded slice. inline boundary -> build-one -> targeted verify -> stop.

Level 2 — Mini

Small vertical slice. compact mini-spec -> build-one -> targeted test -> verify-contract -> stop.

Analytical deliverables such as sizing memos or scenario tables often fit Level 2.

Level 3 — Full

User-facing, scheduled, autonomous, decision-impacting, data-sensitive, or multi-slice work. grill-with-docs-lite -> mini-spec -> checklist-mini -> thin-plan -> scope-freeze -> analyze-mini -> build-one -> test-mini -> verify-contract -> ship-mini. Add handoff when another session or agent must continue.

Below Level 0 — Prompt primitives

Some tasks do not need a skill, artifact, or workflow gate. For quick steering moves like “Find the lie,” “Smallest safe diff,” or “Test the tests,” use prompt primitives instead. See docs/recipes.md#prompt-primitives.

Optional bundles

Use the smallest bundle that fits. Installing a bundle does not require invoking every included skill. See docs/bundles.md for copy-paste install sets for starter, bugfix, ML/data science, dashboard, agent-worker, and full governance workflows.

Demo

This sanitized terminal demo shows a bounded cycle using fake data and simulated agent output. It is generated from demo/demo.tape using VHS, so it is reproducible without private code, private data, or API calls.

Render it locally with:

scripts/render_demo.sh

Further reading

• Slash-style usage: see the install docs and skill command examples.
• anti-patterns: each skill documents common failure modes to avoid.
• Loop governance: see docs/loop-governance.md.
• Cross-functional infrastructure coordination: see docs/recipes.md.

Status

This is a practical workflow pack, not a guarantee that agents will behave. The best results still come from a human who can set boundaries, inspect evidence, and decide when to escalate ceremony.

The benchmark evidence supports auditability, verification discipline, and resumability. It does not show broad pass-rate superiority, and ceremony-budget should not be read as "always do more process." The point is to know when not to use the heavier parts of this repo.