How to write security guidance for AGENTS.md and Claude Code skills (and keep it current)
Summary
Most repos we look at have security guidance for coding agents somewhere. An AGENTS.md with a "Security" heading, a couple of Cursor rules, maybe a Claude Code skill someone wrote on a Friday.
Most of it says some version of "write secure code" and "follow OWASP", which changes exactly nothing about what an agent writes.
Guidance that works is specific to your codebase, short where it's always loaded, and kept current. This post covers what to put in it, where each agent looks for it, and why keeping it current is the part everyone underestimates.
Where each agent looks
If your team uses more than one agent, the same guidance ends up in four formats. That's usually where it starts to drift. Simon wrote up the history of how we got here in Guardrails vs Guidelines.
What to actually write
The guidance that changes agent behavior names your real code. Instead of "enforce access control", tell the agent that every query on billing, invoices or members filters by orgId using scopedQuery().
Instead of "handle secrets carefully", say keys come from process.env and never get hard-coded, including in tests and seed scripts (agents love seed scripts).
Cover how ownership works, which session check to call before reading data, what never gets logged, how outbound calls are made, and what to do before adding a package.
The best source material is your own history. Every vulnerability your team has fixed is a pattern your agents shouldn't write again. Here's what a short section can look like:
## Security
- Every query on billing, invoices or members filters by orgId. Use scopedQuery() from lib/db.
- Call requireTeamAdmin() before changing team membership or roles.
- Never log req.body, tokens or card data.
- Outbound HTTP calls go through safeFetch(), which only allows hosts in config/allowlist.ts.
- Read secrets from process.env. Never hard-code keys, including in tests and seed scripts.
- Ask before adding a new npm package.
Keep the always-loaded file short. Context windows fill up fast, and a two-page AGENTS.md gets skimmed by agents the same way it gets skimmed by people.
Put detailed guidance where it only loads for the code it covers: a subfolder AGENTS.md, a Cursor rule scoped to billing/**, or a Claude Code skill.
Why it goes stale
Guidance files get written once, usually by whoever cared most that week, and then the codebase moves on. A new service ships with a different auth pattern.
Someone renames scopedQuery(). Claude Code users get the new billing rule and Cursor users don't. Six months later nobody knows what's in the files or whether any of it is still true.
And even fresh guidance isn't a guarantee. OctoBench tested how well coding agents follow the instructions they're given across the system prompt, AGENTS.md or CLAUDE.md, and tool specs.
The models followed most individual rules, but rarely all of them at once: the best model followed every instruction in a task only 28% of the time, and Claude Sonnet 4.5 and Gemini 3 Pro managed about 15%.
Good guidance means fewer vulnerabilities get written. It won't get you to zero. You still want a security review on every pull request to catch the rest.
How Dam Secure keeps it current
This is the upkeep Managed Security Context takes off your plate. Dam Secure maps how your codebase works, from your auth patterns to how you handle data, and writes security context in the formats Claude Code, Cursor, Codex and GitHub Copilot read.
You review it as a pull request, and agents only load the guidance for the code they're touching. After that, the context keeps pace with your code. When a new service or auth pattern lands, the guidance covering it updates.
When a PR review finds a vulnerability, it becomes guidance that stops agents writing that pattern again, rolled out to every repo. Teams see 30% fewer vulnerabilities written.
"Dam Secure is not just a security partner, but a sage who can lead us to higher levels of maturity." Janyk Theron, Head of Engineering, Skip
FAQ
What is AGENTS.md?
A plain markdown file in your repo that gives coding agents instructions about your project. Codex and many other agents read it automatically.
Does Claude Code read AGENTS.md?
Claude Code reads CLAUDE.md. A lot of teams keep shared guidance in AGENTS.md and reference it from CLAUDE.md, so every agent works from one source.
Should security guidance go in AGENTS.md or a skill?
Short rules every change needs go in AGENTS.md or CLAUDE.md. Detailed guidance for one part of the codebase works better in a skill or a scoped rules file.
Want your agents' security context written and kept current for you? Speak to our team.
.webp)