SKILLS.md

Skills Reference

Narrative reference for checked-in AgentOps skills. The current inventory is generated from skills/**/SKILL.md into registry.json and the generated domain maps; do not hard-code skill counts here.

Skills are the primitive layer of AgentOps. Higher-level entry points like /implement, /validate, /rpi, and /evolve compose those primitives into repeatable flows.

Behavioral Contracts: Most skills include scripts/validate.sh behavioral checks to verify key features remain documented. Run skills/<name>/scripts/validate.sh when present, or the GOALS.yaml behavioral-skill-contracts goal to validate the full covered set.

Skill Router (Start Here)

Use this when you're not sure which skill to run. For a full flow overview, run ao session bootstrap, then /inject when you need on-demand context loading.

What are you trying to do?
│
├─ "Not sure what to do yet"
│   └─ Generate options first ─────► /discovery --ideate
│
├─ "I have an idea"
│   └─ Understand code + context ──► /research
│
├─ "I know what I want to build"
│   └─ Break it into issues ───────► /plan
│
├─ "Now build it"
│   ├─ Small/single issue ─────────► /implement
│   ├─ Multi-issue epic ───────────► /crank <epic-id>
│   └─ Full flow in one command ───► /rpi "goal"
│
├─ "Fix a bug"
│   ├─ Already scoped? ────────────► /implement <issue-id>
│   └─ Need to investigate? ───────► /review (bug-hunt mode)
│
├─ "Build a feature"
│   ├─ Small (1-2 files) ─────────► /implement
│   ├─ Medium (3-6 issues) ───────► /plan → /crank
│   └─ Large (7+ issues) ─────────► /rpi (full pipeline)
│
├─ "Validate something"
│   ├─ Work ready to close? ──────► /validate, then /post-mortem
│   ├─ Code quality only? ───────► /validate
│   ├─ Plan ready to build? ──────► /pre-mortem
│   └─ Quick sanity check? ───────► /council --quick validate
│
├─ "Explore or research"
│   ├─ Understand this codebase ──► /research
│   ├─ Compare approaches ────────► /council research <topic>
│   └─ Generate ideas ────────────► /discovery --ideate
│
├─ "Learn from past work"
│   ├─ Turn the corpus into operator surfaces ─► /operationalize
│   ├─ What do we know about X? ──► ao lookup "<query>" / ao search
│   ├─ Save this insight ─────────► /post-mortem --quick "insight"
│   └─ Full retrospective ────────► /post-mortem
│
├─ "Parallelize work"
│   ├─ Multiple independent tasks ► /swarm
│   └─ Full epic with waves ──────► /crank <epic-id>
│
├─ "Ship a release"
│   └─ Changelog + tag ──────────► /release <version>
│
├─ "Session management"
│   ├─ Compile knowledge ─────────► /forge or /compile
│   ├─ Where was I? ──────────────► /status
│   ├─ Save for next session ─────► /handoff
│   └─ Recover after compaction ──► /recover
│
└─ "First time here" ────────────► ao quick-start → /status

Core Flow Skills

/research

Deep codebase exploration using Explore agents.

/research authentication flows in services/auth

Output: .agents/research/<topic>.md

/plan

Decompose goals into trackable beads issues with dependencies.

/plan "Add user authentication with OAuth2"

Output: Beads issues with parent/child relationships

/implement

Execute a single beads issue with full lifecycle.

/implement ap-1234

Phases: Context → Tests → Code → Validation → Commit

/discovery --ideate

Structured idea exploration. Four phases: assess clarity, understand idea, explore approaches, capture design.

/discovery --ideate "add user authentication"

Output: .agents/discovery/YYYY-MM-DD-<slug>.md

/rpi

Full RPI lifecycle orchestrator. Discovery → Implementation → Validation in one command.

/rpi "Add user authentication"
/rpi --fast-path "fix typo in README"
/rpi --from=implementation ag-1234

Phases: Discovery (/discovery) → Implementation (/crank) → Validation (/validate)

/crank

Autonomous multi-issue execution. Runs until epic is CLOSED.

/crank <epic-id>

Execution model: Wave-based orchestration via /swarm with runtime-native workers.

/validate

Final validation close-out. Use /post-mortem after validation when the work should feed the knowledge flywheel.

/validate
/validate ag-1234

Use when: The work is ready for final review, closeout, and learning capture.

/validate --mode=post-impl (absorbs /vibe)

Comprehensive code validation across 8 aspects with finding classification (CRITICAL vs INFORMATIONAL), suppression framework for known false positives, and domain-specific checklists (SQL safety, LLM trust boundary, race conditions) auto-loaded from /standards. Correlates findings against pre-mortem predictions.

/validate --mode=post-impl services/auth/

Checks: Security, Quality, Architecture, Complexity, Testing, Accessibility, Performance, Documentation

/post-mortem --quick

