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.

If the generator exits non-zero, surface the error visibly:

Catalog generation FAILED (exit {N})

{captured stderr}

Check ~/.claude/dispatch-catalog-build.log for per-entry details.

Step 3: Record the catalog mtime after regeneration

Read the mtime again using the same command as Step 1.

Step 4: Parse the new catalog

Read the catalog file. The top-level structure is:

{ "entries": [ { "kind": "skill" | "agent", ... }, ... ] }

Count entries by kind:

• skills — entries where kind == "skill"
• agents — entries where kind == "agent"

Step 5: Check the generation log for warnings

Read ~/.claude/dispatch-catalog-build.log and extract any lines containing warning or fatal (case-insensitive). Show only the lines from the most recent run (lines after the last generator-invocation timestamp that precedes the run).

If there are no warning/fatal lines, report "No warnings or fatal issues."

Step 6: Report

Print a structured summary:

Catalog regenerated successfully.   ← or "DEGRADED (exit 2)" / "FAILED (exit 1)"

  Skills:  <N>
  Agents:  <M>
  Total:   <N+M>

  Catalog mtime before: <ISO timestamp or "absent">
  Catalog mtime after:  <ISO timestamp>

  Exclusion warnings (from dispatch-catalog-build.log):
  <warning/fatal lines, or "None">

If exit code was 2, prepend the summary with a visible banner:

WARNING: Catalog is degraded — some entries were excluded due to validation errors. Review the warnings above and fix the affected triggers.yml or agent frontmatter files.