---
name: update-skill-index
description: Synchronizes _skill-index.md with the skills that actually exist on disk. Use this whenever skills have been added, removed, renamed, or merged — or just periodically to keep the index clean. Removes index entries that no longer have a corresponding SKILL.md (garbage collection), adds entries for skills that exist on disk but aren't indexed, and refreshes stale trigger phrases. Trigger on: "update the skill index", "sync the skill index", "refresh the skill index", "clean up the skill index", "garbage collect the index", "reconcile the skill index", "the index is out of date".
---

# Update Skill Index

Keeps `_skill-index.md` accurate by reconciling it against what's actually in the `skills/` directory.

## When to run

- After adding, removing, or merging a skill
- Periodically as a maintenance step
- Any time the index might be stale

---

## Steps

### 1. Discover skills on disk

Glob `skills/*/SKILL.md`. For each file found:
- Read the frontmatter to extract `name` and any trigger phrases listed
- Note the folder name (used as the canonical skill identifier)
- Skip `_skill-index.md` and the `skill-creator` directory (it's a tool, not a user-facing skill)

### 2. Read the current index

Read `skills/_skill-index.md`. Parse:
- The Quick Trigger Reference table (header row + one row per skill)
- The Skills section (one subsection per skill with purpose, triggers, file path, dependencies)

### 3. Reconcile

Produce three lists:

**To add:** Skill folders that have a `SKILL.md` but no entry in the index.

**To remove (garbage collect):** Index entries whose listed file path (`skills/<name>/SKILL.md`) doesn't exist on disk. These are orphans — skills that were deleted or merged. Flag them clearly so the user understands what's being removed.

**To update:** Skills present in both, but where the trigger phrases in the index don't match what's in the SKILL.md. Only flag these if there's a meaningful difference — don't nitpick minor wording.

### 4. Present the diff before touching anything

Show a clear summary:

```
Proposed changes to _skill-index.md:

ADD (2):
  + email-draft   — "draft an email", "write an email for me"
  + invoice-gen   — "generate an invoice", "make an invoice"

REMOVE (1):
  - meeting-notes — no SKILL.md found at skills/meeting-notes/SKILL.md

UPDATE (1):
  ~ pro-dev-justification — trigger phrases updated to match SKILL.md

No changes? Index is already up to date.
```

Ask: "Want me to apply these changes?"

### 5. Apply changes

On approval:

**Additions:** For each new skill, write a new entry in the Skills section (name, purpose pulled from the SKILL.md description, trigger phrases, file path, dependencies if any). Add a row to the Quick Trigger Reference table.

**Removals:** Delete the index entry and the corresponding table row. If a skill was merged into another, note that in a comment — don't just silently delete.

**Updates:** Replace stale trigger phrases in both the table and the skill's subsection.

Preserve the existing structure and formatting of the index. Don't reorder sections or change the prose around skills that weren't touched.

### 6. Commit and push

After writing the updated index:

```bash
cd skills/ && git add _skill-index.md && git commit -m "update skill index: [brief summary of changes]" && git push
```

Keep the commit message specific: e.g., "update skill index: add email-draft, remove meeting-notes".

---

## What not to change

- The index footer ("Started with the Robot Assistant Field Guide Starter Kit...")
- Section headers or prose that aren't related to the reconciled skills
- Skills that are in both the index and on disk and whose triggers haven't changed

The goal is a minimal, accurate update — not a rewrite.
