Claude Skill

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

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download aws-samples-sample-apex-skills-skills_update-docs-3ab6c5d.zip · 2 KB

Install

skills CLI npx skills add https://github.com/aws-samples/sample-apex-skills/tree/main/skills/update-docs
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install aws-samples-sample-apex-skills@llmmart
Git 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.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.

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.

No comments yet.

Reviews (0)

No reviews yet.