Getting it into your agent
It runs from inside its repository, so the clone comes first — what it calls does not travel with the file alone.
git clone --depth 1 https://github.com/MartinPLarsen/claude-architecture-skillsnpx agentmods add skills/martinplarsen/claude-architecture-skills/architecture-improveWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/martinplarsen/claude-architecture-skills/architecture-improve)<a href="https://agentmods.dev/skills/martinplarsen/claude-architecture-skills/architecture-improve"><img src="https://agentmods.dev/badge/skills/martinplarsen/claude-architecture-skills/architecture-improve/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/martinplarsen/claude-architecture-skills/architecture-improve"><img src="https://agentmods.dev/badge/skills/martinplarsen/claude-architecture-skills/architecture-improve.svg" alt="Reviewed on agentmods" width="80" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00169 | $0.02249 |
| Opus 5.5 | $0.00068 | $0.00900 |
| Sonnet 5.5 | $0.00034 | $0.00450 |
| Haiku 4.5 | $0.00017 | $0.00225 |
Grade A, and why
architecture-improve scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2mo ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 153 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Architecture Improve
Deep-research an architecture-map (map.js) for what to change, then paint each idea
back onto the map as a proposed node carrying a structured proposal. The sibling of
architecture-cleanup: map = WHAT exists → cleanup = what to REMOVE → improve = what to CHANGE.
Core principle — proposals-only. improve surfaces optimisation ideas and draws them on the map. It NEVER edits source, opens PRs, or applies a change (ADR-012: only cleanup gets an execution layer; improve's changes are judgment-heavy refactors, not mechanical removals).
When to use
- "Optimise the architecture", "improve the pipeline", "where can this be better".
- After mapping (and ideally cleaning) a repo, to plan structural/flow improvements.
- Not for line-level perf, micro-optimisation, or product/feature redesign (D4 boundary).
- Not for finding dead code to delete — that's
architecture-cleanup. - Recommended order: cleanup → improve (don't optimise code you're about to delete).
Input — map.js (ADR-010)
The input is <repo>/architecture-map/map.js (window.MAP_DATA). If it doesn't exist, build
it first with the architecture-map skill, then run improve on the result. If a fresh
architecture-cleanup overlay exists, improve reads it (see Cross-skill, ADR-014).
The two lenses (D4)
Every proposal is tagged with exactly one lens:
- 🏗️ structure — coupling, god-nodes (high fan-in + fan-out), duplicate subsystems, layering violations, missing seams.
- 🔀 pipeline — redundant hops, serial steps that could run in parallel, idempotency/retry gaps, data stored as expiring temp URLs instead of re-hosted, missing back-pressure.
Step 1 — deep research (fan-out, C3 gate)
- Ensure the map exists & is fresh. No
map.js→ build viaarchitecture-map. A stale map gives stale proposals, so re-map if the repo moved. - Cheap seed signals (deterministic). Reuse cleanup's topology helper to focus the research —
it gives per-node degree (god-node = high inbound+outbound),
duplicateGroups(dup tech), and blast-radius:node ../architecture-cleanup/analyze-map.mjs <repo>/architecture-map/map.js > /tmp/seed.json - Cost gate (C3) — warn on scale BEFORE firing. Reader count = number of subsystems on the map. If it is > 8, tell the user the count + a rough token estimate and wait for a go. At/under 8, proceed.
- Fan out, one reader per subsystem. Reuse
architecture-audit's Map-phase pattern (scout + parallel readers via the Workflow tool / subagents). Each reader carries BOTH lenses in its brief and is pre-seeded withseed.jsonhints for its subsystem (high-degree nodes, dup groups). One reader per subsystem keeps the agent count = subsystem count. Each reader returns candidate proposals:{problem, change, tradeoff, effort, impact, lens, affectedNodes[]}.
What ships with it
1 file beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2mo ago First seen · 153 lines · 0 tokens per session scan A 6e44211d2d4a
architecture-improve is a skill published in the GitHub repository MartinPLarsen/claude-architecture-skills (3 stars, last pushed 3mo ago), licensed MIT. It adds 169 tokens to every session and 2,249 once invoked, about $0.0007 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.
Other skills, from other repositories
scenario-godot-multiplayer
Use when a Godot 4 game goes online or co-op: host and join with ENet, WebSocket for a web build, RPCs (@rpc, rpcid, anypeer), MultiplayerSpawner and MultiplayerSynchronizer, player authority, lobbies and login, a dedicated or headless server export, lag, rubber-banding, prediction or netfox, cheating, bandwidth…
league-akari-sgp-data-source
Use when implementing or reviewing League Akari SGP/LCU data-source selection, SGP API clients, League Servers remote config, Tencent cross-region queries, token handling, or per-feature SGP interoperability.
csharp-godot
Use when working with C# in Godot — conventions, GodotSharp API differences from GDScript, project setup, and interop.
web-services
Use when calling web APIs or backends from Godot — HTTPRequest, REST/JSON clients, auth headers, downloads, TLS, WebSocketPeer clients, retries, and keeping secrets out of the build.
gamedev-multiplayer
Use when adding multiplayer or netcode to a game — client-server vs P2P, server authority and anti-cheat, state replication vs RPCs, prediction and reconciliation, lag compensation, plus Godot 4 / Unity NGO / Unreal wiring. NOT single-player gameplay (that is godot, unity, unreal), NOT matchmaking or server hosting…
cloudflare-durable-objects
Cloudflare Durable Objects for stateful coordination and real-time apps. Use for chat, multiplayer games, WebSocket hibernation, or encountering class export, migration, alarm errors.