Update Docs

Update Docs

Walk the APEX repo after any content change and bring every documentation surface back into sync. Two categories of surface exist: script-managed (deterministic, re-runnable) and prose (requires reasoning). Handle both in a single pass.

When to use

• A skill was added, removed, renamed, or had its frontmatter edited
• A steering workflow was added, removed, or renamed
• README marker blocks were edited manually
• Before opening a PR that touches skills/ or steering/
• The user asks to "check docs", "update docs", or "sync documentation"

Modes

Coding-agent mode (default in Claude Code): walk the repo, re-run scripts, propose diffs, ask before writing user-facing prose. Auto-apply mechanical fixes (script outputs, simple name substitutions in fenced code blocks).

Chat-only mode (no file-write tools available): emit the PASS/STALE table + a fix checklist of one-line commands. No file edits.

Step 1: Detect the change set

Determine what changed. Default comparison base is origin/main:

git diff --name-status origin/main...HEAD -- 'skills/**/SKILL.md' 'steering/workflows/*.md' 'steering/commands/**/*.md'

If the user specifies a different scope ("since my last commit", "just the rename I did"), adjust the base accordingly. Also include any paths the user explicitly names.

Step 2: Tier 1 — Script-managed surfaces

Two scripts own deterministic regeneration. Detect staleness and re-run them. Never duplicate their logic.

| Surface | Stale when | Fix | |---|---|---| | Marker blocks (README.md, skills/README.md, steering/**/*.md) | ./misc/update-all-references.sh --check exits non-zero | ./misc/update-all-references.sh | | Docusaurus wrappers, manifest, skills index | ./misc/update-pages.sh --check exits non-zero | ./misc/update-pages.sh |

Run both --check commands. If either exits non-zero, re-run the corresponding script. In coding-agent mode, apply the changes directly. In chat-only mode, emit the fix command.

Step 3: Tier 2 — Prose ripple

Read each file in the candidate set below. Hold the change set in mind and look for stale references.

What "stale" looks like

• A skill name in prose that no longer matches a skills// directory
• A frontmatter description that was edited, where the old phrasing still appears verbatim elsewhere
• A retired steering workflow still referenced in a list
• A skill count or coverage claim ("APEX ships six skills") that no longer matches reality
• A path link skills/old-name/ after a rename
• A removed or renamed concept still mentioned in contributor guidance

Candidate set (tracked files only — use git ls-files)

In scope:

• README.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• THIRD_PARTY_NOTICES.md
• skills/README.md
• Every skills//README.md where present
• Every skills//SKILL.md
• Every tracked *.md under steering/
• misc/README.md
• misc/evals/README.md
• misc/evals/_template/README.md
• Every misc/evals//README.md
• misc/website/docs/intro.md
• misc/website/docs/getting-started.md
• misc/website/src/pages/index.tsx (not markdown but contains skill-name copy)

Excluded (generated by scripts — never hand-edit):

• misc/website/docs/skills/*.md
• misc/website/docs/steering/*.md
• misc/website/docs/skills/index.md
• misc/website/static/manifests/skills.json

For each file, if you find stale content:

• In coding-agent mode: propose the diff. For user-facing prose changes, ask before applying. For mechanical substitutions (path renames in code fences, skill-name swaps in lists), apply directly.
• In chat-only mode: add to the checklist with file, line, and what to change.

Step 4: Final output

Always end with a summary table:

| Surface | Status | Action taken | Confirm? |
|---|---|---|---|
| Marker blocks | PASS | — | — |
| Docusaurus wrappers | STALE | Re-ran ./misc/update-pages.sh | — |
| README.md | STALE | Proposed diff | yes (line 42 prose) |
| CONTRIBUTING.md | PASS | — | — |
| skills/README.md | PASS | — | — |
| misc/evals/*/README.md | PASS | — | — |
| ... | | | |

Status values: PASS (no changes needed), STALE (changes applied or proposed), SKIP (file doesn't exist yet).

Rows marked Confirm? yes require the user's approval before the change is final. Wait for their response before moving on.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aws-samples
• Source: aws-samples/sample-apex-skills
• License: MIT-0
• Homepage: https://aws-samples.github.io/sample-apex-skills/

Install and usage instructions live in the source repository linked above.