Future-CXFuture-CX/AI-Architecture-Toolkit/AGENTS.md

AI-Architecture-Toolkit

AGENTS.md8 starsChanged 6 months agoMITView on GitHub

When creating agents, use the create-an-agent skill. When creating or updating agents: Do not add company-confidential information, customer names, internal system names, proprietary architecture details, credentials, or non-public business context to this repository. Use a separate private company lab repository for real-world testing. Generated artifacts that contain real company context belong in a private company lab repository, not in this public toolkit. This includes real glossaries, ADRs, capability overviews, target architecture documents, solution architecture designs, diagrams, roadmaps, and review findings.

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,774 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 repository17 other files it gives its agents.
- architecture-decision-recordSkill
- assess-solutionSkill
- capability-overviewSkill
- check-readabilitySkill
- create-an-agentSkill
- create-a-skillSkill
- create-drawio-diagramSkill
- data-architecture-designSkill
- grill-meSkill
- integration-designSkill
- problem-to-solutionSkill
- publish-to-confluenceSkill
- solution-architecture-designSkill
- target-architecture-documentSkill
- to-epicsSkill
- ubiquitous-languageSkill
- write-a-principleSkill

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

27 rules. About 1 is common, 22 are distinctive, and 4 are very specific to this project.

≈1
Common · estimate
Many files like this have a rule of this kind.
≈22
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

Distinctive:
When creating agents, use the create-an-agent skill.
line 3
Distinctive:
When creating or updating agents:
line 5
Distinctive:
Update the Agents table in the top-level README.md.
line 7
Very specific:
Update the public homepage at www/index.html when the visible agent list or agent positioning changes.
line 8
Very specific:
Keep agent briefs under agents/.
line 9
Distinctive:
Do not create real-company agent variants in this public repository.
line 10
Common:
Do not add company-confidential information, customer names, internal system names, proprietary architecture details, credentials, or …
line 16
Distinctive:
When creating stakeholder-facing documents:
line 24
Distinctive:
Treat non-technical business stakeholders as the primary audience.
line 26
Distinctive:
Start with the business outcome, the decision or recommendation, and the operational impact.
line 27
Distinctive:
Use plain language first. Add technical detail only when it changes a decision, risk, cost, ownership, timeline, or support model.
line 28
Distinctive:
Prefer short sentences, short paragraphs, clear headings, and concrete trade-offs.
line 29
Distinctive:
Prefer short sections and bullet lists over tables.
line 30
Distinctive:
Use a table only when it makes a compact comparison, repeated field mapping, or index materially easier to scan.
line 31
Distinctive:
Keep dense implementation detail in later sections or appendices after the stakeholder summary.
line 32
Distinctive:
Avoid unnecessary technical jargon.
line 33
Distinctive:
Before finishing, reread the opening sections and simplify any sentence that a business reader would need to parse twice.
line 35
Distinctive:
When creating principles, use the write-a-principle skill.
line 39
Distinctive:
When creating capability overviews, use the capability-overview skill.
line 45
Distinctive:
When creating solution architecture designs, use the solution-architecture-design skill.
line 51
Distinctive:
When a solution architecture design creates diagrams:
line 55
Distinctive:
When creating target architecture documents, use the target-architecture-document skill.
line 64
Distinctive:
When creating skills, use the create-a-skill skill.
line 70
Very specific:
When updating skills, also update the public homepage at www/index.html if the visible skills list or skill positioning changes.
line 78
Distinctive:
Use existing templates before creating new ones.
line 82
Distinctive:
When changing a template, update the owning skill instructions so future generated documents replace placeholders completely and do not …
line 84
Very specific:
When a template change affects public-facing behavior, update the top-level README.md and www/index.html if needed.
line 86

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

AGENTS

When creating agents, use the create-an-agent skill.

When creating or updating agents:

Update the Agents table in the top-level README.md.
Update the public homepage at www/index.html when the visible agent list or agent positioning changes.
Keep agent briefs under agents/.
Do not create real-company agent variants in this public repository.

EXAMPLES

GOVERNANCE

Do not add company-confidential information, customer names, internal system names, proprietary architecture details, credentials, or non-public business context to this repository. Use a separate private company lab repository for real-world testing.

Generated artifacts that contain real company context belong in a private company lab repository, not in this public toolkit. This includes real glossaries, ADRs, capability overviews, target architecture documents, solution architecture designs, diagrams, roadmaps, and review findings.

Toolkit-aware scripts and agents should honor .toolkitignore when deciding what counts as active toolkit content.

READABILITY

When creating stakeholder-facing documents:

Treat non-technical business stakeholders as the primary audience.
Start with the business outcome, the decision or recommendation, and the operational impact.
Use plain language first. Add technical detail only when it changes a decision, risk, cost, ownership, timeline, or support model.
Prefer short sentences, short paragraphs, clear headings, and concrete trade-offs.
Prefer short sections and bullet lists over tables. Tables are often harder for people to read, especially when cells contain full sentences or detailed explanations.
Use a table only when it makes a compact comparison, repeated field mapping, or index materially easier to scan. Move detailed explanation into prose, bullets, or an appendix.
Keep dense implementation detail in later sections or appendices after the stakeholder summary.
Avoid unnecessary technical jargon. Explain acronyms and domain-specific terms when first used.
Make recommendations, decisions, owners, risks, and open questions easy to find.
Before finishing, reread the opening sections and simplify any sentence that a business reader would need to parse twice.

PRINCIPLES

When creating principles, use the write-a-principle skill.

Generated principle documents belong under principles/ in the consuming repository. Do not add company-confidential principle examples to this public toolkit.

CAPABILITIES

When creating capability overviews, use the capability-overview skill.

Generated capability overviews belong under capabilities/<slug>/ in the consuming repository. Do not write real company capability context into this public toolkit.

SOLUTION ARCHITECTURES

When creating solution architecture designs, use the solution-architecture-design skill.

Solution architecture design outputs belong under solution-architectures/<slug>/ in the consuming repository, or under the private lab root when this toolkit is used as a submodule.

When a solution architecture design creates diagrams:

Store each Draw.io source as a separate .drawio file under the design document's diagrams/ subfolder.
Export a same-basename .svg file into the same diagrams/ subfolder for every .drawio file when the diagram must be embedded.
Embed the .svg file in the design document.
Link the .drawio source near the embedded SVG.

When creating any Draw.io diagram, use the create-drawio-diagram skill because it contains the diagram instructions, style rules, and templates. Always store generated .drawio files and same-basename .svg exports under a diagrams/ subfolder next to the document they support. Do not place diagram files beside the document.

When creating target architecture documents, use the target-architecture-document skill.

SKILLS

Skills are organized as folders under skills/.

When creating skills, use the create-a-skill skill.

Each skill entry in the top-level README.md must link the skill name to its SKILL.md.

The skills/README.md file must list every skill with a one-line description and link the skill name to its SKILL.md.

Each skill folder should include a README.md when the skill needs local usage notes, templates, scripts, or resources explained outside SKILL.md.

When updating skills, also update the public homepage at www/index.html if the visible skills list or skill positioning changes.

TEMPLATES

Use existing templates before creating new ones.

When changing a template, update the owning skill instructions so future generated documents replace placeholders completely and do not leave drafting guidance in final artifacts.

When a template change affects public-facing behavior, update the top-level README.md and www/index.html if needed.

Download now (ZIP)

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

What did you use it for? e.g. Reviewing pull requests in a Rails app

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.

Check your setup, free