agent-policy

Schema-first generator for coding-agent repo policies and compatibility files.

Generates AGENTS.md, CLAUDE.md, .cursor/rules/, and .windsurf/rules/ (among others) from a single agent-policy.yaml.

What it does

Maintaining AGENTS.md, CLAUDE.md, and Cursor rules separately means the same policy information gets duplicated across files that diverge over time. agent-policy solves this by letting you define your repo's coding-agent policy once in a canonical agent-policy.yaml, then generating all the tool-specific compatibility files from that single source of truth.

Keep one policy file. Generate all agent instruction files from it. Detect drift in CI.

Install

From npm (no Rust toolchain required)

npx agent-policy
# or install globally
npm install -g agent-policy

From PyPI (no Rust toolchain required)

pip install agent-policy-cli
# or with pipx (recommended for CLI tools)
pipx install agent-policy-cli
# or with uv
uv tool install agent-policy-cli

The PyPI package is agent-policy-cli; the command it installs is agent-policy.

From crates.io

cargo install agent-policy

Binary releases

Download pre-built binaries from GitHub Releases.

Quick start

# Create a starter policy
agent-policy init

# Edit agent-policy.yaml, then generate
agent-policy generate

# Add to CI to prevent drift
agent-policy check

Commands

Both generate and check accept --config / -c to specify a non-default config path, and --targets to natively override outputs:

agent-policy generate --config infra/agent-policy.yaml
agent-policy check --targets agents-md,clinerules

agent-policy.yaml

Minimal example:

project:
  name: my-project
  summary: A short description.
outputs:
  - agents-md

Note: You do not need to manually add .md outputs or target paths to your paths.generated config list. Any active outputs are injected into your generated list automatically!

Full example — see examples/website/agent-policy.yaml.

The file is validated against agent-policy.schema.json (JSON Schema Draft 2020-12). The schema is bundled with the binary and is versioned alongside it. It is considered unstable until v1.0.0.

Generated outputs

When outputting directory rules like cursor-rules or clinerules, agent-policy generates one default layout and optionally one file per customized role, intelligently assigning frontmatter globs and path references directly into the generated configurations to cleanly silo AI behaviors scope-to-scope!

CI integration

Add to your CI workflow to enforce that generated files are never edited by hand:

- name: Check agent policy
  run: agent-policy check

This step exits non-zero if any generated file is stale or missing, and prints a unified diff to stderr.

Non-goals

• Not a replacement for AGENTS.md — it generates AGENTS.md
• Not a full enforcement engine or policy-as-code runtime
• Not a SaaS platform or hosted service
• Not a daemon or background process

License

Apache-2.0