Skip to content

Engineering Skills

Engineering skills teach Codex how to perform repeatable engineering work. They are procedural: they describe how to inspect, plan, edit, verify, and document a class of task.

flowchart TD
  task["Engineering task"] --> skill["Engineering SKILL.md"]
  skill --> references["Required references"]
  skill --> scripts["Optional helper scripts"]
  skill --> checks["Verification checklist"]
  checks --> output["Code, docs, or review output"]

Design Principles

Engineering skills should:

  • be task-specific
  • load only the references needed for the task
  • include deterministic checks where possible
  • tell Codex what artifacts to create or update
  • include docs parity expectations
  • avoid embedding volatile implementation knowledge

Candidate Engineering Skills

Skill Purpose Primary Output
large-change Run the large change workflow inside a repository. Change folder, plan, implementation log
repository-bootstrap Bring a repository into handbook compliance. AGENTS.md, workflow, docs entry points
mkdocs-update Add or reorganize handbook pages safely. Docs pages, nav updates, build verification
docs-parity-review Check whether code or process changes require docs updates. Docs impact report or patches
testing-verification Select and run appropriate verification for a change. Verification plan and command results
code-review Review changes for bugs, regressions, missing tests, and docs gaps. Findings-first review
release-prep Prepare release notes and completion checks. Release checklist and notes

Skill Anatomy

An engineering skill should usually include:

  • trigger conditions
  • required inputs
  • references to read
  • artifact rules
  • verification rules
  • docs parity rules
  • completion criteria

Engineering Skill Lifecycle

stateDiagram-v2
  [*] --> Proposed
  Proposed --> Drafted
  Drafted --> Trial
  Trial --> Active
  Active --> Revised
  Revised --> Active
  Active --> Deprecated
  Deprecated --> [*]

When Not To Use A Skill

Do not create a skill for:

  • one-off decisions
  • rapidly changing implementation details
  • content that belongs in AGENTS.md
  • long-form architecture knowledge
  • prompts that are easier to keep as prompt-library entries

Phase 2 Rule

Phase 2 defines skill architecture and candidates. Actual reusable skills may remain in the handbook until anuva-shared-skills is created.