Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add skills/cluesmith/codev/update-arch-docsnpx skills add cluesmith/codev --skill update-arch-docsgit clone --depth 1 https://github.com/cluesmith/codevWhat 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 | $0.00212 | $0.03076 |
| Opus 5 | $0.00106 | $0.01538 |
| Sonnet 5 | $0.00042 | $0.00615 |
| Haiku 4.5 | $0.00021 | $0.00308 |
Grade B, and why
update-arch-docs scanned grade B with 1 finding 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 yesterday.
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.
Recursive force deletemediumDestructive command
rm -rf with a variable or a broad path is one typo away from removing the wrong tree.
- **Destructive shell commands**. The skill must not invoke `rm -rf`, `git rm`, or destructive `sed` scripts. All edits go through the normal Edit tool. The MAINTAIN PR diff is the human-confirmation step; that's enough. Downgraded: this mod is about security review, or the phrase is quoted, so it is likely naming the pattern rather than instructing it.
How it starts
The opening of the file, as written. The whole thing — 133 lines — stays where its author put it; the contents beside it link to each section on GitHub.
update-arch-docs
This skill maintains the project's governance docs, each split into two tiers (Spec 987):
- COLD reference archives —
codev/resources/arch.md(architecture) andcodev/resources/lessons-learned.md(durable wisdom). Full, on-demand; grepped/read for depth. - HOT always-on companions —
codev/resources/arch-critical.mdandcodev/resources/lessons-critical.md. Tiny, hard-capped, always injected into every porch prompt and into CLAUDE.md/AGENTS.md. Each holds capped facts/lessons plus a bounded "consult when…" map of its cold doc's top-level topics.
It is invoked by the MAINTAIN protocol's documentation step, and ad-hoc whenever someone updates, audits, or prunes any of these files. The skill is opinionated about what does not belong in each tier and polices the hot-tier cap, displacement, and map accuracy. Use it whenever a doc change touches any of the four files.
What this skill does NOT do
These are the patterns that have, in practice, caused arch.md and lessons-learned.md to grow without bound. Treat them as bright-line rejections during both audit-mode and diff-mode work.
In arch.md
- Per-file enumerations that go stale the moment they're written. Document the shape of a directory and the handful of load-bearing files; do not list every file.
git ls-filesis authoritative; the doc is for orientation. - Per-spec changelog sections ("Spec 0042 added X, Spec 0073 changed Y"). Architecture is current state, not history. The git log + the spec/review documents own the changelog framing.
- Specs/plans tables that mirror the contents of
codev/specs/andcodev/plans/. These are duplicative and rot quickly. Link to the directory; do not paginate it into the doc. - Aspirational state ("we plan to…", "in the next phase we'll…"). That belongs in the relevant meta-spec or roadmap doc, not in the architecture body. arch.md describes what is, not what might be.
- Date-stamped narrative ("As of 2026-Q2, the system uses…"). Dates make the doc look fresh while making it harder to maintain. Use git log + commit dates for temporal context.
- Duplication of meta-spec content. If a subsystem has its own meta-spec under
codev/architecture/<domain>.mdor undercodev/specs/, arch.md should carry a 1-paragraph summary plus a pointer — not a copy. - Retired-component graveyards. When a component is removed, delete its section.
git logretains history; an arch.md that describes things that no longer exist is misleading.
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.
- yesterday First seen · 133 lines · 212 tokens per session scan B 88b726a39f94
update-arch-docs is a skill published in the GitHub repository cluesmith/codev (286 stars, last pushed 5d ago), licensed Apache-2.0. It adds 212 tokens to every session and 3,076 once invoked, about $0.0011 per session on Opus 5. A static security scan graded it B with 1 finding (recursive force delete). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other skills, from other repositories
hns-lsel-curator
Local Self-Evolution Loop (LSEL) curator — the CLUSTER + drain engine for the GOOS-local PROPOSE→APPLY seam closure (SPEC-LSEL-LOCAL-EVOLUTION-001). Companion-offset drain of .moai/lessons-inbox.jsonl with a drain-side severity filter that drops the 65% Bash-timeout/sandbox noise, eventkey clustering with a frequency…
new-feedback
Log a harness lesson / post-incident so the SYSTEM improves, not just this one bug — fires on "log a harness lesson", "post-incident", "we should make this less likely", System-Evolution moments. Part of the Agentsmith harness; scaffolds a numbered docs/feedback/NNNN-.md with the five-stage template (R9 — numbers are…
review-claudemd
Review recent conversations to find improvements for CLAUDE.md files.
author-product-docs
Create, revise, retrofit, audit, or verify product documentation — pack READMEs, journeys, tutorials, how-to guides, reference pages, and explanations. Use when asked to write, improve, restructure, audit, or verify user-facing documentation, fix a pack README, create a guide for a feature, update a journey page, or…
java-optionals-eval-capture
Use in Symphony for Trello when a Java change or review presents a reusable Optional or absence/fallback strategy-selection lesson, including on an adjacent owning API such as ScopedValue even when no java.util.Optional appears. Capture the before/prompt/after code and create or update a self-contained eval issue in…
java-streams-eval-capture
Use in Symphony for Trello when a Java change or review presents a reusable lesson about choosing or preserving a stream, collector, direct result-producing collection transformation, or character-predicate traversal, including identity or delimited string reductions, even when the preferred final code contains no…