Quick-capture a learning. For full retrospectives, use /post-mortem.

/post-mortem --quick "debugging memory leak"

Output: .agents/learnings/

/post-mortem

Full validation + knowledge lifecycle. Council validates, extracts learnings, activates/retires knowledge, then synthesizes process improvement proposals and suggests the next /rpi command. The flywheel exit point. Now includes RPI session streak tracking, prediction accuracy scoring (HIT/MISS/SURPRISE against pre-mortem predictions), and persistent retro history to .agents/retro/ for cross-epic trend analysis. Supports --quick, --process-only, and --skip-activate flags.

/post-mortem <epic-id>
/post-mortem --quick            # Lightweight post-mortem
/post-mortem --process-only     # Process improvements only
/post-mortem --skip-activate    # Skip knowledge activation

Output: Council report, learnings, knowledge activation/retirement, process improvement proposals, next-work queue (.agents/rpi/next-work.jsonl)

---

Utility Skills

/beads-br

Git-native issue tracking operations.

BEADS_DIR=$PWD/_beads br ready      # Unblocked issues
BEADS_DIR=$PWD/_beads br show <id>  # Issue details
BEADS_DIR=$PWD/_beads br close <id> # Close issue

/review (absorbs /bug-hunt)

Root cause analysis with git archaeology.

/review "login fails after password reset"

Knowledge queries (no slash command)

Query knowledge artifacts across locations via the CLI. There is no standalone knowledge skill — use /operationalize, /forge, and /compile for corpus promotion, or run the CLI below for ad-hoc lookup.

ao lookup "patterns for rate limiting"
ao search --all "patterns for rate limiting"

Searches: .agents/learnings/, .agents/patterns/, .agents/research/, .agents/compiled/

/refactor (absorbs /complexity)

Code complexity analysis using radon (Python) or gocyclo (Go).

/refactor services/

Threshold: CC > 10 triggers refactoring issue

/doc

Generate and validate repo documentation. --mode selects the artifact family: default (code/API docs, code-maps), --mode=readme (gold-standard README via interview + council validation), or --mode=oss (open-source doc pack: CONTRIBUTING, CHANGELOG, AGENTS).

/doc services/auth/          # code/API docs (default)
/doc --mode=readme           # gold-standard README
/doc --mode=oss              # scaffold/audit OSS doc pack

/pre-mortem

Simulate failures before implementing. Includes error/rescue mapping (tabular risk/mitigation), scope mode selection (Expand/Hold/Reduce with auto-detection), temporal interrogation (hour 1/2/4/6+ timeline), and prediction tracking with unique IDs (pm-YYYYMMDD-NNN) correlated through validate and post-mortem.

/pre-mortem "add caching layer"

Output: Failure modes, error/rescue maps, predictions with IDs, mitigation strategies, spec improvements

---

Orchestration Skills

/council

Multi-model validation — the core primitive used by validate, pre-mortem, and post-mortem. Auto-extracts significant findings from WARN/FAIL verdicts into the knowledge flywheel.

/council validate recent
/council --deep recent

/swarm

Parallel agent spawning for concurrent task execution.

/swarm <epic-id>

Runtime-native multi-agent lanes

Spawn parallel execution agents through the current runtime/substrate. Use /swarm for the skill-level entry point; use Codex subagents or NTM/ATM when the active runtime owns that transport.

/swarm <epic-id>

---

Additional Utility Skills

/handoff

Session handoff — preserve context for continuation.

/handoff

/release

Pre-flight checks, changelog generation, version bumps, and tagging.

/release

/status

Single-screen dashboard of project state.

/status

/status (absorbs /quickstart)

Interactive onboarding — mini RPI cycle for new users.

/status

Out-of-session compounding

Retirement pointer. The in-tree out-of-session compounding engine was removed (soc-2rtm0); scheduled, between-session knowledge compounding now runs via an adopted substrate, and AgentOps ships no out-of-session runner of its own. In-session knowledge primitives stay on-demand: /forge, /compile, and /inject. Daytime code compounding is /evolve via /rpi.

Output: none — this skill no longer drives an in-repo command.

/recover (absorbs /trace)

Trace design decisions through knowledge artifacts.

/recover "why did we choose Redis?"

Knowledge operationalization

Operationalize a mature .agents corpus into reusable belief, playbook, briefing, and gap surfaces.

ao knowledge activate --goal "productize knowledge activation"
ao knowledge gaps

/recover

Post-compaction context recovery. Detects in-progress RPI and evolve sessions, loads knowledge, shows recent work and pending tasks.

/recover                     # Recover context after compaction

/evolve

Autonomous fitness-scored improvement loop. Measures GOALS.yaml, fixes the worst gap, compounds via knowledge flywheel.

/evolve                      # Run until stopped or the full producer ladder is exhausted
/evolve --max-cycles=5       # Cap at 5 cycles
/evolve --dry-run            # Measure only, don't execute

