New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Update Arch Docs

by cluesmith in cluesmith/codev

Audit, prune, and update the project's governance docs — the COLD reference archives codev/resources/arch.md and codev/resources/lessons-learned.md AND their always-on HOT companions…

Apache-2.0Auto-check passedDevelopment

Install Update Arch Docs

skills CLI
$ npx skills add cluesmith/codev --skill update-arch-docs -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install cluesmith/codev update-arch-docs --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/cluesmith/codev.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.codex/skills/update-arch-docs .claude/skills/update-arch-docs && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
update-arch-docs
GitHub stars
288
Token cost
~3.2k tokens
SKILL.md length
1,776 words
Files
1
Skills in repo
12
Repo updated
First seen
Licence
Apache-2.0

At a glance

Audit, prune, and update the project's governance docs — the COLD reference archives codev/resources/arch.md and codev/resources/lessons-learned.md AND their always-on HOT companions…

  • Works in 4 steps: Find the smallest section that needs to… → Apply the change via the Edit tool. → If the change adds new content, run a… → …
  • Running MAINTAINs arch-doc step
  • SKILL.md covers What this skill does NOT do, arch.md vs. lessons-learned.md…, Hot tier: cap, displacement,… and Sizing by purpose, not by line…, plus 3 more sections
  • Calls git

What it does

