A skill is a set of written instructions that your coding agent (Claude Code,
Codex, Cursor and similar tools) follows. An oat command is a program you run
in a terminal; a skill may run oat commands for you. To run a skill, type its
name with a slash in your agent's chat, for example /oat-docs-analyze. Codex
uses $ instead: $oat-docs-analyze. Some guides show arguments or a short
request after the name.
Some skills start only when you type their name; the agent will not choose them
on its own. In the catalog below, these show model disabled: true under
Visibility. Follow a skill's name to its guide, which says whether it needs an
active project (an OAT project already open in this checkout) and what it does
without asking you.
Example. Your docs are stale: several pages describe commands that have
changed. In the catalog, the Docs workflows table
lists oat-docs-analyze. Its guide
says it needs no active project and, without asking, writes a report under
.oat/repo/analysis/ and updates .oat/tracking.json; it does not edit your
pages. Type /oat-docs-analyze, read the report, then run /oat-docs-apply to
make only the changes you approve.
Start a new tracked project: oat-project-new, oat-project-quick-start, oat-project-lite for a single-sitting change with one batched interview and one approval (quick start accepts a project name plus optional description; if you omit the description it should ask before discovery begins), oat-project-brief for one delivery agreed in conversation, or oat-project-goal for an outcome delivered in milestones
Resume an existing project: oat-project-open to select it,
oat-project-progress to see where it stands, then oat-project-next to
continue. See
Resume work on this machine.
Execute a ready plan: oat-project-implement
Import an existing plan: oat-project-import-plan
Split a broad discovery or brainstorm into child projects: oat-project-split
Run or receive reviews: oat-project-review-provide, oat-project-review-receive, or the non-project review variants
Generate an evidence-grounded project retrospective, apply approved repo
improvements, or file tracker feedback: oat-project-retro and
oat-project-retro-file. See
Project Retrospectives.
Capture a scoped, shippable backlog item: oat-pjm-add-backlog-item directly when the work is already scoped, or oat-brainstorm when the thought hasn't converged yet — the brainstorm dispatcher's "scoped backlog item" destination pre-fills the title / description / acceptance criteria / scope estimate / priority from the conversation and then runs oat-pjm-add-backlog-item with confirmed inputs
Manage the repo backlog and reference docs: oat-pjm-update-repo-reference, oat-pjm-review-backlog
Operate an explicit GitHub, Linear, or Jira planning-record binding through a
live host capability: oat-pjm-remote. The OAT CLI retains policy, preview,
approval, journal, and verification authority; the skill discovers and
invokes only the exact host action emitted for one durable operation.
Turn a repo audit, maintainability review, backlog review, backlog directory, or backlog item into standalone external implementation plans: oat-repo-improve. Plans land under .oat/repo/reference/external-plans/; execute them directly or optionally pass one to oat-project-import-plan for tracked OAT execution.
Choose what to delegate and route bounded work by task class across Codex, Claude, or Cursor: subagent-orchestration. It is self-contained and usable without OAT; live catalogs and current instructions take precedence over its dated provider examples.
Build visual project explainers and final project recaps: oat-explainer-kit, backed by the destination-neutral explainer-kit core. See Explainer Kit.
Work on docs surfaces: authoring-docs (general documentation baseline), oat-docs-authoring (targeted OAT/Fumadocs authoring), oat-docs-bootstrap (guided bootstrap of a new docs app), oat-docs-analyze, oat-docs-apply, and oat-project-document
Generate a shipping digest or scheduled recap: oat-wrap-up
Run a wave program over a corpus of external plans: oat-wave-program (durable program artifact: new/refresh/wave-close) and oat-wave-execute (one wave as a wrapper project) — see Wave Workflows
Research a topic in depth: deep-research
Acquire and validate bounded evidence for another workflow: recon
Analyze an artifact, codebase, or document: analyze
Compare options with domain-aware dimensions: compare
Verify a claim adversarially: skeptic
Merge multiple analysis artifacts: synthesize
Capture or refine ideas: oat-idea-new (capture a new idea), oat-idea-ideate (resume an existing tracked idea or expand a scratchpad seed — not for blank-slate brainstorms; use oat-brainstorm for those), oat-idea-scratchpad, oat-idea-summarize
Run a project-independent brainstorming conversation: oat-brainstorm — entry point with an explicit activation contract. Hard Activation fires only on the brainstorm verb ("let's brainstorm", "brainstorm this", "can we brainstorm X", "help me brainstorm X", or /oat-brainstorm); ambiguous exploratory phrasing answers conversationally without the banner and offers structured mode only after sustained exploration. Once entered, runs a structured design conversation (one question at a time, 2-3 approaches with a recommendation) and routes to inline / doc-to-path / idea / backlog item / project handoffs based on installed packs. See Tool Packs for the brainstorm pack details.
Use oat-pjm-remote only for an explicit remote lifecycle request. Its loop is
deliberately narrow:
Before the first provider-contacting command, inspect currently granted MCP
or connector descriptions for a semantic and exact-context match.
If no capable connector is available, inspect an already configured
provider CLI's live help before the first attempt. Do not install a tool,
retain its dialect, or switch execution surfaces mid-attempt.
Construct only bounded provider-neutral capability evidence and pass it to
the requested command with --capability-evidence-stdin. Treat the CLI's
policy, preview, approval, safety, and durable state as authoritative.
When the CLI returns pending with externalAction, execute that exact
semantic action at most once and submit one bounded,
sanitized observation with oat pjm remote operation continue.
Continue only when the CLI emits another exact action for the same durable
operation. Stop on its terminal envelope.
The skill cannot broaden the normalized projection, bypass effective policy,
binding clamps, purpose field grants, hard approval floors, or caller-owned
authority evidence, read credential values, persist native provider data, or
declare remote success. A connector result, process exit, or visible remote
change is only evidence. Success requires an OAT ok envelope after
authoritative read-back.
See Remote Project Management
for policy, storage, approval, and recovery details.
AGENTS.md is the session-facing registry. It should stay aligned with skill frontmatter and the canonical skill directories under .agents/skills/.
Legacy compatibility note: review-backlog and update-repo-reference may still exist in some environments, but prefer the oat-pjm-* family for the current file-backed backlog/reference workflow.
Generated from canonical skill metadata and the reviewed guide mapping. Do not edit this block; run pnpm docs:skills:generate after changing those sources.
Follow a skill name for its invocation, prerequisites, scenario and output. “Needs an active project?” says whether the skill needs an OAT project (a tracked unit of work under .oat/projects/) to be already open in this checkout: “Yes” means it does, “Optional” means it works with or without one, and “No” means it does not need one. Conditional details are in each guide.
Visibility reports source metadata: “user” is user-invocable and “model disabled” is disable-model-invocation. “Not declared” is not an explicit visibility setting.
Run when you need to evaluate agent instruction file coverage, quality, and drift. Produces a severity-rated analysis artifact. Run before oat-agent-instructions-apply to identify what needs improvement.
Run when you have an agent instructions analysis artifact and want to generate or update instruction files. Creates a branch, generates files from templates, and optionally opens a PR.
Use when a user explicitly asks to run an OAT project autonomously end-to-end. Activates session-only autonomy, resumes the correct lifecycle phase, and drives the existing OAT skills through final PR or a reported boundary.
Use when the user requests or confirms adding a new repo backlog item — e.g. "add a backlog item for X", "capture that as backlog", "track that follow-up", "file a backlog ticket", or confirms a previously offered backlog capture. Do NOT auto-invoke when a follow-up is mentioned. Creates the item file in the file-per-item backlog structure, regenerates the index, and prompts for curated overview updates.
Use when the user requests or confirms recording a durable repo decision — e.g. "capture that as a decision", "write an ADR for X", "record this architectural choice", or confirms a previously offered decision capture. Creates a file-per-record decision under reference/decisions/ via `oat decision new` and refreshes the generated decision index. Do NOT auto-invoke for routine choices that do not warrant durable history.
Use when explicitly intaking, publishing, refreshing, reconciling, or continuing an OAT PJM remote binding through a live host capability. Keeps policy, approval, state, and success verdicts in the OAT CLI while the host discovers and invokes currently granted execution capabilities.
Use when prioritizing the file-backed repo backlog or evaluating roadmap alignment. Produces value-effort ratings, dependency mapping, execution recommendations, and an optional external-plan handoff.
Use when repo reference artifacts need updating — roadmap, decision records, backlog status, or completed history. Frequently invoked at project completion, often chained from `oat-project-document`, to ensure active `.oat/repo/pjm/` state and durable `.oat/repo/reference/` records reflect what shipped.
Use when the user explicitly invokes the `brainstorm` verb, including `/oat-brainstorm`, "let's brainstorm", "brainstorm this", "can we brainstorm X", or "help me brainstorm X". For ambiguous exploratory phrasing ("I've been thinking", "what if", "help me think through"), do NOT auto-enter; respond conversationally and offer mode only after ≥2 sustained exploratory turns. Do NOT use for review, debug, PR, status, implementation, or active-workflow questions.
Use when OAT work is mentioned in a Cursor Cloud environment. Orients agents to cloud detection, repo-rooted project homes, user-first assets, CLI availability, and Cursor dispatch context without owning lifecycle execution.
Use when creating, restructuring, migrating, auditing, or reviewing technical documentation for software projects. Provides evidence-first, provider-portable Markdown authoring standards.
Use when a user asks questions about OAT workflows, CLI commands, skill authoring, configuration, or project lifecycle. Answers questions by reading locally-bundled OAT documentation.
Run when you need to evaluate documentation structure, navigation, and coverage against the OAT documentation contract. Produces a severity-rated analysis artifact for oat-docs-apply.
Run when you have a docs analysis artifact and want to generate or update documentation structure and content. Creates a branch, applies approved changes, and optionally opens a PR.
Use when authoring or restructuring targeted content inside an existing OAT Markdown surface or OAT/Fumadocs docs app. Preserves OAT docs navigation, generated indexes, and validation boundaries.
Use when bootstrapping or adopting an OAT documentation surface in a repo. Guides the user through preflight detection, richer input gathering than the raw CLI, `oat docs init` invocation with gated post-patches for open CLI gaps, build verification, post-scaffold config inspection, and an educational walkthrough. Supports plain Markdown (file-level path), Fumadocs (full path), and MkDocs (lean path with defined minimum contract).
Use when continuing an existing tracked idea or expanding an explicit scratchpad seed from {IDEAS_ROOT}/scratchpad.md. Do NOT use to start a brand-new, destinationless brainstorm; use oat-brainstorm for that.
Use when the user requests or confirms documenting an active OAT project — e.g. "document the project", "update the docs", "run oat-project-document", or confirms a previously offered documentation run. Do NOT auto-invoke when implementation completes. Analyzes project artifacts, presents a documentation delta plan, and applies approved changes.
Use when the user requests or confirms opening the final PR for an active OAT project — e.g. "open the final PR", "ship it", "run oat-project-pr-final", or confirms a previously offered final-PR step. Do NOT auto-invoke when phases are marked complete. Generates the final lifecycle PR description from artifacts and creates the PR.
Use when an active OAT project needs a mid-project PR for a completed phase (pNN). Generates a phase-scoped progress PR description from OAT artifacts and commit history, with optional PR creation.
Use when the user requests or confirms a project retrospective — e.g. "run the project retro", "write project-retro.md", "retrospective this project", or confirms a previously offered retro. Do NOT auto-invoke merely because implementation or summary completed. Produces references/project-retro.md from project logs, execution learnings, and session/transcript evidence, with repo improvements and OAT upstream feedback.
Use when the user requests or confirms filing proposed feedback from a project retro into repository or upstream GitHub issues and OAT backlog items. Runs destination capability, duplicate, approval, and sanitization checks before filing, then writes destinations and statuses back to the retro artifact.
Use when the user requests or confirms summarizing an active OAT project — e.g. "summarize the project", "generate the summary", "run oat-project-summary", or confirms a previously offered summary run. Do NOT auto-invoke when implementation completes. Generates summary.md from project artifacts as institutional memory.
Use when one delivery needs a design-aligned interview, a single approved Project Brief with phases of intent and exit evidence instead of planned tasks, and resumable OAT implementation.
Use when work happened outside the OAT project workflow and needs retroactive project tracking. Creates a full project from an existing branch and conversation context.
Use when an outcome needs several deliveries over time - one approved Project Brief with a Milestones table, a milestone loop of activation, delivery and re-alignment, and a terminal declaration audited against the brief's outcomes.
Use when a task is small enough for quick mode or rapid iteration is preferred. Scaffolds a lightweight OAT project from discovery directly to a runnable plan, with optional brainstorming and lightweight design.
Use when plan.md is ready for execution. Dispatches one phase implementer per phase, owns independent phase review and bounded fix routing, and supports plan-declared worktree-isolated parallel phases.
Use when human-implemented commits need to be mapped back to planned tasks. Reconciles implementation.md and state.md after manual work outside the OAT workflow.
Use when discovery is complete and implementation-ready decisions are needed. Runs a collaborative, selective collaborative, or draft-and-review design flow, confirms requirements and produces both `spec.md` and `design.md`, and commits artifacts before the user-review gate.
Use when the user explicitly asks to continue discovery for an active spec-driven OAT project — e.g. "continue discovery", "run discovery", or confirms a previously offered discovery step. Do NOT auto-invoke for new ideas or quick/lite-mode projects. Gathers requirements and context before spec/design.
Use when discovery is complete but you're not ready to design yet, and you want to formalize requirements into a structured spec.md as an optional standalone step. Independent of the design workflow — oat-project-design confirms requirements automatically and does not require this skill to be run first.
Use when continuing work on the active OAT project. Reads project state, determines the next lifecycle action, and invokes the appropriate skill automatically.
Use when the user explicitly asks to check OAT project progress — e.g. "check progress", "what's next", "where are we", or confirms a previously offered progress check. Do NOT auto-invoke just because a workflow step completed. Reads project status and offers the next route.
Use when a bounded investigation needs source-grounded evidence before analysis or implementation. Produces a validated evidence-packet directory through approved provider-neutral worker waves.
Use when auditing a repository or turning maintainability reviews, backlog reviews, backlog directories, or backlog items into self-contained external implementation plans.
Use when onboarding OAT to a repository or when knowledge artifacts are stale. Generates or refreshes the codebase knowledge index using parallel mapper agents.
Use when you need a structured maintainability analysis for a repository or directory target with actionable findings and an optional external-plan handoff.
Multi-angle analysis of existing artifacts, codebases, documents, or systems. Examines what you have from six analysis angles and produces structured findings with prioritized recommendations.
Domain-aware comparative analysis with clear recommendations. Compares options across auto-detected or user-specified dimensions and produces a qualitative assessment with a clear winner.
Comprehensive research orchestrator that classifies topics, dispatches parallel research-angle workers, and produces structured artifacts using domain-specific schemas.
Use when the user questions or suspects an agent claim is wrong. Adversarially gathers evidence to verify or refute the claim using the best sources available in the current environment.
Merge multiple analysis artifacts into a single coherent report with provenance tracking. Reads existing artifacts from /deep-research, /analyze, and /compare.
Use when the user explicitly asks to review an OAT project — e.g. "review project", "review the project", "run project review", or confirms a previously offered review. Do NOT auto-invoke on completed work alone. Resolves a project review scope and offers before running.
Use when reviewing a GitHub PR opened on another machine for an active OAT project and posting findings back as a single PR review. Resolves the project from the PR diff, reads project artifacts for mode-aware review, and posts via gh api.
Use when the user explicitly asks to receive review findings for an OAT project — e.g. "receive review", "process review", "process the project review", or confirms a previously offered review-receive step. Do NOT auto-invoke merely because a review file exists. Resolves the latest review and offers before acting.
Use when you need an ad-hoc review outside an active OAT project lifecycle. Reviews code or artifacts without project phase state, unlike oat-project-review-provide.
Use when reviewing a GitHub PR opened on another machine and posting findings back as a single PR review, outside any OAT project context. Fetches the PR via gh, reviews it, and posts via gh api.
Use when processing GitHub PR review comments outside project context. Fetches PR comments via agent-reviews and converts them into actionable task lists.
Use when preparing a shipping digest or weekly/biweekly wrap-up summarizing OAT projects and merged PRs over a time window. Reads local summary files and GitHub PR metadata; writes a version-controlled markdown report.
Use when you want to check the health of your OAT setup in one place — config, project management (PJM), agent instructions, docs, and installed tools — and then work through what it finds. Sweeps read-only, reports by area, and dives into an area on request, teaching from the bundled docs and offering exact fix commands.
Use when delegating work to subagents or choosing a model for a task — routing by task class, selecting provider-specific models and effort, and verifying subagent claims. Covers OpenAI/Codex, Anthropic/Claude, and Cursor.
Use when executing a wave of external implementation plans as a wrapper OAT project — scaffolding, drift refresh, parallel worktree groups, briefs, gates, merge choreography, and closeout.
Use when decomposing a corpus of external implementation plans into an ordered wave program — coverage inventory, dependency mapping, wave composition, and the durable execution-program artifact that oat-wave-execute consumes and updates.