Get the FREE Ultimate OpenClaw Setup Guide →

index-rebuild

Scanned
npx machina-cli add skill MacroMan5/macromanatlas/index-rebuild --openclaw
Files (1)
SKILL.md
2.9 KB

/index-rebuild

Rebuild the project index, optionally targeting a specific module with custom instructions.

Usage

/index-rebuild                              Full rebuild (all modules + index)
/index-rebuild --module MacroMan-Tracking   Rebuild only Tracking README + update index
/index-rebuild --module MacroMan-Tracking --m "Focus on TrackState machine transitions"

Step 1: Parse arguments

Parse $ARGUMENTS for:

  • --module <name> — target a specific module (optional)
  • --m "<instructions>" or --m <instructions> — custom emphasis instructions (optional)

If no arguments: full rebuild of all modules.

Step 2: Announce

If --module specified: Say: "Rebuilding index for module: <name>" If full rebuild: Say: "Rebuilding complete project index..."

Step 3a: Targeted rebuild (--module specified)

  1. Verify the module directory exists. If not, list available modules and ask user to pick one.
  2. Scan the module:
    • List files with git ls-files <module>/ (or Glob fallback)
    • Read interface/header/export files for public API
    • Extract dependencies from build files (CMakeLists.txt, package.json, Cargo.toml, etc.)
    • Generate tags from file names, class names, function names
  3. Read existing <Module>/README.md
  4. Preserve the <!-- CUSTOM --> section content
  5. Regenerate the <!-- AUTO-GENERATED --> section using the same template as /index-init Step 3
  6. If --m instructions provided:
    • Use them to guide emphasis in the README generation (what classes to detail, what patterns to document)
    • Save the instructions in the CUSTOM section as: **Index instructions**: <instructions>
  7. Write the updated README
  8. Update .claude/index.md:
    • Update the module's row in the Modules table
    • Update the Tag Index for this module's tags only
  9. Regenerate .claude/index.summary.md from .claude/index.md (keep under 4KB)

Step 3b: Full rebuild (no --module flag)

Perform the same steps as /index-init Steps 2-4, but:

  • PRESERVE all <!-- CUSTOM --> sections in existing READMEs
  • PRESERVE the <!-- CUSTOM --> section in .claude/index.md
  • Do NOT re-add the CLAUDE.md section if it already exists (look for "Code Navigation" or "Code Index")
  • Do NOT modify hooks (they're managed by the plugin)
  • Regenerate the "How to Use" section in .claude/index.md with the navigation strategy (tags → README → targeted grep)

Step 4: Report

Summarize:

  • Modules rebuilt (count or specific name)
  • Files indexed
  • Tags updated
  • Custom instructions applied (if --m was used)

If targeted rebuild, suggest: "Run /index-status to verify the rebuild."

Source

git clone https://github.com/MacroMan5/macromanatlas/blob/main/skills/index-rebuild/SKILL.mdView on GitHub

Overview

index-rebuild regenerates the project index, either for all modules or a specific module via the --module flag. It analyzes module files, public API surfaces, and dependencies, then regenerates the AUTO-GENERATED README content while preserving CUSTOM sections. If you supply --m, the instructions are embedded in the CUSTOM area to guide future indexing.

How This Skill Works

The tool parses arguments and performs either a full rebuild or a targeted rebuild. For targeted rebuilds, it validates the module directory, scans files with git ls-files or a Glob fallback, reads the module README, preserves the CUSTOM block, regenerates the AUTO-GENERATED section using the established template, and updates the CLAUDE index and tag index accordingly. If --m is provided, those instructions are saved in the CUSTOM section as Index instructions.

When to Use It

  • You added or updated a module and need its index refreshed.
  • You want to update a single module quickly without rebuilding the entire project.
  • You want to apply or test custom emphasis instructions with --m.
  • You must preserve existing CUSTOM sections while regenerating READMEs.
  • You need to refresh .claude/index.md and tag indexes after changes.

Quick Start

  1. Step 1: Decide whether to rebuild a single module with --module or perform a full project rebuild.
  2. Step 2: Run the command, e.g. /index-rebuild --module MacroMan-Tracking --m "Focus on TrackState transitions".
  3. Step 3: Verify results with /index-status and review updated READMEs and the CLAUDE index.

Best Practices

  • Prefer targeted rebuilds with --module for small, fast updates when possible.
  • Always preserve existing <!-- CUSTOM --> content in READMEs during regeneration.
  • Use --m to steer emphasis (APIs, patterns) and store the guidance in CUSTOM.
  • Verify the target module directory exists before running the rebuild.
  • After rebuilding, run /index-status to confirm modules, files, and tags are up to date.

Example Use Cases

  • Rebuild only the MacroMan-Tracking module: /index-rebuild --module MacroMan-Tracking
  • Full project rebuild after adding a new module to the codebase
  • Rebuild with custom emphasis: /index-rebuild --module MacroMan-Tracking --m "Focus on TrackState machine transitions"
  • Preserve CUSTOM sections while updating READMEs for multiple modules in a single pass
  • Fix a stale tag index by triggering a targeted rebuild on the affected module

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