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.mddescribing 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,.guidebundle, 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-levelschemas/; wheel-packaged atagentguides/_schemas/; public$idpoints athttps://agentguides.io/schema/...).docs/QUICKSTART.mdanddocs/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
docs/SPEC.md— what a Guide is, what a conforming harness must do.examples/books/postgres-upgrade/postgres-major-upgrade/— a worked example exercising every spec section.docs/DESIGN.md— why each decision was made.docs/ARCHITECTURE.md— how the v0.1 reference runtime is built.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.
Metadata
Release files for agentguides 0.5.12
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentguides-0.5.12.tar.gz | 1.4 MB | Without provenance | Details for agentguides-0.5.12.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentguides-0.5.12-py3-none-any.whl | Python 3 | none | any | Details for agentguides-0.5.12-py3-none-any.whl |
Total release size: 1.8 MB
Release files / agentguides-0.5.12.tar.gz
| Download URL | agentguides-0.5.12.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e112d6d626a1e3a9122b2801acab1abf30cb4395b31ca70f9ce521bbcc7fa7b0
|
|
BLAKE2b-256 checksum How to use checksums |
36b8489ca43bef4bd80b08fff0d3b139bf0c13300a9d5d5630dbbbc7c27eecab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / agentguides-0.5.12-py3-none-any.whl
| Download URL | agentguides-0.5.12-py3-none-any.whl |
|---|---|
| Size | 424.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
51fe6b36f92caadd773c56125acd9418bd3adcbc49e5e530b72abeea9b653c28
|
|
BLAKE2b-256 checksum How to use checksums |
accfdcf423c32b79b5cc76f12b6b38b7ed037d697f5767c568b83f523d059aeb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for agentguides 0.5.12
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.