/product

Interactive PRODUCT.md generation. Interviews about mission, personas, value props, and competitive landscape.

/product

Output: PRODUCT.md in repo root

/heal-skill

Detect and auto-fix skill hygiene issues (missing frontmatter, unlinked references, dead references).

/heal-skill --check                     # Report issues
/heal-skill --fix                       # Auto-fix what's safe
/heal-skill --check skills/council      # Check specific skill

Checks: MISSING_NAME, MISSING_DESC, NAME_MISMATCH, UNLINKED_REF, EMPTY_DIR, DEAD_REF

/converter

Convert skills to other platforms (Codex, Cursor).

/converter skills/council codex          # Single skill to Codex format
/converter --all cursor                  # All skills to Cursor .mdc format

Targets: codex (SKILL.md + prompt.md), cursor (.mdc + optional mcp.json), test (raw bundle)

/pr-prep

Prepare structured PR bodies with validation evidence. Includes commit split advisor (Phase 4.5) suggesting bisectable commit ordering.

/pr-prep

---

Additional Skills

Single-purpose skills not listed above. See each skill's SKILL.md for triggers, phases, and flags.

Skill	Purpose
/autodev	Manage the PROGRAM.md operational contract for autonomous development loops
/bootstrap	One-command product-layer setup (GOALS.md, PRODUCT.md, README.md, .agents/, optional hooks)
/compile	Compile raw .agents/ artifacts into an interlinked wiki at .agents/compiled/ (Mine → Grow → Defrag → Lint)
/security (absorbs deps)	Dependency audit, updates, vulnerability scanning, license compliance
/product	Maintain PRODUCT.md so validation and planning share the same product contract
/discovery	Full discovery-phase orchestrator (ideation + search + research + plan + pre-mortem)
/goals	Maintain GOALS.yaml/GOALS.md fitness specs; measure drift; add/prune directives
/perf	Performance profiling, benchmarking, regression detection, optimization
/push	Atomic test-commit-push with conventional-commit message
/red-team	Persona-based adversarial validation — probes whether docs/skills actually work
/refactor	Safe, verified refactoring with regression tests at each step
/review	Structured review of incoming PRs, agent-generated changes, or diffs
/scaffold	Project scaffolding, component generation, boilerplate
/eval-outcomes (absorbs scenario)	Author/manage holdout scenarios in .agents/holdout/ for behavioral validation
/test	Test generation, coverage analysis, TDD workflow

---

Internal Skills

These are loaded by other skills or lifecycle hooks; they are not primary user-facing entry points:

Skill	Purpose
inject	Load knowledge at session start (ao inject)
forge	Mine transcripts for knowledge artifacts (decisions, learnings, failures, patterns)
flywheel	Knowledge health monitoring
standards	Language-specific coding standards (auto-loaded by /validate, /implement)
shared	Shared reference documents for multi-agent backends
beads-br	Issue tracking reference (local-first beads_rust tracker)

---

Subagents

Subagent behaviors are defined inline within SKILL.md files (not as separate agent files). Skills that use subagents spawn them as Task agents during execution. 20 specialized roles are used across /validate, /pre-mortem, /post-mortem, and /research.

Agent Role	Used By	Focus
Code reviewer	/validate, /council	Quality, patterns, maintainability
Security reviewer	/validate, /council	Vulnerabilities, OWASP
Security expert	/validate, /council	Deep security analysis
Architecture expert	/validate, /council	System design review
Code quality expert	/validate, /council	Complexity and maintainability
UX expert	/validate, /council	Accessibility and UX validation
Plan compliance expert	/post-mortem	Compare implementation to plan
Goal achievement expert	/post-mortem	Did we solve the problem?
Ratchet validator	/post-mortem	Verify gates are locked
Flywheel feeder	/post-mortem	Extract learnings with provenance
Technical learnings expert	/post-mortem	Technical patterns
Process learnings expert	/post-mortem	Process improvements
Integration failure expert	/pre-mortem	Integration risks
Ops failure expert	/pre-mortem	Operational risks
Data failure expert	/pre-mortem	Data integrity risks
Edge case hunter	/pre-mortem	Edge cases and exceptions
Coverage expert	/research	Research completeness
Depth expert	/research	Depth of analysis
Gap identifier	/research	Missing areas
Assumption challenger	/research	Challenge assumptions

---

ao CLI Integration

Skills integrate with the ao CLI for orchestration:

Skill	ao CLI Command
/research	ao lookup, ao search, ao rpi phased
/post-mortem --quick	ao forge markdown, ao session close
/post-mortem	ao forge, ao flywheel close-loop, ao constraint activate
/implement	ao context assemble, ao lookup, ao ratchet record
/crank	ao rpi phased, ao ratchet, ao flywheel status