agents-md
Skill1 starsChanged 2 months agoMITView on GitHub
Create, audit, or update portable project instructions that give coding agents durable project intent and proven operational guidance. Use explicitly for AGENTS.md or equivalent agent instruction files, not coding standards or task plans.
37 other projects use a version of this.
Adopted by
Most recently taken up by
- pantheon-org/tekhnetheir own version, first seen Nov 15, 2026
- Integralist/agent-skillstheir own version, first seen Nov 14, 2026
- arfar-x/agent-skillstheir own version, first seen Nov 14, 2026
- Rvey/agent-engineering-kittheir own version, first seen Nov 11, 2026
- eugeniughelbur/agents-mdtheir own version, first seen Nov 10, 2026
- caidanw/skillstheir own version, first seen Nov 8, 2026
Used with
Projects with it also use jira, improve-codebase-architecture and 1 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MicrosoftSkilljira
Jira issue workflows for search, issue updates, transitions, comments, field discovery, and interactive credential setup via the Jira REST API. Use when you need to configure Jira access, search with JQL, inspect an issue, create or update work items, move an issue between statuses, post comments, or discover required fields for issue creation.
Also in 3 projects that use this
GoogleSkillimprove-codebase-architecture
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
Also in 3 projects that use this
GoogleSkillcode-review
Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.
Also in 5 projects that use this
Other versions37 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 37
- agent-substrate/substrate★ 6.9ksame name
- Devolutions/IronRDP★ 3.3ksame name
- getsentry/skills★ 1.2ksame name
- mblode/agent-skills★ 203same name
- cumbucadev/cinemaempoa★ 145same name
- devbrother2024/skills★ 91same name
- Integralist/agent-skills★ 29same name
- arfar-x/agent-skills★ 14same name
- eugeniughelbur/agents-md★ 13same name
- getsentry/webvitals.com★ 12same name
27 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository34 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adrSkill
- architectSkill
- bug-huntSkill
- coding-standardsSkill
- deliverSkill
- diagnosing-bugsSkill
- gardenSkill
- howSkill
- program-designSkill
- prototypeSkill
- pruneSkill
- refineSkill
- researchSkill
- retroSkill
- setup-verificationSkill
- shapeSkill
- shipSkill
- skill-guideSkill
- spikeSkill
- strategic-programmingSkill
- walkthroughSkill
- whySkill
- adaptSkill
- editorSkill
- issueSkill
- pr-descriptionSkill
- pr-reviewSkill
- writing-for-peopleSkill
- grillingSkill
- unslopSkill
- wait-whatSkill
- writing-for-agentsSkill
The file
We split this skill into the rules it gives an agent
1 rule. 0 are common, 1 is distinctive, and 0 are very specific to this project.
0
Common
Most of the 33 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Choose the right owner: Keep project-compass prose and operational guidance here only when they should shape an agent during active work.
“Common” is measured: kept by at least 6 in 10 of the 33 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.
Files
Agents.md
Maintain one concise project brief that helps an agent understand what the project is trying to become, how its authors think, and which recurring mistakes it must avoid while working.
Process
- Set the scope. Identify the project root, creation, audit, or update intent, target language, and actual harnesses in scope. Read their applicable instruction files and resolve discovery and precedence from local behavior or current official documentation. Use root
AGENTS.mdas the canonical default, but preserve an established portable source. Do not assume filenames, nesting, imports, or symlink support across harnesses. - Inspect maintained evidence. Read only enough README, product vision, glossary, ADRs, contributor guidance, configuration, code, and existing instructions to find authoritative owners, contradictions, and facts the human should not have to supply. Current implementation proves what exists; it does not establish what the project should become.
- Resolve the project compass. Obtain concise accepted meaning for the project's purpose, intended users, desired direction, protected qualities, material tensions, and the author's decision heuristics or desired relationship with agents. Prefer an authoritative maintained source or intent already supplied by the user. When material human-owned gaps remain, use
grillingif available, bounded to only those gaps; otherwise ask the minimum focused questions directly. Do not interview again when the compass is already sufficient, and do not invokegrillingfor an ordinary focused audit or update. - Identify operational scars. Retain only concrete guidance supported by an existing accepted instruction, an explicit human decision, or a demonstrated recurring agent failure. Inspect conversation or harness history only when the user authorizes that source and scope. A one-off mistake or hypothetical risk is not enough.
- Choose the right owner. Keep project-compass prose and operational guidance here only when they should shape an agent during active work. Route without modifying other material:
- machine-checkable behavior belongs in executable configuration or CI;
- reviewer-judged project rules belong in the canonical coding-standards source;
- feature requirements and implementation state belong in temporary work artifacts;
- architecture, domain meaning, and durable decision rationale belong in their maintained sources, with a short conditional pointer here only when an agent must consult them.
- Propose the smallest artifact or delta. Explain what each retained passage changes in agent behavior and why this file is its best owner. Prefer a short natural project letter for the compass and direct instructions with safe alternatives for operational scars. Delete stale, duplicated, generic, speculative, or now-enforced guidance. Do not imitate another author's voice or force a template.
- Obtain acceptance. Present the complete proposed content or exact delta, canonical path, target language, harness coverage, and portability limits. Write only after explicit human acceptance. A correction is accepted only after its effect on the draft is clear.
- Write and verify. Preserve unrelated instructions and apply only the accepted change. Create the smallest verified adapter, import, or link only for a named target harness that cannot consume the canonical source directly. Reread every resulting file, resolve its pointers, and verify that the diff contains no contradictory copies or unrelated changes.
Content filter
Useful content can include:
- a compact explanation of what the project exists to accomplish, for whom, and why that should affect implementation choices;
- product qualities and tensions the agent must preserve when several solutions appear valid;
- the author's durable decision heuristics and expectations for collaboration;
- how the team shares work, which
shapeandshipfollow: the tracker for its issues, where it keeps plans for people, and the language its shared work is written in; - recurring hazards with the condition that activates them and a concrete safe path;
- cross-surface obligations or vocabulary needed on nearly every relevant task;
- conditional pointers that name both the maintained source and when to read it.
Exclude:
- script, dependency, framework, directory, or file inventories that repository inspection can recover;
- development commands already discoverable from package, build, task, or CI configuration;
- formatter, linter, type, test, or review rules owned by executable tooling or coding standards;
- feature specifications, implementation slices, current progress, temporary exceptions, and exhaustive architecture summaries;
- a duplicated glossary or ADR history when a conditional pointer is sufficient;
- generic engineering advice, agent capability descriptions, personal preferences unrelated to this project, and instructions added without accepted authority;
- compatibility files for harnesses the user did not place in scope.
Outcomes
No instructions needed: no durable project compass or operational delta earns always-loaded context, so no file is created.No changes needed: the existing instruction chain is current, concise, correctly owned, and portable for the requested harnesses.Agree-ready: one complete artifact or minimal delta is ready for human acceptance; no file has changed.Updated: the accepted change was written and verified at the reported paths.Inconclusive: name the exact intent, authority, ownership, or harness-discovery conflict and its unblock condition.
Completion criteria
Every resulting instruction either communicates accepted project intent that implementation cannot determine or prevents a demonstrated recurring operational failure. The human accepted its meaning, language, path, and harness scope; stronger owners were not duplicated; and every named harness receives one consistent canonical instruction set through verified discovery.
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
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.

