update-docs
Skill1 starsChanged 5 months agoApache-2.0View on GitHub
Audit and update project docs — ARCHITECTURE.md, CHANGELOG.md, README cross-references, and missing OSS docs
90 other projects use a version of this.
Adopted by
Most recently taken up by
- aws-samples/sample-apex-skillstheir own version, first seen Nov 15, 2026
- therain2020/therain2020-agenttheir own version, first seen Nov 15, 2026
- charlesmsiegel/coding-skillstheir own version, first seen Nov 15, 2026
- alexj11324/Mikkatheir own version, first seen Nov 15, 2026
- iuliandita/skillstheir own version, first seen Nov 15, 2026
- caipe-io/ai-platform-engineeringtheir own version, first seen Nov 12, 2026
Used with
Projects with it also use get-pr-reviews, push-everything 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.
saffron-healthSkillget-pr-reviews
Get nicely formatted output of the last review comments on a PR. Used internally by other skills.
Also in 3 projects that use this
saffron-healthSkillpush-everything
Stage ALL changes in the repository (not just session changes), commit, and push. Use when you need to commit all pending changes.
Also in 3 projects that use this
TheKREATORSSkillinstinct-export
Export instincts from project/global scope to a file
Also in 3 projects that use this
TheKREATORSSkillinstinct-import
Import instincts from file or URL into project/global scope
Also in 3 projects that use this
NVIDIASkillgenerate-spec
Produce a feature specification covering API changes, backward compatibility, cross-language impact, performance, and a file-level change plan. Use when designing a new feature, planning a significant change, or the user asks to spec something out.
Also in 3 projects that use this
belokonmSkillfullstack-developer
End-to-end feature expert specializing in frontend-backend integration, system architecture, and complete application development
Also in 4 projects that use this
- +1 more from TheKREATORS
- +1 more from saffron-health
Other versions90 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 90
- vercel/next.js★ 144ksame name
- pipecat-ai/pipecat★ 17ksame name
- anyproto/anytype-ts★ 9.1ksame name
- vladmandic/sdnext★ 7.4ksame name
- ArcReel/ArcReel★ 6.6ksame name
- dotnet/sdk★ 3.3ksame name
- meta-pytorch/OpenEnv★ 2.9ksame name
- huggingface/OpenEnv★ 2.9ksame name
- man-group/ArcticDB★ 2.6ksame name
- fabro-sh/fabro★ 1.9ksame name
80 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
17 rules. 0 are common, 12 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 84 edited versions we read keep these.
12
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 43
If $ARGUMENTS is empty or unrecognized, use AskUserQuestion:
- Distinctive: line 46
All documents (architecture + changelog + readme + oss) *(Recommended)*
- Distinctive: line 56
Create tasks based on selected scope:
- Distinctive: line 276
If ARCHITECTURE.md already exists:
- Distinctive: line 277
Read the file first
- Very specific: line 278
Use Edit to update only the outdated sections (structure tree, module descriptions)
- Distinctive: line 280
Do NOT rewrite sections that haven't changed
- Distinctive: line 294
If exists: read to find the latest version/entry recorded.
- Distinctive: line 295
If not: create from scratch.
- Very specific: line 326
Use commit subject as-is, appended with ({short_hash})
- Distinctive: line 329
If tags exist, create a section for each tagged version with its date
- Distinctive: line 348
Add missing feature descriptions to the Features section.
- Distinctive: line 352
If CHANGELOG.md exists (or was just created) and not already linked in README:
- Distinctive: line 358
If SECURITY.md exists (or was just created) and not already linked:
- Very specific: line 365
Check for README.ja.md, README.ko.md, etc.
- Very specific: line 367
Use Edit for targeted replacements.
- Distinctive: line 408
Only suggest creation — do NOT auto-create without user confirmation, as contribution guidelines are opinionated.
“Common” is measured: kept by at least 6 in 10 of the 84 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
/update-docs — Documentation Audit & Update
Sync project documentation with implementation state. Reads project structure, git history, and existing docs to find and fix gaps.
Arguments: "$ARGUMENTS"
Phase 0: Parse Arguments
Parse $ARGUMENTS (case-insensitive):
architecture→ update ARCHITECTURE.md onlychangelog→ generate/update CHANGELOG.md onlyreadme→ update README cross-references onlyoss→ create missing OSS docs (SECURITY.md, CONTRIBUTING.md) + add README linksallor empty → run all phases
If $ARGUMENTS is empty or unrecognized, use AskUserQuestion:
Q: Which documents should be updated?
- All documents (architecture + changelog + readme + oss) (Recommended)
- ARCHITECTURE.md — fix outdated module/directory structure
- CHANGELOG.md — generate from git history
- README.md — update cross-references and features
- OSS docs — create SECURITY.md, add README links
Phase 1: Create Task Tracker
Create tasks based on selected scope:
| Subject | When |
| "Gather: project structure + docs + git history (parallel scan)" | always |
| "Update ARCHITECTURE.md" | target = architecture or all |
| "Generate/update CHANGELOG.md" | target = changelog or all |
| "Update README.md" | target = readme or all |
| "Create missing OSS docs" | target = oss or all |
| "Verify internal links" | target = all (or whenever files are modified) |
Phase 1b: Parallel Information Gathering
Mark gathering task in_progress. Launch 4 Explore subagents in parallel (model: haiku).
Subagent A: Project Structure Scanner
Scan the project directory structure to understand the codebase layout.
Root: {project root — derive from git rev-parse --show-toplevel}
## What to find:
### 1. Top-level directory inventory
List all top-level directories and their purpose (infer from names and contents).
### 2. Source code structure
Find the primary source directories and their organization:
- Look for src/, lib/, app/, packages/, modules/, feature/, core/ patterns
- For each major directory, list subdirectories (1-2 levels deep)
- Note the primary language(s) (check file extensions)
### 3. Build system
Identify the build system and its configuration:
- Package managers: package.json, Cargo.toml, go.mod, build.gradle.kts, pyproject.toml, etc.
- Monorepo tools: nx.json, turbo.json, lerna.json, settings.gradle.kts, Cargo workspace
- If monorepo: list all packages/modules with their names
### 4. Configuration files
List notable config files: CI workflows, Docker, linting, formatting, etc.
Return a structured summary of the project layout.Subagent B: Existing Docs Scanner
Scan all documentation files in the project.
Root: {project root}
## What to find:
### 1. Document inventory
Use Glob to find all *.md files in: root, docs/, .github/.
For each file, record: path, first heading (title), approximate line count.
### 2. Document content summary
For each of these files (if they exist), read and summarize key sections:
- README.md — Features/description section, links section
- docs/ARCHITECTURE.md or ARCHITECTURE.md — structure section
- CONTRIBUTING.md or docs/CONTRIBUTING.md — first 10 lines
- CHANGELOG.md — latest version entry
### 3. Internal link inventory
For README.md, extract ALL markdown links (pattern: `[text](path)`).
For each link: text, target path, whether it's a relative link.
### 4. Missing standard files
Check existence of: CHANGELOG.md, SECURITY.md, CONTRIBUTING.md, LICENSE
Return a structured summary including: allDocs, missingFiles, readmeLinks, existing doc summaries.Subagent C: Git History Scanner
Scan git history for CHANGELOG generation.
Root: {project root}
## What to find:
### 1. Latest git tags
Run: git tag --sort=-version:refname | head -10
If no tags, note "no tags — will use full history".
### 2. Commits since last tag (or recent 100 if no tags)
If tag exists:
git log {latest_tag}..HEAD --pretty=format:"%H|%s|%as|%an" --no-merges
If no tag:
git log --pretty=format:"%H|%s|%as|%an" --no-merges | head -100
### 3. Classify each commit
For each commit subject, classify into:
- Added: new feature, "add", "implement", "support", "introduce"
- Changed: update, refactor, improve, bump, migrate, rename
- Fixed: fix, bug, crash, error, broken, revert
- Removed: remove, delete, drop, clean
- Infrastructure: CI, lint, build, workflow, docker, deps
### 4. Tagged releases
For each tag found, get the tag date:
git log -1 --format="%as" {tag}
Return: latestTag, classified commits, tag list with dates.Subagent D: Feature Inventory Scanner
Inventory the project's implemented features by examining the source code.
Root: {project root}
## What to find:
### 1. Entry points and main modules
Find main application entry points (main.py, index.ts, App.kt, main.go, etc.).
List the primary features/screens/routes/commands exposed.
### 2. API surface (if applicable)
Grep for route/endpoint definitions, CLI commands, or exported modules.
### 3. Notable integrations
Grep for: database, auth, API client, websocket, queue, cache, storage patterns.
List external service integrations found.
### 4. README-claimed features vs actual
Read README.md's features section. For each claimed feature, verify it exists in code.
Note any features found in code but NOT mentioned in README.
Return: list of implemented features, integrations, and any README gaps.Phase 2: Gap Analysis
Mark gathering task completed.
Consolidate results from all subagents and identify gaps:
Architecture gaps (compare A vs B)
- Directories/modules in the actual project (Subagent A) NOT reflected in ARCHITECTURE.md (Subagent B)
- Outdated paths or descriptions in ARCHITECTURE.md
CHANGELOG gaps (from C)
- Does CHANGELOG.md exist?
- How many unlogged commits since last tag/entry?
README gaps (compare B vs D)
- Features found in code (Subagent D) NOT listed in README Features section
- Broken or missing internal links
OSS gaps (from B)
- Which standard files (SECURITY.md, CONTRIBUTING.md, LICENSE) are missing?
Phase 3: Confirm Scope
Present gap analysis to user with AskUserQuestion:
Gap Analysis Results:
Architecture: [N outdated/missing entries in ARCHITECTURE.md]
CHANGELOG: [exists / missing — N unlogged commits]
README Features: [N implemented features not listed]
OSS docs: [list missing files]Q: Proceed with these updates?
- Yes, update everything found above (Recommended)
- Let me review first (show details)
- Skip specific section (specify which)
Phase 4: Update ARCHITECTURE.md
(Skip if target = changelog, readme, or oss)
Mark task in_progress.
4a. Build updated structure
Using Subagent A results, construct/update the project structure tree. Match the style already used in ARCHITECTURE.md (if it exists). If no ARCHITECTURE.md exists, create one with this structure:
# Architecture
## Project Structure
project-root/ ├── {dir}/ # {description} ├── {dir}/ # {description} └── ...
## Key Design Decisions
{Extract from existing docs or leave as TODO for user}4b. Update existing sections
If ARCHITECTURE.md already exists:
- Read the file first
- Use
Editto update only the outdated sections (structure tree, module descriptions) - Preserve sections that are still accurate (design decisions, diagrams, etc.)
- Do NOT rewrite sections that haven't changed
Mark task completed.
Phase 5: Generate/Update CHANGELOG.md
(Skip if target = architecture, readme, or oss)
Mark task in_progress.
5a. Check existing CHANGELOG
If exists: read to find the latest version/entry recorded. If not: create from scratch.
5b. Write CHANGELOG.md
Format: Keep a Changelog 1.1.0
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- {commit subject} ({short hash})
### Changed
- ...
### Fixed
- ...
### Infrastructure
- ...Rules:
- Group commits by category (Added, Changed, Fixed, Removed, Infrastructure)
- Use commit subject as-is, appended with
({short_hash}) - Skip merge commits
- Infrastructure category goes last
- If tags exist, create a section for each tagged version with its date
- Filter out commits already in the existing CHANGELOG
Mark task completed.
Phase 6: Update README.md
(Skip if target = architecture, changelog, or oss)
Mark task in_progress.
6a. Determine missing features
From Subagent D, identify features implemented in code but not listed in README.
6b. Update Features section
Add missing feature descriptions to the Features section. Keep existing content unchanged.
6c. Add doc links
If CHANGELOG.md exists (or was just created) and not already linked in README:
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a full list of changes.If SECURITY.md exists (or was just created) and not already linked:
For security issues, see [SECURITY.md](SECURITY.md).6d. Mirror in localized README (if exists)
Check for README.ja.md, README.ko.md, etc. If found, apply equivalent changes (translated headings, same link paths).
Use Edit for targeted replacements. Read files before editing.
Mark task completed.
Phase 7: Create Missing OSS Docs
(Skip if target = architecture, changelog, or readme)
Mark task in_progress.
SECURITY.md (if missing)
Adapt to the project's context (web app, CLI tool, library, mobile app):
# Security Policy
## Supported Versions
| Version | Supported |
|---------|-----------|
| Latest | ✅ |
| Older | ❌ |
## Reporting a Vulnerability
Please **do not** open a public GitHub Issue for security vulnerabilities.
Report via [GitHub Security Advisories]({repo_url}/security/advisories/new):
1. Go to the Security tab → Advisories → "Report a vulnerability"
2. Describe the vulnerability, steps to reproduce, and potential impact
3. We aim to respond within 7 daysDerive {repo_url} from git remote get-url origin.
CONTRIBUTING.md (if missing and project has >5 contributors or is public)
Only suggest creation — do NOT auto-create without user confirmation, as contribution guidelines are opinionated.
Mark task completed.
Phase 8: Verify Internal Links
(Always run when any file was modified)
For each modified doc file, extract all relative markdown links [text](path) and verify the target file exists using ls.
Report any broken links. If the target was supposed to be created in this run but wasn't, note as error.
Phase 9: Summary Report
Mark all remaining tasks completed.
## /update-docs Complete
Target: {all | architecture | changelog | readme | oss}
### Files Modified
| File | Action |
|------|--------|
| {path} | {Created / Updated — brief description} |
### Gap Analysis Results
| Area | Before | After |
|------|--------|-------|
| Architecture outdated entries | {N} | 0 |
| Unlogged commits | {N} | 0 |
| README missing features | {N} | 0 |
| Missing OSS files | {N} | 0 |
### Internal Links
All {N} verified links: ✓ (or list broken ones)
### Skipped
{Any phases skipped and reason}Error Handling
| Situation | Action |
| Subagent returns no data | Fallback: read project root directly |
| ARCHITECTURE.md doesn't exist | Create new one from scratch |
| git log returns nothing | Note "no commits to log", skip CHANGELOG |
| Feature exists but can't determine if shipped | Mark as "likely implemented", let user confirm |
| CHANGELOG.md already up to date | Note "already current", skip |
| SECURITY.md already exists | Skip creation, note in report |
| Edit tool fails (pattern not found) | Read file again, retry with correct pattern |
| No README.md exists | Skip README update phase, note in report |
| Localized README out of sync | Only update links section, flag content sync as manual task |
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.

