agentdocs

Portable, structured documentation that AI agents can actually use. CLI for the AgentDocs format — brief.md + tasks.yaml + playbooks/.

Think of it as npm or cargo, but for AI-agent-consumable tool docs. Your repo declares what tools exist, how to call them, and what playbooks orchestrate them — and any agent (Claude Code, Cursor, Codex, MCP clients, your own glue) can read the same thing.

Install

npm install -g @biroai/agentdocs-cli

Or use it with pnpm dlx / npx:

pnpm dlx agentdocs init stripe

Quickstart

# Scaffold a new pack under .agentdocs/stripe/
agentdocs init stripe --kind api

# Fill in brief.md (keep it under ~500 tokens) and add actions to tasks.yaml.
# Then:
agentdocs validate
agentdocs preview stripe

A pack is three things, always in the same shape:

.agentdocs/
  stripe/
    brief.md         # injected at session start (<=500 tokens)
    tasks.yaml       # structured action catalog
    playbooks/       # multi-step flows (markdown or YAML DAG)
      create-charge.md

Commands

Command	What it does
agentdocs init <name>	Scaffold .agentdocs/<name>/brief.md, tasks.yaml, playbooks/. Flags: --kind <api|cli|sdk|internal|process>, --path <dir>, --force.
agentdocs validate [path]	Validate brief + tasks + playbooks against the spec. Default target: ./.agentdocs.
agentdocs preview <name>	Print the brief, action summary, and playbook list for a pack.
agentdocs add <name>	(stub) Registry pull — coming soon.

Root flags: --version, --help, --json. Pass --json to get machine-readable output for any command.

Exit codes

Code	Meaning
0	Success (warnings are OK)
1	Validation error, usage error, or missing pack
2	Unexpected crash

Schemas

Schemas and validators live in @biroai/agentdocs and are also published to npm. If you want to validate packs inside your own tooling without shelling out to this CLI, depend on that package directly.

Roadmap

• agentdocs add <name> — pull published packs from the AgentDocs registry.
• agentdocs init --from-openapi <file> — scaffold tasks.yaml from an OpenAPI document.
• agentdocs init --from-mcp <endpoint> — scaffold from an MCP server's tool list.
• Markdown playbook validation — v1 only validates YAML DAG playbooks; markdown playbooks are displayed as-is.

See github.com/Tim-ReJet/agentdocs-cli for the roadmap, and @biroai/agentdocs on npm for the spec schemas.

License

MIT © 2026 Biro AI