update-project-docs skill
✓ VerifiedSynchronizes task.md, changelog.md, and files.md with the actual git history and source code to ensure documentation accuracy.
- GitHub stars
- 404
- Files
- 6
- Last commit
- Nov 9, 2026
- License
- Apache-2.0
- Allowed tools
- —
What does the update-project-docs skill do?
update-project-docs synchronizes task.md, changelog.md, and files.md with the actual git history and source code to ensure documentation accuracy.
Summary generated from the skill's SKILL.md.
About the update-project-docs skill
Maintaining accurate project documentation is what this skill enables for developers who need to keep their task lists, changelogs, and file descriptions in sync with their actual code. When a feature is finished or a bug is fixed, an agent can load this skill to analyze the git history and the current working tree. It produces updated versions of task.md, changelog.md, and files.md based on concrete evidence found in the repository rather than conversation history.
The process relies on git commands like git log, git status, and git diff to verify what has actually shipped. It is specifically designed to prevent documentation drift by refusing to log features that are not visible in the source code. The tool also includes safety measures to scan for secrets or personal data before saving any changes. Instead of performing git operations directly, it provides a plain text commit message for the user to use, ensuring the developer remains in control of the repository state.
What an agent can do with it
- 1Synchronize documentation after a feature launchUpdate the task list, changelog, and file descriptions to reflect a newly completed feature based on the git diff.
- 2Document new source filesAutomatically add descriptions for new files to files.md by analyzing the changes in the working tree.
- 3Verify task completion statusMove items from in-progress to completed in task.md only if the necessary verification steps have been confirmed.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the update-project-docs skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the update-project-docs skill in Plugin
/plugin marketplace add waynesutton/builder-skills /plugin install builder-skills@waynesutton
Install the update-project-docs skill in Claude Code
~/.claude/skills/update-project-docs/SKILL.md
$ npx degit waynesutton/builder-skills/skills/update-project-docs ~/.claude/skills/update-project-docsInstall the update-project-docs skill in Claude Code (project)
.claude/skills/update-project-docs/SKILL.md
$ npx degit waynesutton/builder-skills/skills/update-project-docs .claude/skills/update-project-docsInstall the update-project-docs skill in Codex
~/.agents/skills/update-project-docs/SKILL.md
$ npx degit waynesutton/builder-skills/skills/update-project-docs ~/.agents/skills/update-project-docsInstall the update-project-docs skill in Gemini CLI
~/.gemini/skills/update-project-docs/SKILL.md
$ npx degit waynesutton/builder-skills/skills/update-project-docs ~/.gemini/skills/update-project-docsInstall the update-project-docs skill in Claude.ai
npx degit waynesutton/builder-skills/skills/update-project-docs update-project-docs && zip -r update-project-docs.zip update-project-docs # claude.ai → Customize → Skills → + → Create skill → Upload a skill → update-project-docs.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablewaynesutton/builder-skills/skills/update-project-docs is public and reachablegithub.com/waynesutton/builder-skills/tree/HEAD/skills/updat ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-09github.com/waynesutton/builder-skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/waynesutton/builder-skills/blob/HEAD/skills/updat ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/waynesutton/builder-skills/blob/HEAD/skills/updat ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 123 linesgithub.com/waynesutton/builder-skills/blob/HEAD/skills/updat ↗Pass
SKILL.md
View on GitHubUpdate project docs
Activate with /update, @update, update project docs, or sync project docs.
Three files describe a project to the next person who opens it. Keep them true.
| File | Answers |
|---|---|
task.md |
What is planned, in flight, and done |
changelog.md |
What changed for users, by version and date |
files.md |
What each file is for |
Truth comes from the repo, not from the conversation. If the diff does not show it, it did not ship.
Run the sync
- Find the root.
git rev-parse --show-toplevel, or the workspace root without git. - Collect evidence.
git log --date=short -n 20,git status --short,git diff --stat, and for the current changegit diff HEAD --stator the staged diff. See references/evidence-rules.md for what counts. - Read all three files as they are. Note the last logged date and the last completed task.
- Update each file. Rules below.
- Check idempotency. If nothing new landed since the last entry, change nothing and say so.
- Scan for secrets and personal data before saving. See the redaction section.
- Print the commit message. Rules below.
- Report in a few lines. Show the new changelog entry or say the docs were already current.
task.md
Sections: ## To Do, ## In Progress, ## Completed.
- Move an item to Completed only if its verification step ran. If the PRD lists a check that has not run, leave it In Progress and say which check is pending.
- Completed entries:
- [x] YYYY-MM-DD HH:mm UTC <what>. <PRD path if any>. <files touched>. Verified: <command or outcome>. - Never delete history. Old completed items stay.
- If
task.mddoes not exist, create it with the three headings and the current change under Completed or In Progress based on the evidence.
changelog.md
Keep a Changelog format. ## [Unreleased] at the top, then ## [x.y.z] - YYYY-MM-DD blocks, each with ### Added, ### Changed, ### Fixed, ### Removed as needed.
- Dates come from
git log --date=short. The release date is the date of the commit that bumped the version, or today's UTC date if it has not been committed yet. Never a placeholder, never a future month. - Write for the user of the project, not the author. "Uploads over 5 MB now show a progress bar" beats "refactored upload hook".
- One line per change. Group related commits.
- Do not log dependency bumps, formatting, or generated files unless they change behavior.
- If a version bump exists in
package.jsonwith no matching heading, add the heading.
files.md
One line per file that matters. Grouped by folder.
## convex/
- `schema.ts` tables and indexes
- `stats.ts` heartbeat mutation with 10s dedup window, page view inserts
## src/hooks/
- `usePageTracking.ts` sends heartbeats, debounced 5s, path change aware
- Add every new source file from the diff.
- Fix descriptions that the diff made wrong.
- Skip
node_modules,_generated, lockfiles, build output, and assets unless they are hand written. - Keep each description under one line. What it is for, not how it works.
Convex projects
When the repo has a convex/ folder, the changelog and files.md can name Convex features, but only ones the source proves. references/convex-detection.md lists what file shows what.
Short version:
- A component counts only if
convex/convex.config.tsregisters it. A dependency inpackage.jsonis not proof. - Crons count only if
convex/crons.tsexists and registers a job. - HTTP actions count only if
convex/http.tshas a route. - Auth counts only if
convex/auth.config.tsor an auth component is present. - AI model names count only if code or config names them. Do not guess which model built the app.
Prefer none over an invented value.
Redaction
changelog.md and files.md are often public. Treat them that way.
- Never open
.env,.env.local, or any secret store to fill in a doc. Env var names are fine to mention. Values never. - Never include API keys, tokens, email addresses, phone numbers, street addresses, private hostnames, or application data records.
- Scan the whole file before saving, not just the new lines. Replace any address shaped text with
[redacted]and say so in one line. - Log behavior, not identifiers. "Signed webhook verification for inbound mail" is fine. The inbox address is not.
Boundaries
- Edit only
task.md,changelog.md,files.md, and PRDs the user points at. Nothing else unless asked. - Never commit, push, deploy, publish, or tag. Print the suggested commit message instead.
- Never rewrite older entries for tone. Fix facts when the evidence contradicts them and flag the correction.
- Do not call production APIs or query live data to make the docs richer.
Commit message
After syncing, print the commit message as plain text in a code block. No git add, no git commit, no heredoc, no shell at all.
<type>: <short summary of the main change>
- optional bullet when the change touches more than two concerns
- Type is one of
feat,fix,docs,style,refactor,test,chore. - Present tense, subject under 50 characters, no period at the end.
- A docs only sync uses
docs: sync task, changelog, and files.
Report format
Synced project docs.
changelog.md added 2.1.0 (2026-09-15): 3 added, 1 fixed
files.md added 2 files, updated 1 description
task.md moved 1 item to Completed, 1 still In Progress (verification pending: e2e)
Suggested commit: docs: sync changelog, files, and tasks for 2.1.0
Files in this skill
6update-project-docs skill questions
How do I install the update-project-docs skill in Claude Code?
Run npx degit waynesutton/builder-skills/skills/update-project-docs ~/.claude/skills/update-project-docs. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the update-project-docs skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What files does this skill update?
The skill synchronizes task.md, changelog.md, and files.md to ensure they reflect the current state of the repository.
How does the skill determine what has actually changed?
It relies on git history and the working tree rather than conversation memory, ensuring that only changes visible in the source code are logged.
Does this skill automatically commit changes to my repository?
No, the skill will not commit, push, or deploy; it only prints a suggested commit message as plain text.