oleg-chibikovoleg-chibikov/agent-skills/AGENTS.md

agent-skills

AGENTS.md1 starsChanged 2 months agoMITView on GitHub

Rules for anything under skills/. An agent reads these files on every run, so every line costs tokens on every run. The size caps are theirs alone, the rest holds for README.md and the instructions file too. install.sh is outside this. - skills/<name>/SKILL.md MUST hold the skill itself: frontmatter, then the steps in the order the agent does them. - Detail needed in one branch of the work only SHOULD move to skills/<name>/references/<topic>.md, and SKILL.md MUST carry a line saying…

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,542 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository5 other files it gives its agents.
- address-commentsSkill
- create-prSkill
- implement-ticketSkill
- reviewSkill
- writing-styleSkill

The file

We split this AGENTS.md into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Every rule MUST carry its own modal.
line 38
Distinctive:
Every rule carries a modal, and no line explains what the modals mean.
line 82
Very specific:
Every MUST reads true as "breaking this ruins the output".
line 83
Very specific:
No rule copied out of writing-style.
line 85

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

Writing the Markdown in this repo

Rules for anything under skills/. An agent reads these files on every run, so every line costs tokens on every run. The size caps are theirs alone, the rest holds for README.md and the instructions file too. install.sh is outside this.

Structure

skills/<name>/SKILL.md MUST hold the skill itself: frontmatter, then the steps in the order the agent does them.
Detail needed in one branch of the work only SHOULD move to skills/<name>/references/<topic>.md, and SKILL.md MUST carry a line saying when to read it.
writing-style owns every rule about words and layout. review and create-pr MUST load it and add only what is theirs. Other files MUST NOT copy a rule out of it.

Size

Counted in prose lines. Fenced blocks and blank lines are free, because the examples are the templates the agent copies.

File	Prose lines
`SKILL.md`	300
a reference file	60

python3 scripts/prose-lines.py skills/*/SKILL.md skills/*/references/*.md

Over the cap, a section SHOULD move to a reference file or go. Shrinking the wording comes second.

RFC 2119 words

Every rule MUST carry its own modal. No file MAY spend a line saying the words keep their RFC 2119 meaning, the reader knows them.

MUST, MUST NOT: breaking it ruins the output or the repo.
SHOULD, SHOULD NOT: the default, and it breaks only with a reason stated in the answer.
MAY: a real choice, both branches fine.
A step, a description or an example takes no modal: "Write three bullets", "Sort by severity".
One modal per sentence, and none inside an example block. Examples show, they don't legislate.

Prose

A rule SHOULD fit one line. Give the reason only where the agent gets it wrong without it.
Three or more rules MUST go in a list.
A section SHOULD stop at five bullets. Past that, split it under a heading.
A rule MAY carry one example, and a Bad and Good pair beats an explanation.
Articles and filler SHOULD go wherever the line still reads: "Read the repo rules first" beats "You should make sure to read the repo rules first".

Verbatim regions

Fenced blocks, inline backticks and links are templates the agent copies. Compressing or reformatting them changes the output. They MUST stay as they are unless the edit is about them.

Frontmatter

name MUST match the folder.
description MUST be one paragraph: when to use the skill, the words that trigger it, what comes out. It is all an agent sees before loading the file, so the trigger words matter more than the prose.

Language

The skills MUST be written in English.
LANGUAGE.md next to a SKILL.md names the language its output comes back in. The installer writes that file. A SKILL.md MUST NOT name a language itself.

Before you commit

scripts/prose-lines.py exits 0.
Every rule carries a modal, and no line explains what the modals mean.
Every MUST reads true as "breaking this ruins the output". The rest drop to SHOULD or lose the modal.
No rule copied out of writing-style.
Fenced blocks untouched unless the edit is about them.
The writing-style final checklist run over the prose.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free