Update Arch Docs is an agent skill from cluesmith/codev. Audit, prune, and update the project's governance docs — the COLD reference archives codev/resources/arch.md and codev/resources/lessons-learned.md AND their always-on HOT companions codev/resources/arch-critical.md and codev/resources/lessons-critical.md (Spec 987, hot/cold two-tier model). Use this skill when running MAINTAIN's arch-doc step, or when asked to update / audit / prune any of those four files. It polices the hot-tier cap (capped facts/lessons + a bounded cold-doc map), enforces displacement (demote…

Its SKILL.md is about 3.2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Changelog and release notes. The repository describes itself as: Codev helps humans and agents co-develop both the context and the code of the project. The licence is Apache-2.0.

When your agent uses it

  • Running MAINTAINs arch-doc step
  • Asked to update / audit / prune any of those four files

Example prompts

  • “/update-arch-docs”

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Find the smallest section that needs to change.
  2. Apply the change via the Edit tool.
  3. If the change adds new content, run a quick sanity check against "What this skill does NOT do" before saving — make sure the new content…
  4. Surface the resulting diff for review.

What it can do on your machine

Read from SKILL.md and the folder at commit 9cd8607. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Update Arch Docs loads about 3.2k tokens when it runs. Until then it costs about 224 tokens; SKILL.md has 1,776 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~224
When it runs · the whole SKILL.md, loaded when a task matches
~3.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from cluesmith/codev at commit 9cd8607, republished under its Apache-2.0 licence (© cluesmith). 1,776 words, ~3,226 tokens.

Download SKILL.mdSave it as .claude/skills/update-arch-docs/SKILL.md (or your agent's skills folder).
name
update-arch-docs
description
Audit, prune, and update the project's governance docs — the COLD reference archives `codev/resources/arch.md` and `codev/resources/lessons-learned.md` AND their always-on HOT companions `codev/resources/arch-critical.md` and `codev/resources/lessons-critical.md` (Spec 987, hot/cold two-tier model). Use this skill when running MAINTAIN's arch-doc step, or when asked to update / audit / prune any of those four files. It polices the hot-tier cap (capped facts/lessons + a bounded cold-doc map), enforces displacement (demote to cold when full), keeps each hot file's map accurate, and is opinionated about what NOT to put in each tier (per-spec changelogs, exhaustive enumerations, aspirational state). Two modes: diff-mode (apply a specific change) and audit-mode (propose cuts with reasons). Edits files directly via normal file-edit tooling; no destructive shell commands.

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) and codev/resources/lessons-learned.md (durable wisdom). Full, on-demand; grepped/read for depth.
  • HOT always-on companions — codev/resources/arch-critical.md and codev/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-files is 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/ and codev/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>.md or under codev/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 log retains history; an arch.md that describes things that no longer exist is misleading.
In the HOT files (arch-critical.md, lessons-critical.md)

These are capped, always-on, and behavior-changers only. Bright-line rejections:

  • Anything over the cap. Each hot file fits in a handful of lines (≈10 single-line facts/lessons + a cold-doc map of ≈12 top-level topics, ≤35 lines). To add an entry, demote a weaker one into the cold doc (displacement) — never grow the hot file.
  • Spec-narrow recipes / reference detail. Those go in the COLD archive (reference), never the hot file.
  • A full/auto table of contents in the cold-doc map. The map lists only top-level cold-doc sections, each with a one-line "consult when…" — never every entry.
  • Multi-paragraph entries. One line each.
In the COLD archives (arch.md, lessons-learned.md)

These are the on-demand reference. They may hold spec-narrow recipes and deeper detail — the anti-accretion discipline lives in the hot cap, not here. Still avoid:

  • Multi-paragraph lesson entries. Split or compress to 1–3 sentences.
  • Duplicate adjacent entries. Fold variations of the same lesson into one.
  • Spec-numbered narrative framing ("Lesson from #0468:…"). State the general principle; link the review if needed.
In either file (process)
  • 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.

arch.md vs. lessons-learned.md (two-doc framing)

Treat the two files as siblings with different purposes. When in doubt about which file a fact belongs in, route by purpose:

PurposeGoes in
Current system shape — services, transports, key mental modelsarch.md
Mechanism for a unique subsystemarch.md (subsystem section) — or its own meta-spec if the mechanism is large enough to warrant one, with arch.md keeping a 1-paragraph summary + pointer
Pointers ("see meta-spec X for details")arch.md
A durable engineering pattern that applies across multiple specslessons-learned.md
A system-shape surprise verified-wrong in production ("looks like X but isn't")arch.md § "Verified-Wrong Assumptions" — not lessons-learned.md, because it's a property of the system, not a general pattern

The "system-shape surprise" routing is the one most often gotten wrong. If a future reader needs to know "the system looks like X but actually does Y", that is system shape and lives in arch.md. If they need to know "we learned that doing X is generally a bad idea", that is engineering wisdom and lives in lessons-learned.md.

That arch-vs-lessons routing is the cold-tier axis. Orthogonal to it is the hot/cold axis: once you know a fact is architecture (or a lesson), decide whether it is behavior-changing enough to earn a slot in the capped hot companion, or whether it is reference detail for the cold archive.

Hot tier: cap, displacement, and map accuracy

The hot files (arch-critical.md, lessons-critical.md) are the behavior-changers, and their value depends on staying tiny. When MAINTAIN runs — or any update touches them — enforce:

  • Cap. Each hot file fits in a handful of lines: ≈10 single-line facts/lessons plus a cold-doc map of ≈12 top-level topics, ≤35 lines total. If an addition would exceed the cap, demote the weakest existing entry into the corresponding cold doc rather than growing the hot file. The cap is load-bearing: it is what keeps the hot tier cheap enough to inject into every prompt.
  • Map accuracy (bounded AND accurate). Each hot file ends with a "Map of <cold doc> (consult when…)" listing only the cold doc's top-level sections, each with a one-line "consult when…". As cold-doc sections are added / renamed / removed, update the map to match — but keep it top-level only; never expand it into a full table of contents (that re-creates the accretion the hot tier exists to avoid).
  • Behavior-changers only. A hot entry must be something that should change a decision up front. Reference detail, recipes, and one-offs belong in the cold archive — demote on sight.

Sizing by purpose, not by line count

There is no line-count budget for either file. The right size for each section is determined by what the section needs to do. If a subsystem genuinely has unique mechanism that takes 80 lines to explain clearly, 80 lines is the right size. If a subsystem can be described in 5 lines and a pointer to a meta-spec, 5 lines is right.

What's wrong is bulk that comes from any of the patterns in "What this skill does NOT do" above. Strip those, and the file's size will land where it belongs.

When proposing a section, ask: "Could a future reader skip this section without losing anything load-bearing?" If yes, the section should not exist. The doc's purpose is orientation, not completeness.

Show full SKILL.md (679 more words)Show less

Mode: diff-mode (apply a specific change)

Use diff-mode when the request is specific: "add a section about the new caching layer," "update the Glossary entry for Tower," "remove the reference to the deleted dashboard-server."

In diff-mode:

  1. Find the smallest section that needs to change.
  2. Apply the change via the Edit tool.
  3. If the change adds new content, run a quick sanity check against "What this skill does NOT do" before saving — make sure the new content is current state, not aspirational; not duplicative of a meta-spec; not a per-spec changelog entry.
  4. Surface the resulting diff for review.

Diff-mode is fast. It is the right mode for ~80% of post-MAINTAIN documentation work.

Mode: audit-mode (identify what to cut)

Use audit-mode when the request is general: "the doc feels stale," "MAINTAIN says it's time to prune," "review arch.md against the principles."

In audit-mode:

  1. Read the file end-to-end.

  2. For each section in arch.md, run through the per-section pruning checklist (from the MAINTAIN protocol):

    • Does it describe current state? If aspirational, the section moves to a meta-spec; the arch.md keeps a 1-paragraph summary + pointer (or nothing, if the meta-spec stands on its own).
    • Does it duplicate a meta-spec? If yes, replace with a 1-paragraph summary + pointer.
    • Is it a per-file enumeration that's gone stale? If yes, prune to the directory shape + a few key files.
    • Is it a changelog/narrative section ("Spec 0042 added X")? If yes, absorb the architecturally-relevant facts and remove the spec-numbered framing.
    • Is the component still alive? If retired, delete the section entirely.

  3. For each entry in the COLD lessons-learned.md, run the per-entry checklist:

    • Is it terse (1–3 sentences)? If multi-paragraph, split or compress.
    • Is the topic section the right one? If filed under "Architecture (continued)" or a spec-numbered section, move it to the right topical home.
    • Is it a duplicate of an adjacent entry? If yes, fold them.
    • (Spec-narrow recipes are kept here as reference — do not cut them just for being spec-narrow. Anti-accretion now lives in the hot cap, not in the cold archive.)

    Then audit each HOT file (arch-critical.md, lessons-critical.md):

    • Cap: within ≈10 entries + a ≈12-topic map, ≤35 lines? If over, demote the weakest entries into the cold doc.
    • Map accuracy: does every map topic name a real top-level cold-doc section, and is any new/renamed section reflected? Fix drift; keep the map top-level only.
    • Behavior-changers only: demote any reference detail that crept in.

  4. When in doubt, KEEP. This rule comes from the MAINTAIN protocol and applies in audit-mode too. A confident cut is better than three speculative ones. Bias toward fewer, higher-confidence proposals with clear rationale; do not chase a maximum cut count.

  5. Apply the cuts via the Edit tool — the skill does not produce a "candidate-cuts list and stop." The diff is the proposal. The MAINTAIN PR review is the human-confirmation step.

  6. Surface a short reason alongside each cut in the run file (codev/maintain/NNNN.md) so PR reviewers can evaluate intent ("removed because: per-spec changelog framing"; "compressed because: duplicates the orchestrator meta-spec").

Audit-mode is slower than diff-mode and produces larger diffs. Reserve it for explicit audit invocations, not for routine doc updates.

Output contract

The skill commits to the following:

  • It edits the four governance files — codev/resources/arch.md / arch-critical.md and codev/resources/lessons-learned.md / lessons-critical.md — directly via the Edit tool.
  • It does not invoke destructive shell commands (no rm -rf, no git rm, no destructive sed). File deletions happen only through Edit removing the relevant content; whole-file removal would be a structural change that is out of scope for this skill.
  • In audit-mode, every removal is paired with a one-line reason in the MAINTAIN run file's ## Audit Findings section. Rationale lives there so reviewers can evaluate intent without re-deriving it from the diff.
  • The skill does not modify other files (specs, plans, reviews, source code). If a fact belongs somewhere else, the skill flags it; it does not move it.
  • The skill does not edit live arch.md or lessons-learned.md content as a side effect of being read or invoked — only when the user/MAINTAIN protocol explicitly asks for an update or audit.

© cluesmith, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .codex/skills/update-arch-docs of cluesmith/codev.

Open the folder on GitHubat commit 9cd8607

Compare with similar skills

Update Arch Docs next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Update Arch Docs compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Update Arch Docs this skillcluesmith/codev288—~3.2kAutomated safety check: PassApache-2.0
Simple Englishmoeru-ai/airi50k2 repos~4.6kAutomated safety check: PassMIT
StarRocks Release NotesStarRocks/starrocks12k—~1.9kAutomated safety check: NotesApache-2.0
Cutting A ReleaseTriliumNext/Trilium38k—~3.2kAutomated safety check: PassAGPL-3.0
React Router Release Notes Prepremix-run/react-router57k—~1.1kAutomated safety check: PassMIT
Mole CLI Release Flowtw93/Mole70k—~2.5kAutomated safety check: PassGPL-3.0

Similar skills

  • Simple English

    moeru-ai/airi

    Write or rewrite technical text with the rules of ASD-STE100 Simplified Technical English so it is clear, unambiguous, and free of AI slop.

    50k GitHub starsUsed in 2 repos~4.6k tokens
    DevelopmentAuto-check passed

  • StarRocks Release Notes

    StarRocks/starrocks

    Drafts English release notes for a StarRocks patch release from the PRs merged into its release branch, then opens a documentation PR and hands translation to /translate.

    12k GitHub stars~1.9k tokensUpdated today
    DevelopmentAuto-check: notes

  • Cutting A Release

    TriliumNext/Trilium

    A skill your agent uses when cutting, preparing, or debugging a Trilium release — bumping the monorepo version, tagging, or diagnosing a failed "Release" workflow run.

    38k GitHub stars~3.2k tokensUpdated today
    DevelopmentAuto-check passed

  • React Router Release Notes Prep

    remix-run/react-router

    Polishes pending React Router change files before the versioning scripts run, and decides whether a long-form What's Changed section is warranted.

    57k GitHub stars~1.1k tokensUpdated 2 days ago
    DevelopmentAuto-check passed

  • Mole CLI Release Flow

    tw93/Mole

    Runbook for assessing and executing a Mole CLI release: distribution channels, pre-flight checks, capital-V tags, build artifacts and the handoff to curated release notes.

    70k GitHub stars~2.5k tokensUpdated today
    DevelopmentAuto-check passed

  • Release

    PrefectHQ/fastmcp

    Cut a FastMCP release end to end. An agent skill from PrefectHQ/fastmcp.

    28k GitHub stars~2.9k tokensUpdated today
    DevelopmentAuto-check passed

More from cluesmith/codev

All 12 skills in this repo

  • Afx

    cluesmith/codev

    Agent Farm CLI — the tool for spawning builders, managing Tower, workspaces, and cron tasks.

    288 GitHub stars~2.4k tokensUpdated 2 days ago
    Auto-check passed

  • Arch Init

    cluesmith/codev

    Adopt an architect identity and recover its state from codev/state/<name.md.

    288 GitHub stars~2.7k tokensUpdated 2 days ago
    Auto-check passed

  • Arch Save

    cluesmith/codev

    Save an architect's state, clear its context, and re-init automatically — the packaged save→clear→re-init refresh cycle.

    288 GitHub stars~3.8k tokensUpdated 2 days ago
    Auto-check passed

  • Builder Refresh

    cluesmith/codev

    Refresh a builder's own context at a protocol boundary — save working state, verify it, clear, and re-orient.

    288 GitHub stars~1.7k tokensUpdated 2 days ago
    Auto-check passed

  • Codev

    cluesmith/codev

    Codev project management CLI — init, adopt, update, and doctor commands.

    288 GitHub stars~962 tokensUpdated 2 days ago
    Auto-check passed

  • Consult

    cluesmith/codev

    AI consultation CLI — query Gemini, Codex, or Claude for reviews and analysis.

    288 GitHub stars~1.1k tokensUpdated 2 days ago
    Auto-check: notes

Categories

Questions about Update Arch Docs

What does Update Arch Docs do?

Audit, prune, and update the project's governance docs — the COLD reference archives codev/resources/arch.md and codev/resources/lessons-learned.md AND their always-on HOT companions…. Update Arch Docs is an agent skill from cluesmith/codev.md (Spec 987, hot/cold two-tier model).

When should I use Update Arch Docs?

Update Arch Docs fits situations like: running MAINTAINs arch-doc step; asked to update / audit / prune any of those four files.

How do I install Update Arch Docs in Claude Code?

Run `npx skills add cluesmith/codev --skill update-arch-docs -a claude-code`. Or copy the skill folder (.codex/skills/update-arch-docs in cluesmith/codev) into .claude/skills/update-arch-docs in your project. Claude Code loads it when a task matches its description.

How do I install Update Arch Docs in Codex?

Run `npx skills add cluesmith/codev --skill update-arch-docs -a codex`. Or copy the skill folder (.codex/skills/update-arch-docs in cluesmith/codev) into .agents/skills/update-arch-docs in your project. Codex loads it when a task matches its description.

Can I use Update Arch Docs in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add cluesmith/codev --skill update-arch-docs -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/update-arch-docs, .gemini/skills/update-arch-docs, .github/skills/update-arch-docs and .opencode/skills/update-arch-docs in your project.

What does Update Arch Docs need to run?

Going by SKILL.md and its folder, Update Arch Docs needs the command-line tools its instructions call (git).

Does Update Arch Docs access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Update Arch Docs safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Update Arch Docs use?

Update Arch Docs is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Update Arch Docs use?

About 3.2k tokens (SKILL.md is roughly 13k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Update Arch Docs?

Skills that share tags, products or a category with Update Arch Docs: Simple English (moeru-ai/airi, 50k stars), StarRocks Release Notes (StarRocks/starrocks, 12k stars), Cutting A Release (TriliumNext/Trilium, 38k stars) and React Router Release Notes Prep (remix-run/react-router, 57k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Update Arch Docs?

cluesmith (a GitHub organization) maintains it in cluesmith/codev, which has 288 GitHub stars. The repository holds 12 skills in this directory. The repository was last updated on October 6, 2026.

Source: cluesmith/codev on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.