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.

Quickstart · Documentation ·
Examples · Evidence ·
Contributing

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.

If you want recurring personal defaults, operator-profile is an optional setup
skill for ceremony, autonomy, verification depth, communication density, and
ambiguity handling. It is not a workflow stage, and its preferences cannot weaken
task contracts, repository rules, permissions, or required proof.

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.

If you want the agent to choose a route, install the optional router first
(from this clone, using your chosen target):

./install.sh --claude-user --only ceremony-budget
# For Codex CLI, use --codex-user instead of --claude-user.

Then ask:

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 in GitHub Actions

Publish workflow state and PR evidence without copying the AES reporting scripts
into the consuming repository:

- name: Check out repository
  uses: actions/checkout@v4
  with:
    fetch-depth: 0

- name: Publish AI Engineering Skills evidence
  if: always()
  uses: tmusser/ai-engineering-skills@main
  with:
    base: ${{ github.event.pull_request.base.sha }}

The reusable Action is reporting-only: it exposes existing workflow evidence in
GitHub Step Summary without turning FAIL or REVIEW_REQUIRED into success and
without running enforcement gates implicitly. See
Reusable GitHub Action.

Starter set

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.

operator-profile is setup-only and intentionally outside workflow bundles. Use
it when you want the same installed skills to honor recurring preferences without
forking their contracts. See Operator Profile.

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 cost-sensitive work on capable small models, opt into
eco-mode: budget selected context without reducing
verification. See the eco guide for usage and limitations.

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

Higher-risk or multi-slice work may need more explicit planning, scope, and
verification. Select stages using the routing guide;
this level is not a requirement to invoke every installed skill.

Use analyze-mini only when a current trigger warrants deeper analysis, and
ship-mini only before a material activation boundary such as shared-state
writes, scheduled execution, or expanded permissions. 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

Command-line tools

The clone also includes deterministic checks and evidence tools, accessible
through one dispatcher:

python scripts/aes.py --help
python scripts/aes.py doctor --help
python scripts/aes.py verify --help

See the CLI reference for commands, exit-code contracts,
and working-directory behavior. Installing skills does not install the CLI on
PATH.

Further reading

• Slash-style usage: Claude Code and
  Codex CLI; each skill lists its anti-patterns.
• Loop governance: diagnose repeated failed attempts.
• Cross-functional infrastructure coordination: a worked example.
• Documentation index: installation, routing, checks, and examples.
• Limitations: known failure modes and claim boundaries.
• Contributing: local checks and change expectations.
• Changelog and release notes.

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.