agent-os
AGENTS.md0 starsChanged 4 months agoMITView on GitHub
Agent-OS is a public, filesystem-first starter for agent-assisted knowledge work. Claude Code, Codex, and generic file-capable agents operate the same portable state. Git and external integrations are optional. 1. README.md for public orientation. 2. agent-os.yaml for instance identity and state configuration. 3. docs/agent-guide.md for detailed routing. 4. docs/state-protocol.md before creating or changing operating state. 5. library/guides/maintainer-workflow.md for repo-wide maintenance or release work. - The nearest AGENTS.md governs files beneath it. - AGENTS.md and neutral docs own policy. - Skills own…
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 repository35 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- briefSkill
- closeoutSkill
- decisionSkill
- deskSkill
- doctorSkill
- editorSkill
- grillSkill
- handoffSkill
- morningSkill
- openSkill
- recentSkill
- researchSkill
- rfcSkill
- setupSkill
- shapeSkill
- specSkill
- weekly-reviewSkill
- briefSkill
- closeoutSkill
- decisionSkill
- deskSkill
- doctorSkill
- editorSkill
- grillSkill
- handoffSkill
- morningSkill
- openSkill
- recentSkill
- researchSkill
- rfcSkill
- setupSkill
- shapeSkill
- specSkill
- weekly-reviewSkill
The file
We split this AGENTS.md into the rules it gives an agent
12 rules. About 1 is common, 10 are distinctive, and 1 is very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
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
- could be automatic: a setting could enforce it
- Distinctive: line 22
When instructions conflict, preserve user data and ask before destructive action.
- Distinctive: line 39
Do not recursively ingest desk, memory, state, or library.
- Distinctive: line 54
Never duplicate current status across a binder, workstream, handoff, and memory file.
- Distinctive: line 61
Read and re-check the workstream revision before writing.
- Distinctive: line 62
Stop if the revision changed.
- Distinctive: line 65
Create a uniquely named immutable receipt after a successful transition.
- Distinctive: line 74
Keep shipped examples coherent, fictional, and free of personal data.
- Distinctive: line 75
Use only workspace-relative paths in portable files.
- Common: line 76
Do not write secrets, raw transcripts, prompts, tool arguments, hostnames, or private URLs to portable state or receipts.
- Distinctive: line 87
Do not refactor, rename, or reformat unrelated material.
- Distinctive: line 88
Ask before deleting files, replacing divergent state, moving whole binders, publishing externally, rewriting history, or removing examples.
- Very specific: line 101
When Git is present, also run git diff --check.
≈ “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.
Files
Agent-OS
Agent-OS is a public, filesystem-first starter for agent-assisted knowledge work. Claude Code, Codex, and generic file-capable agents operate the same portable state. Git and external integrations are optional.
First reads
- README.md for public orientation.
- agent-os.yaml for instance identity and state configuration.
- docs/agent-guide.md for detailed routing.
- docs/state-protocol.md before creating or changing operating state.
- library/guides/maintainer-workflow.md for repo-wide maintenance or release work.
Instruction precedence
- The nearest AGENTS.md governs files beneath it.
- AGENTS.md and neutral docs own policy.
- Skills own procedures and must defer to the nearest repo policy.
- CLAUDE.md is only a runtime shim.
- When instructions conflict, preserve user data and ask before destructive action.
Progressive disclosure
Load the smallest useful context:
| Topic | Read first |
| Named project | desk/<project>/BINDER.md |
| Current execution | The binder-linked state/workstreams/<slug>/WORKSTREAM.md |
| Priorities or commitments | areas/<area>/ |
| Writing preferences | library/reference/me.md and writing-guide.md |
| Prior rationale | memory/decisions/ |
| State mechanics | docs/state-protocol.md |
| Generic runtime operation | docs/generic-agent-guide.md |
Do not recursively ingest desk, memory, state, or library.
Owner-of-record invariants
- desk/ holds binders and project artifacts. Every active project directory has a BINDER.md.
- areas/ holds durable domain context, plans, and commitments.
- state/workstreams/ is the sole owner of resumable execution state and one
next action; a closed workstream uses
None — closed.instead. - state/receipts/ is immutable best-effort evidence, never current state.
- state/handoffs/ is optional and boundary-only.
- memory/ holds curated decisions, corrections, reviews, and portable lessons.
- Credentials, raw transcripts, indexes, caches, locks, and logs live in the external local-state path derived from agent-os.yaml.
Never duplicate current status across a binder, workstream, handoff, and memory file. Link to the owner instead.
State writes
Agent-OS v1 is sequential single-active-writer:
- Read and re-check the workstream revision before writing.
- Stop if the revision changed; never silently merge or overwrite.
- Increment revision once and leave exactly one next action, or the exact
None — closed.sentinel when closing the workstream. - Create a uniquely named immutable receipt after a successful transition.
- Preserve every cloud-conflicted copy and follow library/guides/cloud-sync.md.
Git is optional. Core workflows must still work when .git and the Git executable are absent.
Public and privacy guardrails
- Keep shipped examples coherent, fictional, and free of personal data.
- Use only workspace-relative paths in portable files.
- Do not write secrets, raw transcripts, prompts, tool arguments, hostnames, or private URLs to portable state or receipts.
- Setup must preview replacement of demo content and must not overwrite global runtime settings or unowned skills.
- External systems are optional context, never the only home of portable operating truth.
Working style
- Define the observable done state before editing.
- Make the smallest change that satisfies it.
- Do not refactor, rename, or reformat unrelated material.
- Ask before deleting files, replacing divergent state, moving whole binders, publishing externally, rewriting history, or removing examples.
- Report verification that ran and anything that could not run.
Verification
Run:
python3 library/scripts/agent_os_doctor.py --strict
python3 library/scripts/audit_public_hygiene.pyWhen Git is present, also run git diff --check. For state changes, validate the required schema and relative links described in docs/state-protocol.md.
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.