Our review
Ensures repository documentation stays aligned with code changes by checking relevant docs, updating them alongside code, and recording durable decisions.
Strengths
- Promotes immediate doc updates in the same change as code, reducing drift.
- Explicitly directs decisions to a durable log or ADR rather than chat.
- Encourages concise, operational docs.
- Prevents unnecessary rewrites and respects historical decisions.
Limitations
- Relies on existing doc structure (README, docs/DECISIONS.md, ADRs); if absent, may need to create them.
- Does not specify exact formats or templates for ADRs.
- May require judgment on what constitutes 'public behavior' or a 'durable decision.'
When code changes affect user-facing behavior, commands, validation evidence, or workflow, and docs need to stay current.
For minor internal refactors with no user-facing impact, or when documentation is intentionally frozen for a release.
Security analysis
SafeThe skill only provides documentation synchronization guidance; it does not instruct execution of destructive, exfiltrating, or obfuscated actions, and declares no allowed tools.
No concerns found
Examples
I've added a `--dry-run` flag to the deploy command. Please update the README and any relevant docs to reflect the new option, and add a note in DECISIONS.md.We decided to switch from REST to gRPC. Record this decision in docs/DECISIONS.md or a new ADR, and update all affected documentation as part of this change.The test suite now requires a local Postgres instance. Update the setup instructions in README and note the validation change in the docs.name: docs-sync description: Use when behavior, setup, validation, public wording, data provenance, or workflow commands change and repository documentation may need to be updated.
Docs Sync
- Check
README.md,docs/DECISIONS.md, relevant docs underdocs/, and any ADRs. - Update docs in the same change as code when public behavior, commands, assumptions, or validation evidence changes.
- Record durable decisions in
docs/DECISIONS.mdor a new ADR; do not bury decisions only in chat. - Keep docs concise and operational: what changed, why, how to run it, and what remains out of scope.
- Avoid rewriting unrelated docs or changing historical decisions except to add a dated superseding note.
API Documentation Generator
Documentation
Automatically generates OpenAPI/Swagger API documentation.
Technical Writer
Documentation
Writes clear technical documentation following top style guides.
Create a DESIGN.md
Documentation
Generate a complete DESIGN.md file for any website or app to document design systems in a format AI agents can read.