update-docs
Audit and update every documentation surface in the APEX repo against the current state of skills, steering workflows, README marker tables, and the Docusaurus site under misc/website/. After any change to a skill (rename, retire, add, edit description), walk the repo, re-run scr
Install
npx skills add https://github.com/aws-samples/sample-apex-skills/tree/main/skills/update-docs
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install aws-samples-sample-apex-skills@llmmart
git clone https://github.com/aws-samples/sample-apex-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole aws-samples/sample-apex-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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 runbook under
skills/apex/runbooks/was added, removed, or renamed - README marker blocks were edited manually
- Before opening a PR that touches
skills/ - 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' 'skills/apex/runbooks/*/*.md' 'devops-agent/**'
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) | ./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/<name>/directory - A frontmatter description that was edited, where the old phrasing still appears verbatim elsewhere
- A retired runbook 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.mdCONTRIBUTING.mdCODE_OF_CONDUCT.mdTHIRD_PARTY_NOTICES.mdskills/README.md- Every
skills/<name>/README.mdwhere present - Every
skills/<name>/SKILL.md - Every
skills/apex/runbooks/<skill>/*.md devops-agent/README.md- Every
devops-agent/<name>/SKILL.md misc/README.mdmisc/evals/README.mdmisc/evals/_template/README.md- Every
misc/evals/<skill>/README.md misc/website/docs/intro.mdmisc/website/docs/getting-started.mdmisc/website/src/components/skillCatalog.tsandmisc/website/src/pages/index.tsx(not markdown; skillCatalog.ts holds each skill's catalogue lines, index.tsx names the /apex router)- The
SKILL_METAtable inmisc/update-pages.sh(each skill's page title, summary under 160 characters, and README group; a skill with no group, or a group that is not one of the README headings inmisc/update-skills-references.sh, fails the docs-sync check)
Excluded (generated by scripts — never hand-edit):
misc/website/docs/skills/*.mdmisc/website/docs/skills/index.mdmisc/website/static/manifests/skills.jsonmisc/website/static/llms.txtmisc/website/docs/skills/eks/index.mdmisc/website/docs/skills/ecs/index.md
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.
Files (sample-apex-skills)
-
SKILL.md 5.5 KB
--- name: update-docs description: Audit and update every documentation surface in the APEX repo against the current state of skills, steering workflows, README marker tables, and the Docusaurus site under misc/website/. After any change to a skill (rename, retire, add, edit description), walk the repo, re-run script-managed surfaces if their --check fails, and reason through every tracked prose *.md to catch references that need updating. Use after adding/removing/renaming a skill, after editing SKILL.md frontmatter, after editing README marker blocks, or before publishing a docs change. Also use when the user says "update docs", "sync docs", "check docs", "run update-docs", or mentions that documentation might be stale. --- # 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 runbook under `skills/apex/runbooks/` was added, removed, or renamed - README marker blocks were edited manually - Before opening a PR that touches `skills/` - 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`: ```bash git diff --name-status origin/main...HEAD -- 'skills/**/SKILL.md' 'skills/apex/runbooks/*/*.md' 'devops-agent/**' ``` 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) | `./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/<name>/` directory - A frontmatter description that was edited, where the old phrasing still appears verbatim elsewhere - A retired runbook 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/<name>/README.md` where present - Every `skills/<name>/SKILL.md` - Every `skills/apex/runbooks/<skill>/*.md` - `devops-agent/README.md` - Every `devops-agent/<name>/SKILL.md` - `misc/README.md` - `misc/evals/README.md` - `misc/evals/_template/README.md` - Every `misc/evals/<skill>/README.md` - `misc/website/docs/intro.md` - `misc/website/docs/getting-started.md` - `misc/website/src/components/skillCatalog.ts` and `misc/website/src/pages/index.tsx` (not markdown; skillCatalog.ts holds each skill's catalogue lines, index.tsx names the /apex router) - The `SKILL_META` table in `misc/update-pages.sh` (each skill's page title, summary under 160 characters, and README group; a skill with no group, or a group that is not one of the README headings in `misc/update-skills-references.sh`, fails the docs-sync check) **Excluded (generated by scripts — never hand-edit):** - `misc/website/docs/skills/*.md` - `misc/website/docs/skills/index.md` - `misc/website/static/manifests/skills.json` - `misc/website/static/llms.txt` - `misc/website/docs/skills/eks/index.md` - `misc/website/docs/skills/ecs/index.md` 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.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.