blueprint
Skill0 starsChanged 3 months agoMITView on GitHub
Scores this workspace out of 100 on how well it is built — routing, precedence, freshness, and the maintenance loop — and names the three highest-leverage fixes with the exact command for each. Fires on "run blueprint", "score my setup", "is my AIOS built right", "grade my workspace", "how solid is my context setup", "give me a score out of 100", "rate how this thing is organized", and on complaints like "everything is up to date and my agent still gets things wrong", "this is just a pile of markdown files and I don't know if it's any good", or "I set this up months ago and I have no idea if it's still put together right". Also fires when the operator asks what to fix first, or wants to see whether last month's fixes moved the number.
73 other projects use a version of this.
Adopted by
Most recently taken up by
- mapsa/claude-skillstheir own version, first seen Nov 16, 2026
- laceyp99/skillstheir own version, first seen Nov 16, 2026
- hmohammed7/claude-skillstheir own version, first seen Nov 16, 2026
- akshay-diwadkar/first-four-hourstheir own version, first seen Nov 16, 2026
- AndresArreguy/ecc-pi-porttheir own version, first seen Nov 16, 2026
- ckaico/reversiumtheir own version, first seen Nov 15, 2026
Used with
Projects with it also use assess, continuous-agent-loop and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
AWSSkillassess
Run a 5-domain CAF security posture assessment for an AWS service. Produces (1) assessment-summary.md — CAF-structured findings with GAPS tables, (2) sar-facts.json — extracted SAR data, (3) checkpoint-results.json — factual checkpoint verification. These feed into the research, validate, and generate phases.
Also in 4 projects that use this
junimnjwSkillcontinuous-agent-loop
Patterns for continuous autonomous agent loops with quality gates, evals, and recovery controls.
Also in 3 projects that use this
marylinSkillalign
Audit project structure, docs health, and lifecycle compliance. Use when a project feels disorganized, after major refactors, before onboarding a contributor, or periodically as a health check.
Also in 3 projects that use this
sahinSkillexecute
Also in 5 projects that use this
LangChainSkilldocker-patterns
Best practices for Docker containerization and multi-stage builds
Also in 3 projects that use this
royaluniondesign-sysSkillsearch-first
Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. Invokes the researcher agent.
Also in 3 projects that use this
Other versions73 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 73
- WordPress/agent-skills★ 2.3ksame name
- hyperlink-academy/leaflet★ 527same name
- astronomer/agents★ 459same name
- loulanyue/awesome-claude-notes★ 272same name
- Joonghyun-Lee-Frieren/oh-my-gemini-cli★ 218same name
- Joonghyun-Lee-Frieren/oh-my-antigravity★ 214same name
- team-attention/hoyeon★ 173same name
- Fmarzochi/EGC★ 61same name
- smilewilson1999/blueprint★ 58same name
- manusco/resonance★ 38same name
63 more not listed
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.
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. 0 are common, 10 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 70 edited versions we read keep these.
10
Distinctive
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: line 19
Take the inventory before scoring anything: Read CLAUDE.md in full — its routing map, its precedence table, its automation table.
- Distinctive: line 33
Never run a git command in this skill.
- Distinctive: line 38
Every first-level folder on disk has a row in the routing map.
- Very specific: line 39
Every path the map names exists on disk.
- Distinctive: line 40
No row points somewhere that exists but holds something else — a row that sends you to the wrong real place is worse than a missing row, …
- Very specific: line 54
No status that a task tool owns is written into a file.
- Very specific: line 56
No money or runway figure anywhere in context/.
- Distinctive: line 87
Every automation that writes files has a row in the manual's automation table.
- Distinctive: line 95
Convert findings to a band. Use only these six values: No half points, no 22.
- Distinctive: line 109
If two or more distinct findings land in that same band, drop exactly one step (25→20→15→10→5→0).
- Distinctive: line 112
Write down the finding that set each band.
- Very specific: line 121
Every fix ships with the exact command or the exact edit.
- Distinctive: line 169
Never run a
gitcommand: Not to check history, not to check status. - Distinctive: line 170
Never score an axis you did not run the commands for: If a command fails, say the axis is unscored and why.
“Common” is measured: kept by at least 6 in 10 of the 70 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Blueprint
The failure this prevents: a workspace that is full and current and still structurally wrong — no map, the same number living in four files, and no loop keeping any of it honest. It reads as healthy right up to the session where the agent answers confidently out of a stale copy, and nothing in the system was ever going to catch that.
/os-audit asks whether the workspace is still true. This asks whether it is built
right. A workspace can score 95 here and be full of stale facts; it can be perfectly current
and score 40 because nothing holds it together. Run both.
Procedure
Take the inventory before scoring anything. Read
CLAUDE.mdin full — its routing map, its precedence table, its automation table. Then collect the ground truth you will score it against. Run every command; do not score from memory of the manual.ls -d */ | grep -v '^\.' # every first-level folder on disk ls .claude/skills/ # skills that actually exist wc -l context/*.md # size of the always-loaded layer cat .claude/settings.json # is the hook wired ls -lt reports/ | head -20 # what the loop has produced tail -20 decisions/log.md # is the log alive find . -path ./archives -prune -o -name '*.md' -mtime -30 -print # what moved this monthNever run a
gitcommand in this skill. Use file modification times. A workspace cloned yesterday has one commit and thirty files older than the clone — git history scores it wrong every time.- Score Routing (25). Is there a map, and does it point at things that exist?
- Every first-level folder on disk has a row in the routing map. Count the ones that don't.
- Every path the map names exists on disk.
test -eeach one. Count the dead paths. - No row points somewhere that exists but holds something else — a row that sends you to the wrong real place is worse than a missing row, because you stop looking.
- Each wiki-shaped folder (
knowledge/external/,knowledge/playbook/) has anindex.md. - 15 vs 10: one folder on disk the map never mentions, everything else resolving, is a 15 — one real gap. Half the folders unmentioned, or a whole named layer whose rows point at directories nobody ever created, is a 10 — the map is describing a workspace that only partly exists.
- Score Precedence (25). Does each fact live in exactly one place?
CLAUDE.mdhas a precedence table naming an owner for each contested class of fact.- Pick the distinctive strings out of the owned files — the quarter's target numbers, dated
goals, headcount — and grep for them everywhere else:
grep -rn "<the number>" --include='*.md' . | grep -v '^./archives'. Every hit outside the owner is a copy. - No status that a task tool owns is written into a file. Grep for status words
(
in progress,won,closed,blocked) attached to named projects outsidereports/. - No money or runway figure anywhere in
context/. - Nothing enumerates what the disk owns — a written list of "the skills we have" or "our projects" is a copy that goes stale the next time someone adds one.
- 15 vs 10: one number copied into one second file — the quarter target repeated in a project README — is a 15. No precedence table at all, or a whole class of fact routinely duplicated (every project file restating status the task tool owns), is a 10: the discipline isn't implemented, it just hasn't bitten yet.
- Score Freshness (25). Is what gets preloaded every session still true?
- The four
@imported files exist and none carries a demo banner:grep -rl "DEMO" context/. A demo string in the always-loaded layer ispoisoningby construction — it is false in every session forever. - No
context/file untouched for more than 60 days:find context -type f -mtime +60. - The always-loaded layer stays small. Over ~200 lines total across the four files is
bloat— flag it; over ~400 it is a real finding. - Each
index.mdis at least as new as the newest node beside it:ls -lt knowledge/external/ | head -5. A frozen index means nodes exist that nothing points at. - 15 vs 10: one always-loaded file untouched past 60 days while the other three are current is a 15. The demo still installed in one or two of the four, or an index frozen since scaffolding while nodes kept arriving, is a 10 — the layer is partly somebody else's workspace.
- The four
- Score Loop (25). Can the system repair and grow itself — and is it actually running?
Both halves count. Machinery that exists and never fires scores the same as machinery that
was never built.
.claude/settings.jsonwires theSessionStarthook, and the script it names exists and exits 0:sh scripts/aios-freshness-check.sh; echo "exit=$?".- An audit report inside 60 days:
find reports -name 'os-audit-*' -mtime -60. - A skill added or edited inside 30 days:
find .claude/skills -name SKILL.md -mtime -30. decisions/log.mdhas an entry inside 30 days.- Every automation that writes files has a row in the manual's automation table. An undocumented one scores as a finding here — output arrives, nobody knows from where, and nobody notices when it stops.
- 15 vs 10: hook wired, script clean, skills present, but no audit in 60 days is a 15 — one habit lapsed. The hook pointing at a script that is missing or exits non-zero, or reports arriving while no skill and no decision moved in a month, is a 10: the loop runs on one cylinder.
Convert findings to a band. Use only these six values. No half points, no 22.
Score Means 25 No findings. The mechanism exists, is complete, and is being used. 20 Cosmetic only — wording, ordering, a stale "last verified" date. Nothing an agent would act on wrongly. 15 One real gap. The mechanism is built and working; one thing slipped through it. 10 Partly unimplemented. The mechanism exists in outline but does not cover what it claims to. 5 The mechanism is absent. No map, no precedence table, no dates, no loop. 0 Actively wrong. It points somewhere false and an agent following it lands on the wrong answer. Two deterministic rules, so a second run lands on the same number:
- The band is set by the most severe single finding, never by the count. One dead path is a 15 whether or not the rest of the map is perfect.
- If two or more distinct findings land in that same band, drop exactly one step (25→20→15→10→5→0). Floor at 0. Do not drop twice for four findings.
Write down the finding that set each band. That sentence is what makes the next run comparable — a score with no named cause cannot be re-derived.
Rank the top three fixes by leverage, not by severity. Leverage is points recovered divided by effort. A 15 you can close in two minutes outranks a 5 that needs an afternoon. Break ties by: the lowest axis first, then whichever fix unblocks another axis — repairing the routing map usually raises Precedence too, because you cannot tell what is duplicated until you know where things live.
Every fix ships with the exact command or the exact edit. Not "improve the routing map" —
add a row for assets/ to the routing map in CLAUDE.md. Not "run an audit" —/os-audit. A fix the operator has to design themselves will not get done.Write the report to
reports/blueprint-YYYY-MM-DD.md, using today's date. Before writing, check for a previous run (ls reports/blueprint-*.md) and fill the previous-score line in the template below from whatever you find — drop that line entirely if this is the first run. Print the score line in the session too — the operator should not have to open a file to see it.# Blueprint — YYYY-MM-DD **Score: NN/100** — Routing NN · Precedence NN · Freshness NN · Loop NN _(Previous run: NN/100 on YYYY-MM-DD)_ ## What is built right <Two to four lines. Name the mechanisms that scored 25 or 20 and why. Strengths are not filler — they are what the operator must not break while fixing.> ## Score detail | Axis | Score | The finding that set the band | |---|---|---| | Routing | NN | … | | Precedence | NN | … | | Freshness | NN | … | | Loop | NN | … | ## Top three fixes, by leverage 1. **<fix>** — recovers ~N points on <axis>. Run: `<exact command or edit>` 2. **<fix>** — recovers ~N points on <axis>. Run: `<exact command or edit>` 3. **<fix>** — recovers ~N points on <axis>. Run: `<exact command or edit>` ## Everything else found <The findings that did not make the top three, one line each, so the next run is not surprised by them.>- Close by telling them to re-run. Say it plainly: do the
three fixes and run
/blueprintagain — the number moves, and the movement is the only proof the fixes were real. A score you take once is a verdict. A score you take monthly is a control loop, and this workspace stops being true in about sixty days without one.
Rules
- Read-only except the report. You score; you do not repair. If a fix is obvious and small, it still goes in the report as a command, not into the working tree. An audit that quietly edits what it measures can never be re-run honestly.
- Never run a
gitcommand. Not to check history, not to check status. - Never score an axis you did not run the commands for. If a command fails, say the axis is unscored and why. A guessed 20 poisons the comparison with every future run.
- Ignore
archives/in every grep and every count. Retired material is meant to be stale.
When NOT to run this
- The workspace has stale facts, not structural problems — the map is fine, the numbers in
it are old. That is
/os-audit. It checks whether every claim the manual makes is still true; this checks whether the mechanisms that keep claims true exist at all. A workspace can pass one and fail the other badly in either direction. - You just missed one specific thing that was there — that is
/route-fix. It repairs the single cause behind a single miss. Do not run a full scoring pass to fix one bad routing row; the score will tell you nothing you did not already learn from the miss. - The demo is still installed and the operator has never set this up — run
/onboardfirst. Scoring a demo workspace measures the template, not their workspace, and the number is meaningless. - The operator wants something built, not measured —
/leveragefinds the week's friction and ships one machine for it;/skill-builderturns a repeated process into a skill. This skill produces a diagnosis and stops.
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.

