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.

2. 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.

3. 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.

4. Edit minimally, with explicit list/link formatting rules

• Keep Markdown bullets as plain list syntax (- item).
• Keep link text and relative paths consistent with surrounding style.
• Avoid broad refactors for single-link updates.

5. Validate the edit before finalizing

git -C "$TARGET_REPO" diff -- README.md

• If the file is README.md, ensure only intended lines changed.
• If formatting drift is detected, fix it before creating a PR.
• For requests to remove screenshots, photos, badges, or diagrams "from the page," remove the Markdown/HTML references first. Do not delete the underlying asset files unless the user explicitly asks to remove them from the repository or they are confirmed unused everywhere.

5. Publish and verify the rendered result when requested

• Before publication, recheck the exact checkout, branch, HEAD, Git locks, and absence of another writer.
• For a deletion-only documentation diff, confirm no added lines exist; this tightly bounds new credential and local-identifier risk while preserving the repository's normal publication gates.
• After pushing, verify the remote branch SHA matches the local commit.
• Read the raw remote README and confirm the removed references or section text are absent.
• Fetch the public repository page to confirm GitHub renders the new commit, then wait for that exact commit's required CI checks when present.
• If push output and an independent remote-SHA comparison both prove success, a credential-helper warning that only affects storage/readback is not a failed publication. Escalate only if authentication or remote verification failed.

6. Prepare handoff output

• Report exact files changed.
• State whether assets were merely unreferenced or actually deleted.
• Report the verified commit/link and CI result when publication was in scope.
• Report whether change scope is minimal and cleanly reviewable.

Common pitfalls

• Wrong checkout edits: editing the same repo from a secondary clone can produce unlinked commits and confusing diffs.
• Unverified paths: adding a missing/nonexistent link target in a README undermines trust more than no change.
• List corruption: an accidental |- or similar table-row fragment can hide in a diff and break section structure.
• Scope creep: avoid adding unrelated docs or formatting cleanup during a targeted link update.

Verification checklist

• target path, remote, and branch confirmed
• target section and path verified in working tree and upstream snapshot
• final diff scoped to intended doc change
• markdown structure still consistent with surrounding sections
• changes ready for PR review with no unrelated churn
• General README/session checklist:
• Post-feature AGENTS.md/CLAUDE.md architecture refresh: