agentsgen AGENTS.md Generator
LATEST UPDATE
SAFE + REVIEWABLE
V0.5.1

Agent contract layer for AI-ready repos

agentsgen generates, updates, and checks AGENTS.md and RUNBOOK.md for AI coding agents. Use it when you want repo instructions that are reviewable, marker-safe, CI-checkable, and readable by coding-agent clients.

Get started View on GitHub Why it’s safe

init -> check -> guard agentsgen = repo ID = human SET = orchestration skills = reusable workflows id-context.json = bridge

How it fits

Independent tools with explicit boundaries.

agentsgen

  • Owns repo-scoped agent context: AGENTS.md, RUNBOOK.md, pack docs, command manifests, repomap artifacts, and MCP/CLI contract surfaces.

ID

  • Owns portable human context: preferences, freshness, privacy, handshakes, and cross-tool continuity.

SET

  • Owns reviewable orchestration: presets, planning, CI entrypoints, and exported workflows.

Bridge

  • docs/ai/id-context.json is the repo-local handoff surface that lets ID meet repo context without guesswork.
 ABVX Agent Skills logo

abvx-agent-skills

  • Owns reusable capabilities: compact SKILL.md workflows for coding, frontend, audits, debugging, research, token economy, handoffs, and browser verification.

Git Tweet

  • Consumes a completed GitHub Release downstream and turns its verified release notes into social output.

Quickstart

Bootstrap agent docs in minutes. No repo damage.

Agent-readiness loop

  • Bootstrap: create marker-safe repo docs.
  • Enforce: run checks locally and in PRs.
  • Serve agents: emit pack artifacts, manifests, and local MCP surfaces.
  • Fail safely: write sibling generated files when markers are missing.
Readiness is not the full delivery loop. Pair this with delivery gates for spec -> slices -> proof -> review -> release when the change itself needs explicit evidence.
Quickstart 
uv tool install agentsgen
cd your-repo
agentsgen init . --defaults --autodetect
agentsgen check . --ci
Review the detected commands in .agentsgen.json before committing. No API key is required.
Outputs: AGENTS.md, RUNBOOK.md, .agentsgen.json, agents.entrypoints.json, and docs/ai/id-context.json.

Platform signals

Small tool, platform-shaped surfaces.

Distribution

  • Install with uv tool install agentsgen or pipx install agentsgen.
  • Use in CI through the reusable GitHub Action.
  • Run check --report and update for the local readiness loop.
  • Run fleet scan for a read-only team rollout report.
  • Run locally as a stdio MCP server.

Compatibility

  • Produces standard instruction files that Cursor, Claude Code, Codex, Copilot Workspace, and Aider can read; native loading depends on each client.
  • Exposes CLI docs, pack artifacts, JSON contracts, and discovery files.
  • Keeps hosted discovery separate from local-only MCP execution.

Use cases

Where this helps immediately.

Repo context

  • Give Codex, Claude Code, and Cursor a stable repo contract instead of ad-hoc prompt boilerplate.

Human + repo handoff

  • Let ID carry the human and let agentsgen carry the repo, with id-context.json joining them.

CI drift guard

  • Fail pull requests when docs, pack artifacts, or snippets drift from the expected repo state.

Multi-repo orchestration

  • Feed the same repo runtime into SET when you want one entrypoint across many repositories.

The philosophy

Agentsgen is built for one goal: less babysitting, fewer hallucinations, lower token burn.

  • No text for the sake of text. If it doesn’t prevent mistakes, it doesn’t belong in always-loaded context.
  • Instrumented truth beats prose. Prefer check/status/pack --check over “hope this CLAUDE.md stays true”.
  • Progressive disclosure scales. Keep global rules small; pull deeper docs only when the task needs them.
Rooted in: ETH “Do Context Files Help?” + Codified Context (layered memory).
Read the full Manifest

Safety model

Safe to re-run: generated sections are owned; everything else stays yours.

1
File missing
Create docs with section markers.
2
Markers exist
Update only inside marker ranges.
3
No markers
Never overwrite; write sibling *.generated.md.
Markers make updates idempotent and reviewable.

Auto-detect (no AI)

Priority rules. Conservative defaults.

  • Makefile (dominant)
  • package.json scripts
  • Python heuristics (uv / poetry / pytest / ruff, etc.)
  • Otherwise: minimal baseline (no hallucinated commands)
No command execution. No network. No AI inference.

Pack bundle (optional)

AI-readable docs bundle generated with the same safety model.

  • Crawl / index layer: llms.txt (or LLMS.md)
  • Execution layer: agents.entrypoints.json, docs/ai/how-to-run.md, docs/ai/how-to-test.md
  • Boundary layer: docs/ai/architecture.md, docs/ai/data-contracts.md
  • Handoff layer: docs/ai/id-context.json for ID-compatible workflows
  • Policy layer: SECURITY_AI.md, CONTRIBUTING_AI.md, README_SNIPPETS.md
Commands: agentsgen pack --autodetect and agentsgen pack --autodetect --check.
ID reads the human. agentsgen reads the repo. id-context.json connects them.
If markers are missing, pack writes sibling *.generated.* files instead of overwriting originals.
Companion guide for site-oriented AI visibility work: LLMO Quick Start (PDF).

PR Guard + Pack drift check Recommended

Fail PRs when agent docs drift. Optionally enforce pack bundle drift in the same job.

Why it matters

  • Fail PRs when generated docs drift.
  • pack_check: "true" adds agentsgen pack --check.
  • Marker-only ownership stays intact for handcrafted docs.
Works on forks (best-effort comments).
Workflow 
name: agentsgen guard + pack check

on:
  pull_request:
  push:
    branches: [ main ]

permissions:
  contents: read
  pull-requests: write

jobs:
  agentsgen:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: markoblogo/AGENTS.md_generator/.github/actions/[email protected]
        with:
          comment: "true"
          files: |
            AGENTS.md
            RUNBOOK.md
          pack_check: "true"
          pack_format: "json"
If you do not want PR comments, set comment: "false".

Docs (deep dives)

Everything detailed lives in docs. The landing stays short.

Action docs
Pack bundle docs
ID integration
LLMO Quick Start guide (PDF) for site pack / analyze / meta
Release kit

FAQ

Short answers.

What is AGENTS.md?
A repo-level contract for coding agents: setup, commands, guardrails, and “done” criteria. Think “README for agents”.
Will it overwrite my existing docs?
By default, no. Without markers it writes a sibling *.generated.md file and leaves your originals untouched.
What is the pack bundle?
A small bundle of AI-readable docs (run/test/architecture/contracts plus policies) that can be enforced via pack --check.
Does it work for monorepos?
It can detect mixed; if unsure, it stays conservative and may leave commands empty intentionally.

Known limitations

Conservative by design.

  • Monorepos may be detected as mixed; commands can be empty by design.
  • Unusual workflows should be set explicitly in .agentsgen.json.
  • This generates process guidance, not a full developer handbook.
Details in docs.