agentleFS
Sign inStart free
DevolutionsDevolutions/IronRDP/.agents/skills/agents-md/SKILL.md

agents-md

Skill3.3k starsChanged 2 days agoApache-2.0View on GitHub

Discipline for writing and updating AGENTS.md (or CLAUDE.md) so it holds only what an agent cannot infer - policy, gotchas, and pointers - and stays under about 40 lines. Use instead of /init when creating, editing, or adapting one.

We split this skill into the rules it gives an agent

6 rules. 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 32 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Put positively: there is no way the agent learns this unless we write it.

    line 18
  2. Distinctive:

    Keep headings that organize the rules or add context.

    line 33
  3. Distinctive:

    Every AGENTS.md gets a sibling CLAUDE.md symlink to it, because Claude Code reads only CLAUDE.md.

    line 46
  4. Very specific:

    Verify every surviving sentence against the tree and the remote default branch.

    line 50
  5. Distinctive:

    When a line documents a workaround, fix the code instead.

    line 51
  6. Distinctive:

    When adapting another repository's file, report deviations with reasons instead of copying: a line true there may be false here.

    line 52

“Common” is measured: kept by at least 6 in 10 of the 32 edited versions of this file we could read. “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
SKILL.md

AGENTS.md is loaded on every task, so every line is a cost paid everywhere. Measured on real repositories (arXiv 2602.11988): developer-written files raised resolve rate about 4% and cost about 20%; LLM-generated files lowered resolve rate; repository overviews did not help. What helped agents was locating the right place to change, not writing better patches.

The test

A line earns its place when both hold:

Would it cost more than one cheap feedback round to discover and fix? Does no skill or always-read file already state it?

A lint or formatting miss costs one run of CI or of the repository's check command and is not worth a line; a testsuite written against the library instead of the CLI is a pile to redo, and is. Put positively: there is no way the agent learns this unless we write it.

What belongs, in order of value

  • A pointer to a non-standard layout: "Integration tests are centralized in testsuite; see testsuite/AGENTS.md."
  • The default feedback loop when it is not the ecosystem's default: "cargo xtask check-uncommitted verifies local modifications."
  • A policy with its reason: "Use #[expect(lint, reason = "...")] so the suppression explains itself and expires when it stops being needed."
  • Repository rules no tool enforces: intent-file handling, writing conventions for committed text, comment markers such as INVARIANT: and UNTESTED:.
  • The one fact a shared skill leaves to the repository, such as the issue-reference footer format, when it fits in a line; otherwise a repo-local skill.
  • One opener saying where skills live, for agents that do not discover them.

What /init generates is the blacklist: product overview, directory map, command lists, "follow standard conventions", inventories of packages or scopes, and lossy summaries of STYLE.md. Examples without the rule behind them are the costliest lines; agents copy the example, mistakes included.

Omit an opening banner that only repeats the repository, path, or body context, because it adds no guidance. Keep headings that organize the rules or add context.

Division of labour

AGENTS.md    always loaded     policy, gotchas, pointers
skill        loaded on match   rules for one task; may load the skills it builds on
STYLE.md     loaded by a reviewer skill when a rule's intent is unclear

The root file enters every context, so about 40 lines is the rule of thumb; a nested file loads for fewer tasks and may run longer; past the mark, flag it for the human rather than cut a gotcha to fit. Load each file at the latest point where it pays for itself; an always-loaded file pointing at a 700-line guide is a cost on every task, while a skill pointing at the one it depends on keeps both small. A directory with its own policy gets a nested AGENTS.md and one pointer from the root. Every AGENTS.md gets a sibling CLAUDE.md symlink to it, because Claude Code reads only CLAUDE.md.

Keeping it true

  • Verify every surviving sentence against the tree and the remote default branch; /init files go stale within weeks.
  • When a line documents a workaround, fix the code instead; the file is a list of smells not yet fixed.
  • When adapting another repository's file, report deviations with reasons instead of copying: a line true there may be false here.

references/before-after.md holds one 151-line file reduced to 27, with the reason each block was cut or kept and the maintainer's verbatim pushbacks; read it when unsure what counts as discoverable.

Download now (ZIP)

Trending

More talk lately.about the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 1 mentionMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 1 mentionJul 2026: 16 mentionsAug 2026: 1 mentionSep 2026: 15 mentionsOct 2026: 14 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the Devolutions/IronRDP repository that our weekly crawl found. There is no adoption data for this file yet.

Who's talking about Devolutions/IronRDP

The biggest 5 of 60 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 60

Talked about on GitHub, Bluesky and Hacker News (60 times).

On GitHub · 50

45 more on GitHub

On Bluesky · 9

4 more on Bluesky

On Hacker News · 1

Does it work?

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

Reviews can't be read right now.

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