agentscribe

agentscribe

One source of truth for your AI agent instructions.

Write your project's guidance once in AGENTS.md, and let agentscribe generate and keep in sync every tool-specific variant — CLAUDE.md, Cursor rules, GitHub Copilot instructions, Gemini, Windsurf, Cline — then lint the source and fail CI when the copies drift.

---

The problem

Every AI coding tool reads its instructions from a different file:

If your team uses more than one of these — and most do now — you end up copy-pasting the same rules into five files and watching them rot out of sync.

The fix

Keep one file (AGENTS.md, the emerging open standard that Codex reads) and generate the rest:

pip install agentscribe

agentscribe init      # scaffold an AGENTS.md from your project
agentscribe sync      # generate CLAUDE.md, Cursor rules, Copilot instructions, ...
agentscribe check     # in CI: fail if any generated file is out of date
agentscribe lint      # catch leaked secrets, dead file refs, bloated instructions

Generated files carry a "do not edit" header and are byte-stable, so check gives you a clean pass/fail in CI.

Quickstart

$ agentscribe init
Created AGENTS.md  (detected: Python)

$ agentscribe sync
  + CLAUDE.md  (Claude Code)
  + .cursor/rules/agentscribe.mdc  (Cursor)
  + .github/copilot-instructions.md  (GitHub Copilot)
Updated 3 file(s) from AGENTS.md.

$ agentscribe check
All target files are in sync with AGENTS.md.

Now edit AGENTS.md whenever your conventions change and re-run agentscribe sync.

Commands

Run agentscribe <command> --help for all flags.

Configuration

Configuration is optional. Put it in agentscribe.toml:

source = "AGENTS.md"
targets = ["claude", "cursor", "copilot", "gemini"]

[lint]
max_chars = 12000

[cursor]
legacy = false                 # true -> write .cursorrules instead of .mdc
description = "Project rules"
always_apply = true

…or under [tool.agentscribe] in pyproject.toml. Available target keys: claude, cursor, copilot, gemini, windsurf, cline.

Scoping content to specific tools

Most guidance is shared, but sometimes one tool needs its own note. Use HTML-comment directives — invisible when the file renders as Markdown:

Shared guidance for every agent.

<!-- agentscribe:only cursor,copilot -->
This paragraph is emitted only into the Cursor and Copilot files.
<!-- agentscribe:end -->

<!-- agentscribe:except claude -->
Goes everywhere except CLAUDE.md.
<!-- agentscribe:end -->

<!-- agentscribe:ignore -->
Private notes that stay in AGENTS.md and are never copied anywhere.
<!-- agentscribe:end -->

Directives may be nested.

Use in CI

Add a check so generated files can never silently drift. GitHub Actions:

- run: pip install agentscribe
- run: agentscribe check   # fails the build if CLAUDE.md et al. are stale
- run: agentscribe lint    # fails on leaked secrets or malformed instructions

Library API

Everything the CLI does is available programmatically:

from agentscribe import Config, sync, check, lint

cfg = Config.load(".")
sync(cfg)  # write all target files
drift = check(cfg)  # list of out-of-date targets
findings = lint(cfg)  # list of Finding(level, rule, message, line)

How is this different from copy-pasting or a symlink?

• Symlinks don't work: each tool wants a different format and location (Cursor needs YAML front-matter; Copilot lives under .github/), and symlinks are fragile on Windows and in Git.
• Copy-pasting is exactly the drift problem this tool removes.
• agentscribe transforms one source into each tool's real format, and check turns "did someone forget to update a file?" into a CI failure.

Design goals

• Near-zero dependencies. Pure standard library on Python 3.11+ (a single tomli backport on 3.9–3.10).
• Deterministic output. LF endings, stable ordering — diffs stay clean.
• Conservative linting. Actionable findings over noisy ones.

Contributing

Contributions are welcome — see CONTRIBUTING.md. This project dogfoods itself: its own CLAUDE.md, Cursor, and Copilot files are generated from AGENTS.md by agentscribe sync, and CI runs agentscribe check.

License

MIT