home / skills / jmerta / codex-skills / docs-sync

docs-sync skill

safe

This skill keeps documentation synchronized with code changes across README, docs, API specs, runbooks, and configuration for releases.

npx playbooks add skill jmerta/codex-skills --skill docs-sync

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

2.2 KB

---
name: docs-sync
description: Keep documentation in sync with code changes across README, docs sites, API docs, runbooks, and configuration. Use when the user asks to update docs, ensure docs match behavior, or prepare docs for a release/PR.
---

# 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)
1) Identify what changed
   - Use the diff to locate impacted areas:
     - `git diff --name-only`
     - `git diff`
2) 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, see `references/docs-structure.md` for a suggested layout.
3) 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`).
4) 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.
5) 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

This skill keeps documentation aligned with code changes across README, docs sites, API specs, runbooks, and configuration. It identifies affected doc surfaces, applies small targeted edits, and delivers a clear verification checklist so docs match runtime behavior and developer expectations.

How this skill works

I inspect the git diff to find changed files and map those changes to documentation locations such as README.md, docs/, API schema files, runbooks, and changelogs. I create a short inventory of files to update, make minimal edits that include runnable examples where relevant, and produce a "files updated" list plus concrete verification steps to validate the updates.

When to use it

When a feature, bugfix, or refactor changes behavior that users or developers rely on
Before opening a release PR to ensure docs are release-ready
When a reviewer requests documentation updates alongside code changes
When API contracts, env vars, or setup steps have changed
When preparing onboarding materials or runbooks for operational tasks

Best practices

Start from git diff --name-only and git diff to locate impacted docs quickly
Prefer small, targeted edits and keep headings stable to preserve links
Include copy/paste runnable examples for setup, API calls, and migrations
Update API schemas (OpenAPI, GraphQL) and request/response examples together
Run existing doc checks (mdlint, docs site build) or at least verify code fences and env var names

Example use cases

A change renames an environment variable used in bootstrap; update README, runbooks, and examples
An API endpoint changes shape; update OpenAPI, API docs, and sample curl/json payloads
A refactor moves CLI commands; update CONTRIBUTING.md and developer setup docs
A new feature requires a database migration; add migration steps to setup and runbook
Preparing docs for a release: consolidate changelog entries, update README highlights, and verify docs site build

FAQ

What inputs do you need to start?

Tell me what changed (feature/bugfix/refactor), who the docs are for, and which doc surfaces matter (README, docs/, runbooks, API spec).

How do you minimize churn in docs?

I make small focused edits, keep headings stable, reuse templates, and add runnable examples instead of large rewrites.