# 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 script-managed surfaces if their --check fails, and reason through every tracked prose *.md to catch references that need…

- **Type:** Skill
- **Install:** `agentstack add skill-aws-samples-sample-apex-skills-update-docs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aws-samples](https://agentstack.voostack.com/s/aws-samples)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT-0
- **Upstream author:** [aws-samples](https://github.com/aws-samples)
- **Source:** https://github.com/aws-samples/sample-apex-skills/tree/main/skills/update-docs
- **Website:** https://aws-samples.github.io/sample-apex-skills/

## Install

```sh
agentstack add skill-aws-samples-sample-apex-skills-update-docs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`:

```bash
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](https://github.com/aws-samples)
- **Source:** [aws-samples/sample-apex-skills](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aws-samples-sample-apex-skills-update-docs
- Seller: https://agentstack.voostack.com/s/aws-samples
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.