aaditya1273/agent.md

What it finds

Real output, on a small example repo:

  Agent context audit  acme-app
  2 files an agent reads · ~52 tokens loaded on every prompt

     1  secrets in files the agent reads
     1  prompt-injection signals
     1  dangerous patterns in 1 skill script
     1  references to files that no longer exist
     1  formatting rules a formatter already enforces  auto-fixable

  ERROR   .claude/skills/deploy/scripts/run.sh:2  skill-payload
          Downloads code and pipes it straight into a shell.
  ERROR   CLAUDE.md:4  secret
          Looks like an Anthropic API key. Instruction files are sent to the model on every session.
  ERROR   CLAUDE.md:6  injection
          An HTML comment carries an instruction. GitHub hides comments from reviewers but the agent reads them.
  WARNING CLAUDE.md:3  stale-reference
          `src/auth/middleware.ts` does not exist in this repository. The agent will look for it and guess.

It reads CLAUDE.md, AGENTS.md, GEMINI.md, Cursor and Copilot rules, every SKILL.md and the scripts beside it, subagents, hooks, memory files and MCP configs, for Claude Code, Cursor, Codex, Copilot and Gemini CLI. Free, open source, runs locally. Precision first: no known false alarms on the instruction files of 146 real-world repositories, every reference finding checked by hand, plus 4,292 registry files and 272 skill scripts. What it cannot see: docs/KNOWN-LIMITS.md.

---

🔥 The problem

Every coding agent reads a rules file first, on every prompt, and trusts it more than your code. Nobody reviews those files like code, and nothing enforces what they say.

1. They go stale, and the agent follows the stale file

In 320 runs across 40 projects, 90.1% of agent choices followed an outdated instruction file over the existing code. Claude Code noticed the conflict in 79 of 80 runs and followed the file anyway. One sentence telling the agent to prefer the code raised code-following from 4.2% to 91.4% (arXiv 2610.30571).

2. The rules vanish, and “never” is only a sentence

