refresh-docs

name	refresh-docs
description	Use when the user asks to refresh local reference docs, rerun `./scripts/refresh-docs.sh`, review the latest `docs/references/CHANGES.md` entry, or produce/update `docs/references/CHANGES-REPORT.md`. Trigger phrases include "refresh docs", "refresh references", "update references", "check what the refresh changed", "write the changes report". Scoped to repos that ship this specific Axon/Repomix reference-docs pipeline — requires the host project to provide `./scripts/refresh-docs.sh` and a `docs/references/` tree. Does not apply to generic documentation, README, or doc-generator refreshes in other repos.
allowed-tools	Bash(./scripts/refresh-docs.sh *), Bash(*archive-changes-report.sh *), Bash(rg *), Bash(find *), Bash(sed *), Bash(awk *), Read, Write

Refresh Docs Impact Review

Run the reference refresh first, then review the exact changed reference files and produce an implementation impact report. Do not make application code changes as part of this skill.

Upstream reference checks for this skill:

• docs/references/INDEX.md
• ./scripts/refresh-docs.sh
• docs/references/CHANGES.md
• docs/references/CHANGES-REPORT.md
• the changed files under docs/references/ named by the latest CHANGES.md entry

Refresh Run

./scripts/refresh-docs.sh

Use the script's options when the user asks for a narrower or non-writing run:

./scripts/refresh-docs.sh --dry-run
./scripts/refresh-docs.sh --skip-crawl
./scripts/refresh-docs.sh --skip-repomix

--dry-run prints planned work and does not update docs/references/CHANGES.md. --skip-crawl refreshes Repomix XML packs and sparse-cloned FastMCP/mcporter docs only. --skip-repomix refreshes only Axon-crawled ACP, MCP, and Claude Code docs; it also skips FastMCP and mcporter sparse docs because those are refreshed in the Repomix phase. The script rejects using both skip flags together.

Reference Change Log

if [ -f docs/references/CHANGES.md ]; then
  awk '
    /^## / {
      if (entry != "") {
        latest = entry
      }
      entry = $0 ORS
      next
    }
    entry != "" {
      entry = entry $0 ORS
    }
    END {
      printf "%s", entry != "" ? entry : latest
    }
  ' docs/references/CHANGES.md
else
  echo "docs/references/CHANGES.md does not exist"
fi

Reference Summary

printf 'reference files: '
find docs/references -type f | wc -l
find docs/references -maxdepth 3 -type f \
  | sed 's#^docs/references/##' \
  | awk -F/ '{ print $1 "/" ($2 ? $2 : "") }' \
  | sort \
  | uniq -c

Workflow

1. Read the latest entry in docs/references/CHANGES.md.
2. Normalize changed paths from the latest entry by removing list markers, surrounding backticks, and any leading whitespace inside the backticks before resolving under docs/references/.
3. Review every file listed as added, modified, or removed in that latest entry. For removed files, compare by slug/path intent against added or current files when possible. For large XML packs, search within the pack for relevant changed areas instead of loading the whole file at once.
4. Cross-reference the changed reference material against the implementation using rg, find, and focused file reads. Check Rust crates, scripts, skills, docs, configs, and generated contract surfaces.
5. Cross-check against docs/references/INDEX.md so the report uses the current reference layout and source names.
6. Identify any code, docs, config, tests, schemas, skills, scripts, or workflows that should change because of the refreshed references.
7. Identify new capabilities, commands, protocol features, examples, or workflows that the project could add because of the refreshed references.
8. Before writing a new report, run <skill-dir>/scripts/archive-changes-report.sh.
9. Write the new report to docs/references/CHANGES-REPORT.md using references/CHANGES-REPORT-template.md as the structure.

./scripts/refresh-docs.sh excludes docs/references/CHANGES.md, docs/references/CHANGES-REPORT.md, and docs/references/archive/changes-reports/* from the detected file-change set. Do not treat those generated report/log files as upstream reference changes.

The full refresh currently covers:

• Axon crawls copied from AXON_OUTPUT_DIR for agentclientprotocol.com, modelcontextprotocol.io, and code.claude.com.
• Repomix XML packs for ACP, MCP, FastMCP, jmagar/aurora-design-system, jmagar/lab with docs/references/** ignored, and mcporter.
• Sparse checkouts for PrefectHQ/fastmcp/docs/cli as flat top-level .mdx files and openclaw/mcporter/docs recursively.

Bundled Resources

• references/CHANGES-REPORT-template.md: use this as the required report structure.
• references/CHANGES-template.md: documents the append-only docs/references/CHANGES.md entry format generated by ./scripts/refresh-docs.sh.
• scripts/archive-changes-report.sh: run this before creating a new CHANGES-REPORT.md.

Report Requirements

The report must include frontmatter with at least:

• title
• generated_at
• source_changes_log
• reviewed_change_entry
• reviewer

The report body must include:

• Latest refresh summary.
• Every changed reference file reviewed, with status.
• Upstream reference paths used for the review.
• Affected implementation areas and exact file paths.
• Required changes, if any.
• New additions or opportunities enabled by the refreshed references.
• Tests or verification that should be run before implementing any follow-up work.
• Unknowns or areas needing human/product judgment.

If no local code changes are needed, say that explicitly and explain why.