srs-dd / skeleton
AGENTS.md0 starsChanged 32 days agoMITView on GitHub
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 repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- skeleton/CLAUDE.mdCLAUDE.md
- srs-arch-auditSkill
- srs-arch-harvestSkill
- srs-archSkill
- srs-auditSkill
- srs-baselineSkill
- srs-betSkill
- srs-buildSkill
- srs-checkSkill
- srs-commitSkill
- srs-harvestSkill
- srs-initSkill
- srs-newSkill
- srs-pageSkill
- srs-releaseSkill
- srs-reviewSkill
- srsSkill
- srs-upgradeSkill
The file
We split this AGENTS.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
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
- Very specific: line 35
Before changing behavior, find the requirements that describe it: python3 srs-dd/tools/srs_view.py --code <path/to/file>, or the tables in …
≈ “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
<Your Project Name> — agent guide
<SRS-DD-WIDTH-LINE>
<!-- srs-dd -->
A summary for coding agents; the project follows the SRS-DD standard.
On any conflict, `srs-dd/standard.md` wins — it is the single normative document on the specification.
System behavior is described in `specs/` as numbered requirements with links between them and references to code.- Specification rules —
srs-dd/standard.md, by section;python3 srs-dd/tools/srs_view.py --vocabularyprints the words a block may use. - The method's articles —
srs-dd/method.md(SRS-DD-ART-*), the framework's and the same in every project; the project's own principles arespecs/constitution.md(ART-*). Both apply to every task. - Markdown is not wrapped to a width — a line breaks where the meaning breaks, never inside a sentence; the renderer does the wrapping.
- Check —
python3 srs-dd/tools/srs_check.py. - Gate —
python3 srs-dd/tools/srs_gate.pyruns what the pipeline and the pre-commit hook run: the checkers, then every generated file compared with what git holds. - Read —
python3 srs-dd/tools/srs_view.py <ID>for one requirement with its links resolved,--code <path>for the requirements describing a file (--statementsadds what each obliges),<ID> --wherefor the lines that carry it (--sourceprints them),--areasfor what the specification is divided into,--openfor a page a non-engineer can read;.claude/skills/srs-page/SKILL.mdis the procedure around it. - Check a finished change —
.claude/skills/srs-check/SKILL.mdreads theverificationmethod and thetestsfield of every requirement the change touched, and offers exactly those; it runs nothing unasked. - Build over several passes —
.claude/skills/srs-build/SKILL.mdwrites what has to exist before the first pass and judges the work against that list, takes one requirement's worth of change per pass with its tests, classifies every failure before touching it, and closes the loop in the same set of edits. - Review a finished change —
.claude/skills/srs-review/SKILL.mdruns the checks the requirements call for, reads the work for what no check reaches, confirms every finding in the file it names before reporting it, and calls the work reviewed only on two consecutive passes that found nothing by different means. - Prepare a commit —
.claude/skills/srs-commit/SKILL.mdhands the change to the review and check procedures, establishes which files the message covers, puts the generated files in the index and names the requirement identifiers the change implements, bare, in a trailing parenthesis; it commits nothing itself. - Skills — the procedures in
.claude/skills/*/SKILL.mdare plain markdown; an agent without a skill system reads them directly as workflow guides. - Freeze a baseline —
python3 srs-dd/tools/srs_baseline.py X.Y.Zwrites the row intospecs/92-baselines.md; the commit that carries it is the baseline, and.claude/skills/srs-baseline/SKILL.mdis the procedure. Nothing here commits or tags for you. - Date requirements —
python3 srs-dd/tools/srs_dates.pywrites into each requirement the date its identifier first appeared in the history;--dry-runsays what it would write. Run on purpose, never by a gate. - Grounds register, where the project keeps
grounds/—python3 srs-dd/tools/srs_grounds.pychecks it and regeneratesgrounds/90-dashboard.md;--blast <path>says what the requirements behind a file stand on, and--htmlprints the dashboard as a page..claude/skills/srs-bet/SKILL.mdis the procedure. - Architecture layer, where the project keeps
arch/—python3 srs-dd/tools/srs_arch.pychecks it against the specification and regeneratesarch/90-map.md; a part stillproposedis a design, and--plansays what moving to it requires.python3 srs-dd/tools/srs_arch_doc.pyprints the layer as a document for a person, on request, and--htmlprints it as a page. A part may also say what it is made of inside, as forms inarch/20-shapes.md, designed from the obligations the part carries and compared with what that part's own code declares..claude/skills/srs-arch/SKILL.mdis the procedure;srs-arch-harvestrecovers a cut, or the forms inside a part, from a project that has one, andsrs-arch-auditjudges either. - Publish the pages —
index.html,arch.htmlandgrounds.htmlside by side (Published pages,srs-dd/standard.md);--linksays which others are beside a page, and it links exactly those, so none promises a page nobody rendered. - Upgrade the framework —
python3 srs-dd/tools/srs_upgrade.pyshows the version transition, the upgrade notes and the file list, then asks;.claude/skills/srs-upgrade/SKILL.mdis the procedure. No framework clone, no address to look up.
Two ways in
A question about how the system works starts with what this project wrote about itself — specs/00-glossary.md, specs/01-introduction.md, specs/02-overview.md: short, and in the project's own words, which a search over requirement text assumes you already know. Then --areas, then one area, then the requirement, then its code.
A change to behavior starts at the loop below.
The loop
- Before changing behavior, find the requirements that describe it:
python3 srs-dd/tools/srs_view.py --code <path/to/file>, or the tables inspecs/90-traceability.md. None exist — create one first, with the initial status per the Lifecycle section ofsrs-dd/standard.md. - Plans reference requirement IDs, not prose.
- Implement.
- Record what you chose: each way the change met a requirement that could have been met another way is a decision — Workflow in
srs-dd/standard.mdsays what counts — and goes intospecs/adr/; when there was none, the report says so. - Close the loop: status,
code,tests— in the same set of edits as the code. - Run the checker.
The rules most easily broken
- Changing behavior — first find or create the requirement, then write the code.
specs/90-traceability.mdis generated by a script; never edit it by hand.- Builds, tests, and every other action that SRS-DD-ART-030 of the method reserves run only with the user's explicit confirmation.
- Naming a record to a person — a requirement, a decision, and where the project keeps the layers an element or a grounds record: at its first mention in what the person reads as a whole (a message, a plan, a report), give its title, the file it is written in and its status, pasted from the tool, never typed:
python3 srs-dd/tools/srs_view.py --cite <ID>…printsFR-<AREA>-<NNN> — <its own title> (specs/<file>.md, <status>)and cites a decision by itsADR-NNNN;python3 srs-dd/tools/srs_arch.py --citeandpython3 srs-dd/tools/srs_grounds.py --citeprint the same form for an element and a register record. Afterwards the number alone is enough; insidespecs/,arch/andgrounds/the identifier is the name. A line a checker printed is run through--citebefore it is relayed. The rule holds in a table, a list, the steps of a plan and the report of any procedure — add the citation to a template that has no place for it. It is checked at sending: what was pasted is what the tool printed — no bold around it, no backticks around the file, nothing added inside the brackets. A mention in passing needs it too. A span named as a set —FR-<AREA>-010throughFR-<AREA>-090, a whole area — is one name, not a mention of each member. A commit message and the changelog are the exception and name identifiers bare, in a trailing parenthesis. A number the specification does not carry yet is a proposal, and is marked as one. - Reading the code behind a change — take the files from the
codeandtestsfields of the requirements the change belongs to (--code <path>answers from the other end), not from a search over the repository. Go wider where you must, and say where you went. - Reporting to a person — write in sentences that follow one another, and keep a list or a table for what the reader has to count or compare. A label with a fragment after it is a note to yourself. A report is not sent inside a code fence, which renders none of it. Say what happened and what follows from it in plain statements: no figure of speech where a plain verb exists, nothing about the work of writing the report, no clause whose only job is to join two of your own thoughts. Read the report once before sending it, delete what the reader cannot act on, and claim no action and no number that a tool result here does not show. Answer what was asked; a subject the task did not ask about goes in one line at the end, or not at all.
- Saying what the project's files say — read the source in the same message and match the sentence to it before sending, not to what you remember. A count is derived over the current files, a claim that something is nowhere written names what was searched, and a paraphrase is checked against the passage it paraphrases.
- Putting something to a person for a decision — a sentence for a document, a requirement's text, a step of a plan: the message that asks carries the text as it would be written, quoted in a block where it is long; "as shown above" sends the reader back through the conversation to find it.
- A rule the conversation settles — where something agreed will bind the work after this task is over and no requirement says it, offer to author the requirement, naming what it would oblige and the area it belongs to. Offered, never written: the maintainer decides whether it is written at all.
- A commit that alters behavior names the requirement identifiers it implements, bare, in a trailing parenthesis — SRS-DD-ART-060 asks the commit or the pull request for them, and the identifiers are the ones the change was planned from.
- Nothing sensitive goes into the repository (SRS-DD-ART-100) — no credentials, personal data, documents shared in confidence or traces of your machine. Read what is untracked before staging, and name a file that stays local in
.gitignorebefore writing it. - The procedure the project names for an act is the one used — a general procedure of your own that covers the same act only where the instruction named that one. Where it did, name the project's procedure for that act before following the instruction: the choice is the maintainer's, the naming is not.
<!-- /srs-dd -->This project
What agents working here must know beyond the method: where the code lives, how it is built and run, what is never done. Written by the project; the region above is the framework's and is refreshed by every upgrade.
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.

