agent-runbook

Multi-agent skill framework — compile contract-based YAML runbooks into Claude Code / Codex SKILL.md files. Every step declares input and output with JSON Schema. The compiler validates contract closure at build time. Broken runs resume from the last checkpoint.

Loop Engineering

Loop engineering is replacing yourself as the one who prompts the agent. You design a system that finds work, dispatches agents, checks results, and decides what comes next — then you let that system run. agent-runbook is a loop engineering framework: each runbook defines the loop, the compiler produces the SKILL.md, and agents execute it while you stay the engineer.

Who is this for

• Developers building complex multi-step agent workflows in Claude Code or Codex
• Skill authors who need control flow beyond linear prompts: loops, parallelism, branching, checkpoints
• Teams that want agents to communicate via structured files instead of LLM context

Install

pip install git+https://github.com/KnoxOps/agent-runbook.git

Example

See examples/restart-nginx/runbook.yaml for a complete example. Here's the structure:

# examples/restart-nginx/runbook.yaml
name: restart-nginx
description: SSH into a server, restart Nginx, and verify it's back up

input_params:
  - name: host
    type: string
    required: true

steps:
  - id: restart
    type: agent
    prompt: SSH into {host} and run systemctl restart nginx
    output:
      - file: restart_result.json
        schema: schemas/restart.schema.json

  - id: verify
    type: agent
    prompt: curl http://{host}/health and check the status code
    input:
      - schema: schemas/restart.schema.json
        from_step: restart
        file: restart_result.json
    output:
      - file: verify_result.json
        schema: schemas/verify.schema.json
    depends_on: [restart]

Build it:

$ python3 -m agent_runbook generate examples/restart-nginx/runbook.yaml -o examples/restart-nginx/

This produces SKILL.md — ready for Claude Code or Codex to execute.

How It Works

  runbook.yaml
       │
       ▼
  ┌──────────┐    ┌──────────┐    ┌──────────┐
  │  Parse   │───▶│ Validate │───▶│ Compose  │───▶ SKILL.md + checkpoint scripts
  └──────────┘    └──────────┘    └──────────┘
                       │
              Contract closure check:
              • Every input.from_step exists
              • Schema references resolve
              • DAG has no cycles

Why Files Over Context

Step Types

Demo

See examples/fix-loop/ for a working demo: a runbook that iteratively runs pytest, identifies failing tests, fixes source code one file at a time, and repeats until the test suite is green — all driven by the loop step type with cascading dependency resolution.

Usage

CLI (generic, zero coupling)

python3 -m agent_runbook generate <runbook.yaml> --output <dir>

Wrapper with directory convention

Projects should wrap the CLI with their own path convention. For example:

# From repo root — output path auto-derived from convention
python3 scripts/gen-skill rules/<agent>/<skill>/runbook.yaml

Convention: rules/<agent>/<skill>/runbook.yaml → skills/<agent>/<skill>/SKILL.md

scripts/gen-skill is the only place that knows the project-specific directory layout. The CLI itself remains generic.

Configuration

Input Parameters

Declare typed inputs at the top level:

input_params:
  - name: host
    type: string
    required: true
    description: Target server

Output Contracts

Every step can declare output with JSON Schema:

output:
  - schema: schemas/output.schema.json
    file: output.json

Quality Checks

quality_check:
  blocking: true
  rules:
    - "output.json schema compliance"
    - "result count > 0"

Checkpoint & Resume

steps:
  - id: long_task
    checkpoint: scripts/checkpoint_task.py

Status

Active development — API may change.

Ecosystem

Built with agent-runbook:

• open-devops-skills — Production-ready DevOps & SRE skills: zombie resource scanning, cost optimization, K8s troubleshooting, and more for Claude Code and Codex.

Maintained by KnoxOps.

License

Apache 2.0