refresh-catalog

/refresh-catalog

Force a fresh regeneration of the dispatch catalog and report the results.

When to use this skill

The bundled refresh-catalog-on-stale.js hook (see Bundled hooks) automatically rebuilds the catalog when a source file (skill sidecar or agent frontmatter) is newer than the catalog itself. This skill exists for cases the mtime heuristic misses or when you want to force a rebuild for debugging:

• A sidecar edit did not bump a watched path's mtime.
• You edited the catalog directly and want to overwrite with a clean rebuild.
• You are diagnosing a [CATALOG ERROR] or [CATALOG STALE] banner.

Step 1: Record the catalog mtime before regeneration

Read the mtime of the catalog before running the generator. The catalog path is resolved from $DISPATCH_CATALOG_PATH if set, otherwise the documented default ~/.claude/dispatch-catalog.json. If the file does not exist, note "catalog absent before run".

python -c "
import os, datetime
p = os.environ.get('DISPATCH_CATALOG_PATH') or os.path.expanduser('~/.claude/dispatch-catalog.json')
if os.path.exists(p):
    t = os.path.getmtime(p)
    print(datetime.datetime.fromtimestamp(t).isoformat(timespec='seconds'))
else:
    print('absent')
"

Step 2: Run the catalog generator

Invoke claude-wayfinder catalog build with the consumer's source directories. The default layout follows Claude Code's standard ~/.claude/ tree; adjust the flags if your project uses non-standard paths.

claude-wayfinder catalog build \
  --skills-dir ~/.claude/skills \
  --agents-dir ~/.claude/agents \
  --plugin-overrides-dir ~/.claude/triggers \
  --plugins-dir ~/.claude/plugins \
  --builtin-agents-dir ~/.claude/triggers/builtin \
  --out "${DISPATCH_CATALOG_PATH:-$HOME/.claude/dispatch-catalog.json}" \
  --log ~/.claude/dispatch-catalog-build.log

Capture both stdout and stderr. Record the exit code.

• Exit 0 — clean generation.
• Exit 1 — fatal error; the catalog may not have been written.
• Exit 2 — degraded catalog; a partial file was written but one or more entries were excluded due to validation issues.