Agent Guides

Guides — a Skill-compatible extension to the Agent Skills specification for multi-step processes that need human or agent judgment.

A Guide is a directory that conforms to the Skill spec and adds:

• A GUIDE.md describing the workflow (summary, goal state, prerequisites, rollback).
• A steps/ directory with one markdown file per step (action + optional verify + optional recovery + optional rollback).
• An atomic, append-only state and audit history (markdown in v0.1; pluggable for future backends).

Every Guide is a valid Skill. Skill-only harnesses see a useful artifact; Guide-aware harnesses execute the workflow.

Install

Agent-installable: paste INSTALL.md into any agent (it follows the INSTALL.md convention), or install directly:

uv tool install agentguides           # puts `guide` on PATH

The guide binary is the hard prereq. Per-harness wiring (walk Skill, walk-observer plugin, MCP server registration) is installed by guide setup <harness> — one-time per machine; see the Run a Guide section below and docs/cli/setup.md for the four install dimensions (scope, mode, capability, install method).

Dev install from a checkout:

uv sync                                  # creates .venv from pyproject.toml + uv.lock

Author a Guide

The guide new scaffolder produces a SKILL-folder skeleton that passes guide validate immediately:

guide new my-guide --into ./guides
# Scaffolded at ./guides/my-guide/{SKILL.md, GUIDE.md, steps/010-first-step.md, plugin.json, README.md}
guide validate --root ./guides/my-guide --book ./guides
# OK

For an interactive author flow that asks about the goal, step list, and recovery story, invoke the /create-guide Skill (skills/create-guide/). It calls guide new under the hood and edits the placeholders inline.

See docs/SPEC.md for the full data model and examples/books/postgres-upgrade/postgres-major-upgrade/ for a worked example.

Share a Guide

Guides distribute as folders (drop into ~/.claude/skills/), as plugin-per-guide (the folder + a plugin.json), or as a single-file .guide bundle for transport:

guide pack ./guides/my-guide --out ./dist
# → ./dist/my-guide-0.1.0.guide  (ZIP + MANIFEST.json; sha256-stamped)

guide unpack ./dist/my-guide-0.1.0.guide /tmp/extracted
# → /tmp/extracted/my-guide/   (sha256 + spec_version verified before write)

For multiple related Guides under a single plugin, see the examples/books/db-ops/ book example (and examples/books/postgres-upgrade/).

Run a Guide

Three execution paths:

1. In Claude Code (LLM-driven, full feature set):

guide setup claude-code   # one-time per machine: installs walk Skill + walk-observer plugin
guide harness walk --adapter claude-code --guide examples/books/postgres-upgrade/postgres-major-upgrade --exec

guide setup writes the walk Skill (rendered from a packaged template for the chosen mode + capability) and the walk-observer plugin into ~/.claude/skills/. Claude Code auto-discovers both on its next session. The harness run command prepares per-walk scratch (mcp-config, prompt, audit state path) and invokes claude -p with the right flags. See docs/cli/setup.md and docs/adapters/claude-code.md.

2. Headless (no LLM, scripts only):

python -m tests.headless_runner \
    --root examples/books/postgres-upgrade/postgres-major-upgrade \
    --state-path /tmp/headless-test
# Script actions run; manual/agent_judgment steps log "skipped: no LLM".

Useful for CI smoke tests and non-LLM ops pipelines. See docs/adapters/cli.md.

3. Resuming an interrupted run — the harness uses walk_current({guide_id}) to find the active run id and asks the user whether to resume, abandon, or inspect.

Analyze walks

Because a Guide's state and audit history are atomic and append-only, every walk is replayable as data. The guide eval subsystem lifts that history into a typed graph and turns it into evidence — this is what makes a Guide more than a Skill: auditable, analyzable workflows you can measure and improve.

guide eval walks    --guide <root> --runs r1,r2   # per-run efficiency report + friction signals
guide eval graph    --guide <root> --format dot   # static GuideDAG (DOT for Graphviz)
guide eval universe --guide <root>                # cross-Guide graph (multi-Guide books)
guide eval analyze  --guide <root>                # graph analytics: hot spots, dead branches

Reports attribute friction (stalls, retries, dead ends) to specific edges of the Guide, giving the reviewer evidence-anchored proposals for tightening the workflow.

An operator-facing web viewer (read-only SPA over runs, reports, and heatmaps) is in preview behind a feature flag:

GUIDE_WEB_ENABLED=1 guide web        # requires the [web] extra: pip install 'agentguides[web]'

Design docs: .planning/plans/walk-efficiency-analytics.md (the analytics model) and .planning/plans/interactive-ui.md (the viewer roadmap).

Documentation

All public documentation lives under docs/:

• docs/SPEC.md — normative Guide v0.1 specification.
• docs/DESIGN.md — design record. Appendices §22–§26 cover the v0.1 runtime, toolchain, .guide bundle, parity rule, and repo layout.
• docs/ARCHITECTURE.md — runtime topology, component layering, state lifecycle, packaging shapes (Mermaid diagrams).
• docs/adapters/ — per-harness implementation guides (claude-code.md, cli.md).
• schemas/ — JSON Schemas validating each Guide artifact (canonical at the top-level schemas/; wheel-packaged at agentguides/_schemas/; public $id points at https://agentguides.io/schema/...).
• docs/QUICKSTART.md and docs/CHANGELOG.md — added in M6.

Working Guides live in examples/:

• postgres-upgrade/ — primary + rescue Guide pair as a book; cross-Guide bare-name references.
• db-ops/ — three Guides under one book; cross-Guide bare-name references.
• api-latency-spike-triage/, wildland-fire-incident-command/, hello-walk/ — standalone single-Guide examples.

Reading order

1. docs/SPEC.md — what a Guide is, what a conforming harness must do.
2. examples/books/postgres-upgrade/postgres-major-upgrade/ — a worked example exercising every spec section.
3. docs/DESIGN.md — why each decision was made.
4. docs/ARCHITECTURE.md — how the v0.1 reference runtime is built.
5. docs/adapters/claude-code.md — implementing or installing the runtime for Claude Code.

just recipes

just setup           # uv sync
just validate        # schema + DAG + refs for every example Guide
just test            # run the Python test suite
just new <name>      # scaffold a Guide (passes guide validate immediately)
just pack <dir>      # produce a .guide bundle
just unpack <bundle> <dest>
just launch [GUIDE]  # Claude Code session with example + MCP server attached
just watch           # tail the active run state file
just inspect         # open the active run state file in $EDITOR
just clean           # wipe /tmp/guide-test-* dirs

Project planning

Internal planning artifacts (active plans, ADRs, milestone trackers) live under .planning/. Contributors who want context should look there; end users do not need to.

Status

v0.1. See docs/SPEC.md §19 for the explicit list of features deferred to v0.2+, and .planning/milestones/v0.1.md for milestone progress.