---
name: heal-skills
description: Heal gemma skills by analyzing session errors and user corrections, then creating a PR with fixes to the agentic toolkit repo. Use after a session where gemma skills had issues, produced errors, or required manual workarounds.
disable-model-invocation: true
argument-hint: "[optional: specific skill or issue to focus on]"
---

# Heal Gemma Skills

Analyze the current conversation for errors and corrections related to gemma skills, then create a PR in the agentic toolkit repo with targeted fixes.

## Scope

Only heal **gemma-*** skills from the `gemma-agentic-toolkit` repo. Do NOT touch third-party skills (superpowers, dbt, plugin-dev, feature-dev, etc.).

## Process

### Step 1 — Identify affected skills

Scan the conversation history for:

- **Skill invocations**: Messages like "Using gemma-*:" or skill content that was loaded
- **Errors during skill execution**: Failed commands, wrong paths, incorrect parameters, missing context
- **User corrections**: "No, instead do...", "That's wrong, it should be...", "Don't do X, do Y", manual workarounds the user performed after a skill gave bad guidance
- **Outdated information**: APIs that changed, tools that moved, configurations that no longer apply

Build a list of affected skills with this structure:

```
AFFECTED_SKILLS:
- plugin: gemma-<name>
  skill: <skill-name>
  issues:
    - what: <what went wrong>
      correction: <what the user did instead / what the fix should be>
      evidence: <quote from conversation>
```

If `$ARGUMENTS` specifies a skill or issue, focus on that. Otherwise, scan the full conversation.

If no gemma skills were used or no corrections were found, tell the user and stop.

### Step 2 — Read current skill files

For each affected skill, read the source files from the toolkit repo.

Resolve `TOOLKIT_REPO` in this order:
1. If Claude is currently inside a `gemma-agentic-toolkit` checkout, use `git rev-parse --show-toplevel`.
2. Otherwise, ask the user: *"What is the path to your local gemma-agentic-toolkit checkout?"* and store the answer as `TOOLKIT_REPO`.

Read:
- `$TOOLKIT_REPO/plugins/<plugin>/skills/<skill>/SKILL.md`
- Any files in `references/`, `scripts/`, or `assets/` that are relevant to the issue

Locate the exact sections that need fixing. Quote the current (incorrect) text.

### Step 3 — Draft changes

For each issue, prepare a concrete fix:

```
### Fix: <plugin>/<skill> — <short description>

**File:** plugins/<plugin>/skills/<skill>/SKILL.md (line ~N)

**Current (incorrect):**
> [exact text from file]

**Proposed fix:**
> [corrected text]

**Why:** [what went wrong and how the fix prevents it]
```

Group changes by plugin for the commit message.

### Step 4 — Present and get approval

Present ALL proposed changes to the user in the format above, then ask:

```
Should I apply these changes?

1. Yes — create branch, apply fixes, and open a PR
2. Apply but let me review before the PR
3. Revise — I'll give feedback on the changes
4. Cancel
```

**Wait for the user to respond. Do not proceed without approval.**

### Step 5 — Apply and create PR

Only after approval (option 1 or 2):

1. Navigate to the toolkit repo:
   ```bash
   cd $TOOLKIT_REPO
   ```

2. Create a branch from `main`:
   ```bash
   git checkout main && git pull
   git checkout -b fix/heal-skills-<date>
   ```
   Use today's date in YYYY-MM-DD format.

3. Apply each fix using the Edit tool. Read back modified sections to verify.

4. Commit with conventional commit format. Group by plugin:
   ```
   fix(<plugin>): <description of what was healed>
   ```
   If multiple plugins are affected, make one commit per plugin.

5. Push and create a PR:
   ```bash
   git push -u origin fix/heal-skills-<date>
   ```
   Create the PR with `gh pr create` using this structure:
   - **Title:** `fix: heal skills from session feedback`
   - **Body:**
     ```
     ## Skills healed

     <For each affected skill:>
     ### `<plugin>/<skill>`
     - **Issue:** <what was wrong>
     - **Fix:** <what was changed>
     - **Evidence:** <brief quote from session>

     ## How these were discovered
     These fixes come from errors and corrections observed during a live session.
     Captured by the `heal-skills` skill.
     ```

6. If option 2 was chosen, stop after committing and let the user review before pushing.

7. Return the PR URL to the user.

## Important notes

- Never fabricate issues. Only heal problems that actually occurred in the conversation with clear evidence.
- Keep fixes minimal and targeted. Don't refactor or "improve" surrounding content.
- If a correction is ambiguous or you're unsure about the right fix, flag it in the proposal and ask.
- The toolkit repo may be on a different branch. Always start from `main`.