architecture-skill
AGENTS.md0 starsChanged 4 months agoMITView on GitHub
This repository is the released architecture skill: the Shape stage of the Digital Product Skills family. The runtime skill lives under skills/architecture/; repository and plugin names use the -skill suffix. Version metadata lives in .codex-plugin/plugin.json, CHANGELOG.md, and tags — never in SKILL.md. The shape of a software system: service boundaries and coupling, API/event contracts, data architecture and consistency, NFR budgets (perf/SLO/capacity/cost), threat modeling and the auth/authz model, migration/deprecation strategy, and ADR governance — across web/SaaS, mobile, agentic/LLM systems, data platforms,…
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 repository13 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- site/llms.txtllms.txt
- mediabunnySkill
- remotion-best-practicesSkill
- remotion-captionsSkill
- remotion-createSkill
- remotion-docsSkill
- remotion-interactivitySkill
- remotion-markupSkill
- remotion-renderSkill
- remotion-saasSkill
- remotion-upgradeSkill
- architectureSkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
Run scripts/check-sync before any release.
- Very specific: line 28
Every method must be grounded in its named framework with a source in SOURCES.md.
- Very specific: line 30
Keep the boundary discipline: reference sibling territory by backtick name and recommend it.
- Very specific: line 32
Keep the eval contract current: evals/{activation,traversal,output,compression-ablation} must reflect the router.
- Very specific: line 34
Treat README as the primary storefront.
- Distinctive: line 41
Do not mark a change complete merely because lint passes.
≈ “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
Agent guide — architecture-skill
This repository is the released architecture skill: the Shape stage of the Digital Product
Skills family. The runtime skill lives under skills/architecture/; repository and plugin names
use the -skill suffix. Version metadata lives in .codex-plugin/plugin.json, CHANGELOG.md, and
tags — never in SKILL.md.
What this skill owns
The shape of a software system: service boundaries and coupling, API/event contracts, data
architecture and consistency, NFR budgets (perf/SLO/capacity/cost), threat modeling and the
auth/authz model, migration/deprecation strategy, and ADR governance — across web/SaaS, mobile,
agentic/LLM systems, data platforms, and internal tools. It sits between product (which decides
what to build and why) and the build skills (which write the production code). It owns the
decision, the contract, the budget, and the threat model — not the implementation. It recommends
siblings (design, frontend, backend, data, ai, quality, operate) for work it does not
own and never silently invokes them.
Maintainer rules
- Run
scripts/check-syncbefore any release; it validates packaging, routes, references, metadata, and eval fixtures. Runscripts/lint-skillandscripts/count-skill-tokenstoo. SKILL.mdis the direct router: a faceted table of one primary job × at most one surface overlay. References are flat underreferences/, directly linked, self-describing, and loaded only when their observable condition applies. No required second-hop navigation.- Requirements-gate before solutioning is load-bearing, not a nit: never propose a design before functional requirements and NFRs are captured and contradictions surfaced.
- Every method must be grounded in its named framework with a source in
SOURCES.md. Fix a wrong formula, a misattribution, or a license-posture error as a correctness bug, not a nit. - Keep the boundary discipline: reference sibling territory by backtick name and recommend it; never absorb design/frontend/backend/data/ai/quality/operate work.
- Keep the eval contract current:
evals/{activation,traversal,output,compression-ablation}must reflect the router. Add near-miss activation cases when a new sibling overlap appears. - Treat README as the primary storefront. The
site/andremotion/profiles follow thesite/README.mddesign brief — designed for this skill's faceted-router model inside the shared family chrome and its own accent, never a filled-in skeleton. - Release through matching plugin version + changelog entry +
v<version>tag + GitHub Release, and keep the GitHub About area configured (family-style description, canonical site alias as homepage, base + domain topics).
Do not mark a change complete merely because lint passes. Activation, traversal, and output evaluations must show the skill still changes agent behavior usefully.
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.

