Agent-Skills.md

Agent Skills: Docs Align

Align docs with code. Detect drift and update ADRs, specs, README, AGENTS. Use after implementation or for docs drift reviews. Not for code review fixes or platform architecture.

UncategorizedID: bjornmelin/dev-skills/docs-align

Repository

bjornmelin/dev-skills
BjornMelin
8

Install this agent skill to your local

pnpm dlx add-skill https://github.com/BjornMelin/dev-skills/tree/HEAD/skills/docs-align

Skill Files

Browse the full folder contents for docs-align.

Download Skill

Loading file tree…

skills/docs-align/SKILL.md

Skill Metadata

Name
docs-align
Description
Align docs with code. Detect drift and update ADRs, specs, README, AGENTS. Use after implementation or for docs drift reviews. Not for code review fixes or platform architecture.

Docs Align

Use this skill after implementation work or when you suspect documentation drift.

Workflow

  1. Read the repo AGENTS.md.
  2. From this skill root (directory containing SKILL.md), run drift collection (requires git on PATH):
    • python3 scripts/docs_drift.py collect --cwd <repo> --out <json>
    • Equivalent collect-only shortcut: python3 scripts/check_docs_drift.py --cwd <repo> --out <json>
  3. python3 scripts/docs_drift.py compare --input <json> --out <json>
  4. Render the summary:
    • python3 scripts/docs_drift.py render --input <json> --format md
  5. Use Alignment policies below only for doc surfaces that the gap map says are in scope.
  6. Update docs only after the gap map is clear.

Path note

Commands above assume the current working directory is this skill’s root (skills/docs-align in this repository). If the working directory is elsewhere, invoke the same files with an absolute path, for example:

python3 "<skill-dir>/scripts/docs_drift.py" collect --cwd <repo> --out <json>

Alignment policies

ADR

Create or update an ADR when the implementation changed:

  • architecture boundaries
  • execution model
  • durable workflow policy
  • major dependencies or infrastructure choices

Do not create ADR churn for small local refactors.

Spec

Update product or architecture specs when the implementation changed:

  • interfaces
  • contracts
  • verification steps
  • operational behavior

Prefer deleting stale spec text over leaving contradictory guidance.

README

Update the README when the change affects:

  • setup
  • commands
  • environment variables
  • high-level architecture or usage expectations

Keep the README high signal; move deep details into docs when needed.

Use When

  • The task is post-implementation doc alignment.
  • The user wants README, ADR, spec, or AGENTS updates based on code changes.

Do Not Use When

  • The task is only code review remediation.
  • The task is only dependency planning.

Outputs

  • likely impacted docs
  • missing/update/delete doc tasks
  • a concise docs alignment summary