Most AGENTS.md and SKILL.md files I have seen — including my own — read like onboarding documents for a new colleague. Long paragraphs, friendly explanations, gentle suggestions. That style fights against what these files are actually for: telling an LLM what it MUST do and what it MUST NOT do.

The idea for the fix was born in a workshop by Adam Bien. He did not propose it directly — he mentioned RFC 2119 in passing, alongside a broader point: old, boring, widely-cited standards are deeply absorbed into every LLM. You do not need to explain them. Drop the name and the model already knows the rules, the vocabulary, and the conventions that go with it. RFC 2119 is exactly that kind of standard. Write your agent instructions in its style — and just mention "RFC 2119" once in the file — and you get the IETF’s decades of precision for free.

The Problem with Prose

Prose instructions have two failure modes when an LLM reads them.

First, intent gets buried. "It would be great if you could try to use AsciiDoc source blocks where possible" is a polite request to a human and a coin flip to a model. Is it a rule? A preference? Optional? The LLM has to guess.

Second, files grow without bound. Every time the agent does something wrong you add another paragraph explaining context, rationale, exceptions — and maybe an example or two for good measure. Six months later the file is 400 lines of well-meaning suggestions and the model misses half of them.

The RFC 2119 Vocabulary

RFC 2119 defines a tiny set of keywords with precise meanings:

  • MUST / MUST NOT — absolute requirement / prohibition

  • SHOULD / SHOULD NOT — strong recommendation; deviate only with good reason

  • MAY — truly optional

That is the whole vocabulary. Five keywords, written in ALL CAPS so they stand out both to readers and to the model’s attention.

Before and After

Here is a typical prose rule from an early version of my CLAUDE.md:

When writing blog posts please make sure to use AsciiDoc format with
a `.adoc` extension. Every page needs YAML front matter at the top,
delimited by three dashes. The directory name should follow the
pattern of date plus slug, and the slug should be descriptive,
lowercase, and use hyphens between words.

Four sentences, friendly tone, easy to skim past. Rewritten with RFC 2119 keywords:

- You MUST write all content in AsciiDoc (`.adoc`)
- You MUST start every page with YAML front matter delimited by `---`
- You MUST name post directories `YYYY-MM-DD-slug` under `content/blog/posts/`
- You MUST use a descriptive, lowercase, hyphenated slug

Same rules. Fewer words. No ambiguity. The MUST keyword tells the model — and any future me — that these are not negotiable.

A Full Example

The CLAUDE.md that drives this very blog is written entirely in this style. A short excerpt from the content section:

- You MUST write all content in AsciiDoc (.adoc)
- You MUST use AsciiDoc section syntax (==, ===) for headings — NOT
  Markdown (#)
- You MUST use AsciiDoc source blocks for code and You MUST always
  specify the language
- You SHOULD prefer `layout: :theme/post` for posts, `layout:
  :theme/page` for standalone pages
- You MUST NOT duplicate author data in front matter when the author
  key can reference data/authors.yml

Notice the mix. MUST for structural rules the build will break on. SHOULD for things I want but can be relaxed for one-offs. MUST NOT for the failure mode I actually want to prevent.

The model picks up the gradient.

What This Buys You

Three things change when you rewrite an AGENTS.md or SKILL.md file this way.

Compactness. The file shrinks. My CLAUDE.md got noticeably shorter in the rewrite without losing a single rule. Shorter context means more room for the actual task.

Easier review. When every rule starts with one of five keywords, you can scan the file and immediately see what is a hard rule versus a preference. Adding a new rule forces you to pick a keyword, which forces you to decide how strict it really is.