AgentSkillsCN

docs-after-change

在每次代码变更后强制执行。确保文档字符串、README以及架构/文档内容与新行为保持一致。

SKILL.md
--- frontmatter
name: docs-after-change
description: Mandatory after any code change. Ensures docstrings, README, and architecture/docs stay consistent with the new behavior.

docs-after-change

This skill is mandatory after any code change (including refactors). It is optimized to keep repository documentation accurate without doing unnecessary full-repo audits.

When to use

  • •Use this skill after you make any code changes (add/edit/delete/rename).
  • •Use this skill before finishing the task / handing control back to the user.

Goal

Keep documentation and developer UX up-to-date by validating and updating:

  • •Docstrings in changed runnable scripts (and other touched modules where docstrings are used as primary docs)
  • •README(s) that document entrypoints, setup, env vars, and outputs
  • •Architecture docs (e.g., architecture.md) when flow/structure changes

Inputs (what you should consider as “code change”)

  • •Python files (.py)
  • •Configuration files (.yml/.yaml, .toml, .json, .env.example) that affect runtime behavior (models, providers, pipelines)
  • •Docker/Kubernetes/deployment manifests
  • •Migrations / schema changes / database models
  • •Anything that changes CLI flags, environment variables, output folders, or the pipeline stages

Instructions (do these steps in order)

1) Identify what changed and what it impacts

  • •Determine the scope of changes:
    • •CLI/entrypoints (e.g., app/main.py, app/scripts/*, python -m ...)
    • •Configuration (e.g., pyproject.toml, *.yml, .env.example, provider/model selection)
    • •Outputs (folders, file formats, naming conventions)
    • •Architecture (module boundaries, new stages, new services, data flow)
    • •Tests (new workflows, changed assumptions)

2) Docstrings: update runnable scripts and public entrypoints

For any file intended to be executed as a script or documented as an entrypoint:

  • •Ensure a top-level module docstring exists and is accurate:
    • •Brief one-liner of what it does
    • •Inputs (files, env vars, CLI args) with enough detail to be self-explanatory (each CLI flag should have a short purpose + expected format)
    • •Outputs (files, stdout, DB writes)
    • •Usage example from project root using python -m ...
  • •Ensure side effects do not run at import time (work in main()).
  • •Ensure CLI args in docstring match actual argparse behavior.

If the file is not runnable but is a “public” module (commonly imported or referenced in docs), ensure key functions/classes have docstrings where they clarify non-obvious behavior or invariants.

Additionally (general rule): ensure every function and method you touched has a docstring.

  • •Trivial functions/methods: a one-liner is enough.
  • •Non-trivial or side-effecting functions/methods: describe inputs/outputs, side effects, and raised exceptions when non-obvious.

3) README updates: keep developer instructions truthful

Update README.md if any of these changed:

  • •Installation steps (pip, uv, requirements.txt vs pyproject.toml)
  • •Required environment variables / keys
  • •Example commands (python -m ...) and their flags
  • •Output directories / filenames / structure
  • •Typical workflows (single input vs batch, optional stages/flags, performance/quality tradeoffs)
  • •Model/provider configuration examples

Checklist:

  • •Keep examples runnable (command names, paths, flags).
  • •Avoid adding secrets; only document them in .env.example.
  • •If you introduce a new required env var, ensure it appears in .env.example and is referenced in README.md.

4) Architecture docs: update when structure/flow changes

Update architecture.md (and any other architecture documents) if you changed:

  • •Module responsibilities and boundaries
  • •Data flow between stages
  • •Components/services that exist or no longer exist
  • •Persistence/storage strategy (DB schemas, linking/mapping strategy if applicable, output formats)

Rules of thumb:

  • •If diagrams mention classes/modules that don’t exist anymore, fix the diagram.
  • •If a new stage is added, document it and show where it reads/writes.

5) Consistency pass

  • •Ensure terminology matches across docs (stage names, folder names, pipeline steps).
  • •Ensure paths are consistent (relative to project root).
  • •Ensure references to “source of truth” are consistent (e.g., dependency management policy).

6) Report what you changed

In the final response, include:

  • •Which docs you reviewed
  • •Which docs you changed and why (1–3 bullets)
  • •Any docs you intentionally did not change (and why)

Non-goals (what NOT to do)

  • •Do not run a full-repo audit here (use /repo-doc-audit for that).
  • •Do not rewrite docs for style; focus on correctness and minimal updates.