playbooks

home / skills / viteinfinite / skills / documentation-updater

documentation-updater skill

/skills/documentation-updater

This skill keeps project documentation accurate and executable by updating README, guides, and reference docs whenever core changes occur.

npx playbooks add skill viteinfinite/skills --skill documentation-updater

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

Files (1)
SKILL.md
2.6 KB
---
name: documentation-updater
description: Use when implementing features, refactors, or fixes that affect core functionality, configuration, infrastructure, or integrations. Ensures documentation stays accurate by updating README, operational guides, and reference docs, and verifying links/commands remain correct.
---

# Documentation Updater

Maintain project documentation (README, operational guides, reference docs) as a first-class part of shipping changes. Keep documentation accurate and executable as code evolves.

## When to use

Activate this Skill when:

- A change alters **how to run/test locally** (development environment setup, containerization, bootstrapping).
- You add/remove/change **environment variables**, secrets, or configuration files.
- You change **environment/deployment assumptions** used by scripts or tools.
- You add/modify **operational scripts** (deployment, data seeding, logging, maintenance tasks).
- You update **integrations** with external services or APIs.
- You modify **infrastructure** setup or deployment processes.

## Principles

1. **Prefer updating existing docs over adding new ones.** Add a new doc only when it clearly reduces confusion.
2. **Keep docs executable.** Commands must match actual scripts/tools; paths must match the project structure.
3. **Respect environment requirements.** When docs tell users to run commands/tests, include the correct environment setup steps (e.g., sourcing environment files, activating virtual environments, loading configuration).
4. **Document "what & why", not internal trivia.** Focus on user outcomes and maintenance workflows.
5. **Cross-link instead of duplicating.** Use references to maintain a single source of truth.

## Workflow

### 1) Determine doc impact from the change

Identify what category the change falls into and what docs it likely affects.

### 2) Update the smallest set of docs that restores accuracy

- Update only the relevant sections; avoid broad rewrites.
- Keep headings and tone consistent with the existing file.
- Prefer adding links from main documentation to detailed reference docs for deep dives, instead of duplicating instructions.

### 3) Add "quick verification" steps

When documenting new or changed workflows, include:

- The exact command(s) to run (use project-standard task runners or scripts).
- The expected output/behavior at a high level (1–2 bullets).
- Any common failure mode and how to fix it (1 short subsection max).

### 4) Check for drift and broken references

- Confirm referenced scripts/commands exist in the project.
- Confirm file paths and directory references exist in the repository.
- Verify external links are still valid and accessible.

Overview

This skill helps keep project documentation accurate whenever code or infrastructure changes affect usage, configuration, or operations. It focuses on updating README, operational guides, and reference docs so commands, paths, and links remain executable. Use it as part of feature work, refactors, or fixes that change how the project is run or integrated.

How this skill works

The skill inspects code changes to identify impacted documentation areas: run/test steps, environment variables, scripts, deployment flows, and external integrations. It updates the smallest set of documents needed to restore accuracy, adds quick verification steps, and verifies referenced scripts, paths, and external links. The goal is executable docs: commands and outcomes are validated against the repository structure and tooling.

When to use it

  • A change alters local run/test setup, containerization, or bootstrapping steps.
  • You add, remove, or rename environment variables, secrets, or configuration files.
  • You modify deployment assumptions, CI/CD scripts, or infrastructure code.
  • You change operational scripts (deploy, seed, backup, logging).
  • You add or update integrations with external services or APIs.

Best practices

  • Prefer updating existing sections over creating new documents unless it reduces confusion.
  • Include exact commands and the minimal environment setup required to run them.
  • Provide a brief expected outcome for each verification command and note one common failure and fix.
  • Keep language focused on what users need to do and why, not internal implementation details.
  • Cross-link to detailed reference docs instead of duplicating instructions; maintain a single source of truth.

Example use cases

  • Update README run instructions and local .env examples after adding a new configuration option.
  • Modify deployment guide when switching to a different container registry or changing image tags.
  • Add quick verification steps to operational docs after changing a database seeding script.
  • Fix broken links and script references after a repo reorganization or path rename.
  • Document new API integration credentials and the expected behavior after enabling the integration.

FAQ

How much documentation should I change for a small code tweak?

Update only the sections that are rendered inaccurate by the change. Avoid broad rewrites; prefer adding a link to a detailed reference if more context is needed.

What belongs in quick verification steps?

Exact command(s) to run, one short line describing expected output/behavior, and one common failure with its fix.