From skilled-labor
Create and update project documentation to match current code. Analyzes git changes, reads source files, and updates or creates README and doc files. Use when code has changed and docs need to catch up, or to audit docs for accuracy.
How this skill is triggered — by the user, by Claude, or both
Slash command
/skilled-labor:update-docsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Create or update project documentation so it accurately reflects the current codebase.
Create or update project documentation so it accurately reflects the current codebase.
There are two layers:
README.md (root) — The entry point. Concise. Gets someone from zero to running in minutes.docs/ directory — The deep dives. Every detail, every option, every edge case lives here.The root README links to docs. It never tries to be comprehensive itself.
Scale the docs/ layout to match the project's complexity:
Small/medium projects — flat files in docs/:
docs/
├── architecture.md # always exists — system overview, modules, data flow
├── <module>.md # one per module/service
└── ...
Multi-service projects — subdirectories per service, plus top-level overview docs:
docs/
├── architecture.md # always exists — high-level system overview, how services connect
├── deployment.md # how to deploy, infrastructure, environments, CI/CD
├── <service>/
│ ├── architecture.md # service-level internals, data model, design decisions
│ ├── <reference>.md # commands, endpoints, etc.
│ └── ...
└── ...
Rules for choosing the layout:
docs/architecture.md always exists at the top level, even with subdirectories. It covers the full system: what services exist, how they communicate, shared infrastructure, data flow between services.docs/deployment.md should exist for any project that runs in production — covers environments, infrastructure, CI/CD pipelines, secrets, monitoring, rollback procedures.architecture.md covers that service's internals: its own data model, internal design decisions, package structure. The top-level one covers how services fit together.docs/.Before anything else, understand the project:
README.md and any files in docs/package.json, pyproject.toml, Cargo.toml, go.mod, Makefile, docker-compose.yml etc. to understand the tech stack and entry pointsRun git diff --name-only HEAD to see uncommitted changes. If there are no uncommitted changes, compare against the last few commits with git diff --name-only HEAD~3..HEAD.
If the user specified a scope (e.g., a module or service name), focus only on that area.
If there are no changes at all, do a full audit — compare all existing docs against the current code.
For each changed source file, determine:
docs/architecture.md? (e.g., new services, changed data model, new storage layer, changed communication patterns)docs/deployment.md? (e.g., new env vars, changed infra, new CI steps)If a doc file doesn't exist yet but should, create it.
For each affected area:
The root README must stay concise. It should contain only these sections, in this order:
docs/ with one-line descriptionsIf the README is growing beyond ~100-150 lines, something needs to move to docs/.
docs/These can be as long and thorough as needed.
docs/architecture.md — Must always exist. Starts with the big picture, then drills down:
This is the first doc someone reads to understand how the system works. It starts high-level (what are the pieces, how do they talk) and only then goes deep. Update it whenever modules, data flow, schema, or system boundaries change.
In multi-service projects, per-service docs/<service>/architecture.md files cover that service's internals. The top-level docs/architecture.md stays focused on the system-wide view — it should not duplicate service internals.
docs/deployment.md — Should exist for any project that runs in production. Covers:
If the project is local-only or not yet deployed, skip this file. Create it when deployment becomes relevant.
Module/service docs — Full reference for each module. Content depends on the module type:
Docs should read like a connected graph, not isolated pages. A reader should never hit a dead end.
README ↔ docs:
docs/ file in its Docs sectionBetween docs:
architecture.md links to the detailed docs when mentioning a module: "The CLI exposes 20+ commands (see CLI Reference)"[entity model](architecture.md#entity-model), not just [architecture](architecture.md)Per-service docs (multi-service projects):
architecture.md links down to each docs/<service>/architecture.mdLink hygiene:
docs/ file linked from README must existdocs/ entry[CLI Reference](docs/cli.md) from README, [Architecture](architecture.md) between docs in the same directorygrep -r '](.*\.md' docs/ README.mdAfter updating, provide a brief summary of what changed in each doc file and why.
npx claudepluginhub rhedbull/skilled-labor --plugin skilled-laborAnalyzes codebase structure and updates README.md and docs/ directories to reflect current code state, including changes since last doc update. Triggers on 'update docs' or staleness checks.