• After a session compacts, violations of the project’s own rules go from 0% to 30–59% (arXiv 2606.22528); the request to fix it upstream was closed not planned (claude-code#24460).
• In 481 public CLAUDE.md files, only 4.4–16% of security rules have a control that enforces them (arXiv 2608.23550). “Never force-push” is advice until something refuses the command.

3. They are an unguarded attack surface

• ~0.7% of public agent instruction files contain a live credential, mostly pasted by hand (Radware, Aug 2026), and mainstream secret scanners don’t watch these files.
• Shared rule files make agents install look-alike packages with 79% success across 8 agents and 13 models (arXiv 2610.09264); editing only a README or requirements file makes agents pull from attacker indexes (Microsoft, arXiv 2607.15143).
• Rule files are a working prompt-injection channel (Aletheia, 2026); skill scanners stop at SKILL.md, and every one tested was bypassed (CSA / Trail of Bits).

4. They bloat, and bloat costs accuracy

• Agent instruction files grow +226% over their lifetime, and noisy instructions cut instruction-following by 24 points (arXiv 2608.11095).
• 91 of the 100 most-starred repos have at least one configuration smell: leaked lint rules, bloat, dead references, contradictions, never-edited /init output (arXiv 2606.15828).

The fix: check every file the agent reads like you check code, keep the rules in context, turn the “never” lines into controls, and gate the installs. Every time, not once.

---

💊 What Agent.md does

---

🔁 Every time, not once

A linter you run once is a one-time fix. These files are read on every prompt, so Agent.md sits on the moments they fail:

flowchart LR
    S([Session start / compaction]) -- pin re-injects the hard rules --> A[Your agent]
    I([Every install the agent runs]) -- guard blocks look-alikes and bad indexes --> A
    N(["Every 'never' line"]) -- enforce compiles it to a deny rule --> A
    C([Every correction you repeat]) -- learn proposes it as a rule --> F[(CLAUDE.md · AGENTS.md · rules · skills)]
    F -- read on every prompt --> A
    P([Every pull request]) -- lint · enforce --check · cost --budget --> F
    R([Every dependency bump]) -- stale pins · drift · dead paths --> F

---

🚀 Quick start

1. Check every file your agent reads: works on any repository, nothing to install first

npx activate-agentmd lint

  ERROR   CLAUDE.md:14  secret
          Looks like an Anthropic API key. Instruction files are sent to the model on every session — rotate it, then read it from the environment.
  ERROR   .cursor/rules/deploy.mdc:3  injection
          An HTML comment carries an instruction. GitHub hides comments from reviewers but the agent reads them.
  WARNING CLAUDE.md:1  stale-pins
          The version pins in the agentmd block do not match the dependencies this project now runs.

  2 errors, 1 warning across 6 instruction files

2. Gate every install the agent runs

npx activate-agentmd guard --install

3. Keep the rules, and make “never” real

npx activate-agentmd pin --install      # hard rules survive /compact and resume
npx activate-agentmd enforce --write    # "never" lines become permissions.deny

  Enforcement  6 hard rules · 5 prohibitions · 4 enforceable · 0 enforced · 2 left to the model

  ! prose only CLAUDE.md:3  Never force-push.
               force pushes: Bash(git push --force:*), Bash(git push -f:*), Bash(git push --force-with-lease:*)
  ! prose only CLAUDE.md:4  Never edit `.env`.
               edits to `.env`: Edit(./.env)

  ! 9 deny rules would make the prose above enforced. `agentmd enforce --write` adds them to .claude/settings.json.

4. See what your context costs, and what it loads

npx activate-agentmd cost
npx activate-agentmd sbom --out bom.json

5. Detect the stack, pin breaking changes, install standards

npx activate-agentmd init
npx activate-agentmd link

  ✓ Next.js                  package.json (next)
  ✓ PostgreSQL               package.json (pg)
  ⇅ Next.js 16               node_modules (next 16.0.3)    (version pin)
  ⇅ Prisma 7                 package.json (@prisma/client ^7.0.0)

Recommended packages for claude:
  Security       authentication, owasp, sql-injection
  Database       postgres, prisma, indexes, migration
Install these? [Y/n]

link writes a managed block into whichever of CLAUDE.md, AGENTS.md, .cursor/rules, GEMINI.md and copilot-instructions.md your tools read. Commit .agentmd/ and the whole team gets the same rules.

6. Check a diff: deterministic, offline, zero tokens

npx activate-agentmd review --fast --fail-on=high

Or try it in the browser in 10 seconds at agentmd.tech/inspect: drop a package.json to see every major your agent will get wrong, or paste a CLAUDE.md to check it. Nothing is uploaded.

---

🧪 Try to sneak something past it

---

🧭 Why it’s different

Built to be trusted:

1. Neutral across vendors. One tool for the files every agent reads, signed with your key, not any vendor’s.
2. Deterministic, not model-judged. Every rule has a must-catch and a must-not-fire sample, tested in CI, and every new rule is diffed on real repositories before it ships. A gate that cries wolf gets switched off.
3. Evidence-first. A check, a pin or a standard ships when it is measured, not when it sounds right.

---

🔬 What the research says — and what we built

---

🏛 The pillars in depth

🔒 agentmd lint: the 26 checks

Injection rules read prose only, not code fences, inline code or lines that warn against the thing, so documentation about attacks doesn’t trip them. .claude/memory/*.md files are linted too.

📌 pin, ⛔ enforce, 🧠 learn

• pin picks the explicit rules first (mark one `` or put it under a ## Pinned heading), then the “never” lines, then the “must” lines, inside a token budget (--budget, default 600), and prints them back on every SessionStart after compaction or resume.
• enforce maps one-reading “never” lines to permissions.deny. Ambiguous lines stay prose and are reported, never guessed. --check exits 1 when a mappable rule is not enforced.
• learn reads your Claude Code session logs on your machine, groups corrections that say the same thing, and proposes the ones you gave more than once. --write appends them under a review heading.

🛡 agentmd guard

The gate sits between “the agent read an install command” and “it ran”. guard --install adds it to .claude/settings.json as a PreToolUse hook; the Claude Code plugin ships it on. Blocked installs come back to the agent with the reason, so it fixes the command or asks you.

sequenceDiagram
    participant A as Agent
    participant G as agentmd guard
    participant R as npm / PyPI / OSV
    A->>G: pip install reqeusts
    G->>G: shape check against your manifests and widely installed names
    G->>R: does it exist? how old? how used? known-vulnerable pin?
    G-->>A: blocked: reqeusts looks like requests but is not it
    A->>G: pip install requests
    G-->>A: allow

📋 agentmd sbom and 💸 agentmd cost

sbom --out bom.json writes CycloneDX 1.6 for the SBOM tools you already run. cost turns always-on tokens into dollars per developer per month and shows what lint --fix gives back; cost --budget 1500 is a CI gate.

⇅ Version pins

link writes the breaking changes for the majors you run, first in every agent file:

### Version pins (detected from this project)

**Next.js 16** — _node_modules (next 16.0.3)_
- Request APIs are async only — `params`, `searchParams`, `cookies()`, `headers()` must be awaited.
- `middleware.ts` is `proxy.ts`; the old filename is not picked up.

**Prisma 7** — _package.json (@prisma/client ^7.0.0)_
- No Rust query engine by default: instantiate the client with a driver adapter, not a bare `new PrismaClient()`.

Coverage: Next.js 13–16, React 18–19, Pydantic 1–2, SQLAlchemy 2, Django 5, Prisma 5–7, Tailwind 3–4, Express 5, Zod 4, ESLint 9, Vue 3, Go 1.22–1.25, Python 3.12–3.13. The installed version beats the declared range, so a lockfile bump from 15 to 16 is pinned as 16, and lint flags the block as stale until you run link.

🎯 On-demand standards

Each installed standard is written in the agent’s own scoped format, so it costs nothing until it’s relevant:

The Postgres standard costs nothing while you edit CSS. Overrides in .agentmd/overrides/ replace a registry standard with your team’s own text.

---

🏢 For teams: signed context

npx activate-agentmd bundle keygen --out ~/keys/agentmd.key --kid acme-2026   # private key never inside the repo
npx activate-agentmd bundle sign --key ~/keys/agentmd.key                     # writes .agentmd/bundle.sig
npx activate-agentmd bundle verify                                            # exit 1 on any change
npx activate-agentmd bundle attest                                            # commit + context digest, as JSON

  ✗  the files an agent reads have changed since the bundle was signed
     modified    CLAUDE.md
     unapproved  .cursor/rules/new-rule.mdc

• Covers every instruction file plus installed standards, overrides and policy; per-developer *.local.* files stay out.
• requireSignedContext: true in .agentmd/enterprise.json makes lint fail on any unsigned change.
• In CI, pin trusted keys from a secret (AGENTMD_BUNDLE_KEYS), otherwise a pull request could swap the key in the repo and re-sign. verify warns when it isn’t set.
• attest gives an auditor one record per build: the commit, a digest of every instruction in force, and whether it was approved.

Need a named reviewer’s approval bound to the exact files your agents read, checked on every pull request? See docs/team.md and agentmd.tech/pro.

---

🛡 Enforce it in CI

name: agentmd
on: [pull_request]
permissions:
  contents: read
jobs:
  agentmd:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npx --yes activate-agentmd lint                    # secrets, injection, drift, stale pins
      - run: npx --yes activate-agentmd review --base origin/${{ github.base_ref }} --fast --fail-on=high
      # - run: npx --yes activate-agentmd enforce --check      # optional: every mappable "never" is enforced
      # - run: npx --yes activate-agentmd cost --budget 1500   # optional: always-on tokens stay under budget

Zero tokens, no API key, nothing leaves the runner. Upload lint --sarif to GitHub code scanning to see findings inline. npx activate-agentmd ci --write generates this workflow for you.

---

🤖 Supported agents

Agent Skills. Two skills teach the agent to use the toolchain, agentmd-usage (install, pins, lint) and agentmd-standards (following what’s installed):

npx skills@latest add Aaditya1273/Agent.md -a claude-code -a cursor -y

MCP server. Search and read standards mid-task:

claude mcp add --transport http agentmd https://agentmd.pages.dev/api/mcp     # Claude Code
codex  mcp add agentmd --url https://agentmd.pages.dev/api/mcp                # Codex
gemini mcp add --transport http agentmd https://agentmd.pages.dev/api/mcp     # Gemini CLI

Cursor and VS Code: one click at agentmd.tech/connect.

---

📚 The registry

This repository is the registry: plain markdown, written once in _canonical/ and generated for 11 model families (Claude, OpenAI, Gemini, DeepSeek, Grok, Qwen, Kimi, GLM, MiniMax, Mistral, Sarvam): 308 standards in 21 categories for Claude, 304 for each other family.

npx activate-agentmd search "rate limiting"
npx activate-agentmd info Security/jwt
npx activate-agentmd install Database/          # a whole category
npx activate-agentmd install claude/Motion/lumen # make a launch film with Claude

Browse with logos and search at agentmd.tech. Full CLI reference: docs/cli.md.

---

🧾 Known limits

• Patterns, not verdicts. lint is deterministic pattern matching; a pass is a floor. Every gap is listed per rule in docs/KNOWN-LIMITS.md.
• pin and enforce are Claude Code only today. They use Claude Code’s SessionStart hook and permissions.deny; for Codex, Cursor and Gemini CLI they report “not covered” rather than pretend.
• guard runs where the agent has a command hook. Installs typed by hand are caught at review time by install-source and package-swap.
• Bundles are a CI and review gate, not runtime enforcement. They stop an unapproved file from merging unseen.

---

🤝 Contributing

Questions? Ask in the Agent.md Discord: about a standard, the CLI, or whether an idea is worth a pull request. No question is too small.

Standards are plain markdown in _canonical//.md. The bar: imperative, specific, short wrong/right code pairs, an anti-patterns table and a checklist, and evidence that the standard changes what a model writes (agentmd test --baseline prints it). A standard that doesn’t change the output isn’t a standard; it’s a file.

Hacktoberfest 2026: the open issues are scoped, markdown-only and need no build: new standards for Vue, Svelte, Angular, Rust, NestJS, Fastify and Java; upgrades of legacy packages; verification against React 19, Next 16, Prisma 7 and Tailwind 4. See CONTRIBUTING.md.

---

🗺 Roadmap

---

❓ FAQ

Is this a replacement for CLAUDE.md / AGENTS.md / Cursor rules? No. Those are file formats. Agent.md checks what’s in them, keeps them true to your code, and turns the rules into controls.

Isn’t a linter a one-time fix? The files are read on every prompt and change on every PR. pin runs on every compaction, guard on every install, ci on every pull request, learn whenever you repeat yourself, lint whenever a dependency or path moves.

Does it paste 30 standards into every prompt? No. Only version pins are always on. Standards load on demand, when the agent opens a matching file.

Does lint need Agent.md installed in the repo? No. npx activate-agentmd lint works on any repository with any agent instruction files.

Will it slow my agent down? guard and pin are hooks that run in milliseconds; pin stays inside the token budget you give it.

Does anything leave my machine? init, install, link, pins, lint, pin, enforce, learn, cost, sbom, bundle and review --fast run locally. lint --online and guard ask npm, PyPI and OSV about package names only. review (model mode), extract and test send the diff or evidence to the Anthropic API under your own key. Anonymous usage counters are off by default and opt-in (agentmd telemetry).

Does a pin actually change what a model writes? That is the right question, and it is being measured rather than assumed. Pins matter most when the model’s training predates the version you run. Results are published once they repeat on a second model.

---

License

MIT. Use it anywhere, including commercial projects, no attribution required.