agent-workspace
AGENTS.md0 starsChanged 24 days agoMITView on GitHub
The one instructions file for every AI agent that works in this folder, whatever the tool or model. Tools that look for their own file name point here (see CLAUDE.md). A folder of plain Markdown files holding the context, reasoning and decisions behind what the user is working on. It is organized by domain folders: each has a CONTEXT.md saying what is true in it right now and a DECISIONS.md logging what was settled and learned. The full spec is…
1 other project uses a version of this.
Adopted by
Most recently taken up by
- aminbadh/workspace-starterword for word, first seen Oct 22, 2026
Other versions1 project uses a version of this.
Word for word · 1
- aminbadh/workspace-starter★ 0100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
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.
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 32,671 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.
- CLAUDE.mdCLAUDE.md
- onboardSkill
- one-thingSkill
- upgradeSkill
- weekly-reviewSkill
The file
We split this AGENTS.md into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
Context first: Before answering anything about a domain, read its CONTEXT.md.
- Very specific: line 17
Check freshness before trusting a file: Every CONTEXT.md carries status and last_reviewed in its frontmatter:
- Very specific: line 22
Respect closed decisions: If a DECISIONS.md marks something closed, do not reopen or re-analyze it unless the user explicitly asks.
- Very specific: line 23
Update what you invalidate: If work in a session changes something a CONTEXT.md asserts, edit that file in the same session and bump its …
- Distinctive: line 59
Alone: read anything connected; create and edit files in this workspace.
- Distinctive: line 66
When updating a document, make the edit directly.
- Distinctive: line 67
Nothing is committed automatically: Leave changes in the working tree for the user to review unless they ask for a commit.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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
Workspace Instructions
The one instructions file for every AI agent that works in this folder, whatever the tool or model. Tools that look for their own file name point here (see CLAUDE.md).
What this workspace is
A folder of plain Markdown files holding the context, reasoning and decisions behind what the user is working on. It is organized by domain folders: each has a CONTEXT.md saying what is true in it right now and a DECISIONS.md logging what was settled and learned. The full spec is CONVENTIONS.md. Read it before creating or restructuring a domain, rather than copying the shape of a neighbour.
First, every session
- Read PROFILE.md. It says who the user is and what they are working on. Never ask for something it already answers.
- If PROFILE.md still says "Blank template", run the onboard skill before anything else, whatever the user asked; if it says "Onboarding in progress", resume it. Tell them it takes about fifteen minutes and makes every later answer specific to them.
Operating rules
- Context first. Before answering anything about a domain, read its
CONTEXT.md. Do not ask for information that is already written down. - Check freshness before trusting a file. Every
CONTEXT.mdcarriesstatusandlast_reviewedin its frontmatter:status: dormant: real, but not being worked. Never present its workstreams as live commitments. Say it is dormant.status: archived: finished. It lives under.archive/. Do not read it unless the user asks about it directly.last_reviewedolder than the file's review interval: say so rather than trusting it, for example "last verified on 3 March, treat the dates with caution." The linter reports what is overdue, so do not keep a threshold in your head.
- One fact, one home. A parent
CONTEXT.mdis an index of its children, not a summary. Never copy a deadline, decision or number from one file into another. Link to where it lives. If two files disagree, the more specific one wins and the other is a bug to fix. Never record state one command reveals (unpushed commits, what is deployed, build status). - Respect closed decisions. If a
DECISIONS.mdmarks something closed, do not reopen or re-analyze it unless the user explicitly asks. - Update what you invalidate. If work in a session changes something a
CONTEXT.mdasserts, edit that file in the same session and bump itslast_reviewed. Settled a decision? Append it toDECISIONS.md. Stale context is the main way this workspace fails. - Never invent a fact about the user, their work or the world. Ask, or say you do not know. A plausible default that a plan is then built on is an invented fact.
- Search the web for questions about the outside world. Whether a tool has an MCP server or connector, how to export from an app, the usual way to do something: search before answering or asking the user, and lead with the established solution rather than a homemade one.
- Links, not paths. Refer to other files with real Markdown links, never backticked paths. A link can be checked; a backticked path stays wrong forever.
What to do now
When the question is open (what should I do now, today or this week, I am stuck, I am behind), use the one-thing skill rather than ranking from memory. When the conversation is already on a topic, "what now" means within that topic. Do not volunteer commentary on the user's priorities when they have not asked.
The weekly pass that keeps these files true is the weekly-review skill. Run it when the user says it is review time or asks to plan the week, never unprompted.
Tasks
Not set up yet: the onboard skill writes where tasks live and how to reach them.
The boundary between tasks and these files is in CONVENTIONS.md.
Skills
Procedures the user asks for by name live as skills in .agents/skills/, linked into .claude/skills/ for Claude Code. Use them rather than improvising. Rules that must always hold stay in this file, because a skill only runs when invoked.
| Skill | Use it when |
| onboard | PROFILE.md is blank, the user wants to update their setup, or they want an add-on from addons/ |
| weekly-review | It is review time, or the user asks to plan the week |
| one-thing | The user asks what to do now with no topic in play |
| upgrade | The user asks to upgrade the workspace, or the weekly review reports template changes |
Working with me
Not set up yet: the onboard skill writes how the user wants the AI to work and write for them.
What the agent may do
A safe default, until onboarding asks the user what to change.
- Alone: read anything connected; create and edit files in this workspace; run its scripts and read-only commands; draft anything.
- Draft only, the user sends: emails, messages, posts and comments; commits and pushes; anything written to a task app or calendar, until the user says otherwise.
- Never: spend money or start paid jobs, enter or store credentials, delete anything outside this workspace.
Output
- Clean Markdown: headers, bold for key terms, tables for comparisons.
- When updating a document, make the edit directly. Do not describe what you would change.
- Nothing is committed automatically. Leave changes in the working tree for the user to review unless they ask for a commit.
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.

