docs-sync
Scannednpx machina-cli add skill jmerta/codex-skills/docs-sync --openclawFiles (1)
SKILL.md
2.2 KB
Docs sync
Goal
Update documentation so it matches the current code and is easy for the target audience to follow.
Inputs to ask for (if missing)
- What changed (feature/bugfix/refactor) and who the docs are for.
- Which docs surfaces matter: README,
/docs, wiki, runbooks, API spec, changelog, onboarding. - Any required format/voice (company style guide, "keep it short", etc.).
Workflow (checklist)
- Identify what changed
- Use the diff to locate impacted areas:
git diff --name-onlygit diff
- Use the diff to locate impacted areas:
- Inventory docs surfaces in the repo
- Common locations:
README.md,docs/,CONTRIBUTING.md,CHANGELOG.md,openapi.*,schema.graphql,adr/,runbooks/. - For Spring: check for generated OpenAPI/Swagger docs or endpoint annotations.
- For Next/TypeScript: check for docs pages, Storybook, or typed API clients.
- If your repo uses
docs/as the primary doc root, seereferences/docs-structure.mdfor a suggested layout.
- Common locations:
- Decide what needs updating
- Ensure docs cover:
- setup and local dev commands
- required env vars / config keys
- API contract changes (request/response examples)
- DB migrations and operational steps
- behavior changes visible to users
- If the change is an architectural/behavioral decision, add or update an ADR (use
references/adr-template.md).
- Ensure docs cover:
- Apply edits with minimal churn
- Prefer small, targeted edits over rewrites.
- Add examples that are copy/paste runnable.
- Keep headings stable to avoid breaking deep links.
- Use templates in
references/when helpful.
- Verify docs are consistent
- Run the repo's existing doc checks if present (md lint, docs build, site build).
- At minimum: ensure code fences match the actual commands and file paths, and env var names match the code.
Deliverable
Provide:
- The list of docs files updated and why.
- A short "How to verify" section (commands or manual checks).
Overview
Docs-sync ensures documentation mirrors code across README, docs sites, API docs, runbooks, and configuration. It guides identifying changes, mapping affected surfaces, and delivering consistent docs for releases or PRs.
How This Skill Works
Identify changes with git diff to locate impacted docs surfaces, then inventory locations like README.md, docs/, CHANGELOG.md, and OpenAPI specs. Decide what to update (setup, env vars, API contracts, migrations) and apply targeted edits with stable headings. Finally verify with md lint or docs/site build.
When to Use It
- A feature, bugfix, or refactor requires updated docs to match current behavior.
- Preparing a release or PR and ensuring docs align with code.
- API or config contracts change (request/response formats, env vars, keys).
- User-visible behavior changes that should be documented in runbooks or guides.
- New docs surfaces (README/docs/CHANGELOG/openapi) need alignment.
Quick Start
- Step 1: Run git diff to identify changed files and impacted docs.
- Step 2: Inventory affected surfaces (README, docs/, API specs, runbooks, changelog).
- Step 3: Apply minimal edits and verify against doc checks (mdlint, build).
Best Practices
- Prefer small, targeted edits over rewrites to minimize churn.
- Keep headings stable to avoid breaking deep links and anchors.
- Include runnable, copy/paste-ready examples.
- Run existing doc checks (md lint, site/build) to verify consistency.
- Use templates in references/ (e.g., ADR) for architectural decisions.
Example Use Cases
- Added a new feature; updated API docs, README, and changelog to reflect endpoints and usage.
- Renamed a config key; updated docs surfaces and example commands accordingly.
- Incident prompted a new runbook step; documented in runbooks/ and updated openapi contract.
- Generated OpenAPI/Swagger docs updated; refreshed endpoint descriptions and examples.
- Architectural decision documented via ADR template and related docs.
Frequently Asked Questions
Add this skill to your agents
