github-readme-maintenance

GitHub README and Documentation Maintenance

Use this skill for edits where the goal is to keep repository-facing Markdown documentation accurate, current, and review-friendly.

Scope

Apply this skill when editing:

• README.md and similar top-level docs
• AGENTS.md, CLAUDE.md, and other agent-facing repository guidance
• Community megathread catalogs or link indexes
• Repository runbooks, contribution guidance, and operational playbook docs

For agent-facing guidance, document stable architecture, ownership boundaries, generated-file rules, safety invariants, and executable verification commands. Do not copy temporary campaign state, process IDs, review generations, or acceptance SHAs into durable repository instructions.

Operating assumptions

• You may be working in a repository that exists in more than one local checkout.
• The expected change is usually a small, localized edit.
• The safest path is to treat target path/branch as explicit inputs.

Canonical workflow

1. Pin the target repository path and branch first

TARGET_REPO=/path/to/repo
git -C "$TARGET_REPO" remote -v
git -C "$TARGET_REPO" rev-parse --abbrev-ref HEAD
git -C "$TARGET_REPO" status --short

• If you have multiple local clones, verify all candidates before editing.

1. Verify target file and section context before changing anything

git -C "$TARGET_REPO" ls-tree -r --name-only HEAD -- README.md megathreads | sed -n '1,120p'
git -C "$TARGET_REPO" show origin/main:README.md | sed -n '1,120p'

• Confirm the file exists in the working HEAD and that the section you plan to modify is in the expected place.

1. Ground architectural guidance in the accepted implementation

• Inspect the current agent guide, final accepted commits, production entry points, generated artifacts, and canonical package scripts before writing.
• Reconcile counts and names mechanically when possible (for example, parse the generated tool-schema JSON rather than counting a long list by eye).
• Name the authoritative source and generated outputs separately. State “do not edit generated files directly” only when the repository actually provides a regeneration path.
• Convert completed feature work into stable class-level guidance: architecture, trust boundaries, default-off/fail-closed behavior, lifecycle ownership, and the commands future agents must run.
• Keep historical implementation milestones and one-time acceptance evidence out of AGENTS.md; link to a durable design or evidence document if history is genuinely needed.