Docs update
Refresh existing docs (architecture, onboarding, data-model, deployment, security, contributing) so they match the current codebase, verifying every claim against real code instead of guessing. Use when the user says docs are stale, asks to sync docs with recent code changes, update a specific doc file, or update a whole category (core/data/infrastructure/development) after a refactor or schema change. Not for creating docs that don't exist yet (use docs-init) or scoring/auditing doc health without editing (use docs-check).From its SKILL.md
npx -y skills add mgiovani/cc-arsenal --skill docs-updateAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
7.9 KB, as published. Nobody here has run it
Update Documentation
Synchronize documentation with the current codebase state: one file, a category, or everything in docs/.
Anti-Hallucination Guidelines
Every statement written must trace back to a file read or grepped this run:
- Verify each claim before writing it, read the actual source, don't recall it
- Get counts from
find/grep, never estimate ("5 services" means 5 files were counted this run) - Delete claims about features that no longer exist rather than leaving them stale
- After writing, re-read the diff and drop anything not backed by evidence gathered this run
Workflow
Phase 1: Resolve Scope
Parse the invocation argument:
- No argument or
all: update every doc that exists indocs/ <doc-name>(e.g.architecture): resolve via the mapping below, update only that filecategory:<name>(core,data,infrastructure,development): update every doc in that category
| Argument | File Path | Category |
|---|---|---|
architecture | docs/architecture.md | core |
onboarding | docs/onboarding.md | core |
data-model | docs/data-model.md | data |
deployment | docs/deployment.md | infrastructure |
security | docs/security.md | infrastructure |
contributing | docs/contributing.md | development |
Existence check: stop before doing anything else if the target is missing. This skill only updates docs that already exist; it never creates one.
allorcategory:<name>: silently exclude any mapped path that isn't on disk (e.g.find docs/*.mdand intersect with the category's paths); the run proceeds with whatever remains<doc-name>: resolve the path, then check it withtest -f <resolved-doc-path>(or Read). If it does not exist, STOP the entire skill run right here: do not read further, do not run Phase 2-5, do not Write or Edit that path under any pretext (not as a "special case," not with a caveat about verified content). Tell the user the doc doesn't exist yet and point them todocs-init, which owns creation and the canonical templates. This is the final action for that run.
For a multi-doc run that passes the existence check, track progress with TodoWrite: one todo per document, marked in_progress while it's being worked and completed once written.
Phase 2: Check Freshness
For each doc resolved in Phase 1 (using its actual path, not a fixed one), compare its last commit against source changes since:
git log --since="$(git log -1 --format=%ai -- <resolved-doc-path> 2>/dev/null || echo '30 days ago')" --oneline --name-only -- . ':!docs' | head -30
A doc whose last update predates relevant source changes is a candidate for this run. If git history is unavailable (no .git, doc untracked, first commit), fall back to the commands in references/change-detection.md and note in the final report that freshness couldn't be determined from git.
Phase 3: Verify Against the Codebase
Single document: read it fully, then grep the codebase for each claim it makes (component names, counts, file paths, tech stack). No subagent needed, one Explore pass funnels into one file write either way.
Multiple documents (all or category mode): spawn one subagent per document so verification runs concurrently, see references/update-strategies.md for the per-document-type checklist and prompt pattern. If no Task/subagent tool is available, run the same read-verify-write pass for each document sequentially instead.
Phase 4: Write Updates
- Preserve manually added sections and any content that doesn't match the template structure: only touch parts backed by verified facts from Phase 3
- Templates are shared with docs-init:
../docs-init/assets/templates/relative to this skill's own directory (works when both skills are installed side by side, e.g. via the cc-arsenal plugin ornpx skills add). If docs-init isn't installed alongside this skill, fetch the same templates from the cc-arsenal repo instead of inventing structure - Before filling placeholders, run
grep -oE '\{\{[A-Z_]+\}\}' <template-file>to see the tokens that specific template actually uses: each template has its own set (architecture.md alone uses over a dozen), never assume a fixed list - Regenerate diagrams whose depicted components/entities changed
- Remove claims Phase 3 could not verify
- If it's ambiguous whether a section is custom or auto-generated, ask before overwriting rather than guessing
Phase 5: Report
List documents updated (with what changed and numbers pulled from Phase 3, e.g. "3 services found" not "several services"), skipped (already fresh), and not found (excluded from an all/category run because the file doesn't exist, mention docs-init, don't create it). This skill never reports a "created" doc; creation is docs-init's job.
Example Output: All Docs Update
Documentation Update Complete
Updated (2 docs):
docs/architecture.md (added AuthService, NotificationService — found via grep of src/services/)
docs/data-model.md (schema changed, ER diagram regenerated from 6 models)
Up to Date (1 doc):
docs/onboarding.md (no source changes since last update)
Skipped — could not verify (1 doc):
docs/security.md (claims about SSO could not be confirmed in code, left as-is, flagged for manual review)
Example Output: Specific Doc Update
Architecture Documentation Updated
File: docs/architecture.md
Changes:
Added 2 new services (AuthService, NotificationService) — src/services/auth.py, src/services/notify.py
Updated architecture diagram to include the new message queue integration
Preserved custom "Deployment Notes" section (not touched)
Verified:
5 services total (find src/services -name '*.py' | wc -l)
3 databases: PostgreSQL, Redis, MongoDB (grep of config/database.yml)
Example Output: Target Doc Doesn't Exist
docs/security.md doesn't exist yet — nothing to update.
This skill only refreshes existing docs. Run docs-init to create
docs/security.md from the canonical template first, then re-run
docs-update security to keep it in sync going forward.
No file was written and no other phase ran.
Notes
- Never creates a doc that doesn't exist: a missing target stops the run and points to docs-init instead
- Preserves custom content by default: asks rather than overwrites when a section's status is unclear
- Git-aware: freshness comes from
git log, not assumption - Safe to run repeatedly (after refactors, schema changes, infra changes, or before onboarding/releases)
- For a full category, see references/update-strategies.md for the category-level output format and per-doc-type verification steps
Additional Resources
- references/update-strategies.md: parallel subagent pattern, per-document-type checklist, category-update output format
- references/change-detection.md: fallback change-detection commands when git history is unavailable
What ships with it: 4 files
8.6 KB alongside SKILL.md
evals/
- evals.json2.7 KB
- trigger-eval.json1.9 KB
references/
- change-detection.md1.6 KB
- update-strategies.md2.3 KB
Gives 0 of the 12 instructions most docs writing skills give
Counted across 1,951 of the 3,904 authors here whose files we hold, read 2026-09-06
- Use third-person for skill descriptionsin 54 of 1951, across 35 files
- Start descriptions with Use whenin 43 of 1951, across 29 files
- Run baseline scenarios before writing any skillin 40 of 1951, across 26 files
- Use active voicein 40 of 1951, across 36 files
- Map file responsibilities before defining tasksin 36 of 1951, across 29 files
- Use checkbox syntax for tracking stepsin 35 of 1951, across 27 files
- Ask one question at a timein 35 of 1951
- Offer execution options after saving the planin 33 of 1951, across 24 files
- Include complete code in every stepin 33 of 1951, across 27 files
- Design units with clear boundaries and interfacesin 31 of 1951, across 23 files
- Announce the skill usage at the startin 30 of 1951
- Verify agent compliance after adding the skillin 29 of 1951, across 17 files
Said here and by no other author read
- Read actual source files instead of relying on memory
- Use find and grep to obtain exact counts
- Re-read diffs to remove unverified information
- Stop immediately if the target document does not exist
- Preserve manually added sections and custom content
- Compare last commit against source changes to check freshness
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.