learn

What this skill does

# Learn

This skill updates fx-cc marketplace plugins based on learnings from the current conversation. It modifies skill definitions to prevent future mistakes or improve behavior.

## Prerequisites

Before making any changes, verify the fx-cc marketplace is accessible:

```bash
cd ~/.claude/plugins/marketplaces/fx-cc && git remote -v && git status
```

Verify the remote is accessible and the working directory is clean. If not accessible, inform the user and abort.

### Read CLAUDE.md and respect it

**CRITICAL:** Read `CLAUDE.md` at the root of the marketplace repo (`~/.claude/plugins/marketplaces/fx-cc/CLAUDE.md`) and follow every instruction it contains, especially the **Required First-Time Setup** section. CLAUDE.md is authoritative — its rules apply to every operation this skill performs in the repo.

### Wire up the pre-commit hook (idempotent)

Before any modification, ensure the version-bump pre-commit hook is active in this clone of the marketplace. Git does not let a repo configure its own hooks path, so each clone must opt in once:

```bash
cd ~/.claude/plugins/marketplaces/fx-cc

# Check whether hooks are wired up; if not, wire them.
if [ "$(git config --get core.hooksPath || true)" != ".githooks" ]; then
  git config core.hooksPath .githooks
  echo "✓ Wired core.hooksPath → .githooks"
else
  echo "✓ Hooks already wired"
fi
```

Run this at the very start of any learn invocation, not only when committing. It is idempotent and safe.

**Never bypass the hook** with `--no-verify`. If the hook rejects a future commit, read its message and bump the indicated `plugin.json` / `marketplace.json` versions per the rules in CLAUDE.md.

## Workflow

### Step 1: Analyze the Learning Request

Examine the current conversation to understand:

1. **What went wrong** - Identify the specific behavior that needs correction
2. **Root cause** - Determine which skill caused the issue
3. **Desired behavior** - Understand what should happen instead

Common scenarios:

- **Skill not loaded when it should have been** → Update skill description to be clearer about trigger conditions
- **Skill produced incorrect behavior** → Add explicit prohibition to skill instructions
- **Skill missed a step** → Add the step to the skill's workflow
- **Instruction was ambiguous** → Clarify the wording

### Step 2: Locate Relevant Files

Search the fx-cc marketplace for relevant files:

```bash
# Find all plugin definitions
find ~/.claude/plugins/marketplaces/fx-cc/plugins -name "*.md" -type f

# Search for specific content
grep -r "keyword" ~/.claude/plugins/marketplaces/fx-cc/plugins/
```

Key locations:
- **Skills**: `plugins/<plugin>/skills/<skill>/SKILL.md`

### Step 3: Make Targeted Modifications

Edit the relevant files to address the learning. Follow these principles:

1. **Be specific** - Add concrete instructions, not vague guidance
2. **Use imperative form** - Write "Do X" or "Never do Y", not "You should..."
3. **Add context** - Explain why the rule exists if non-obvious
4. **Preserve structure** - Maintain existing formatting and organization

For prohibitions, use clear language:
```markdown
**CRITICAL:** Never do X because Y.
```

For required actions:
```markdown
**IMPORTANT:** Always do X before Y.
```

### Step 4: Sync to Plugin Cache

**CRITICAL:** Claude Code caches plugins separately from the marketplace source. After modifying files in the marketplace, sync changes to the cache so they take effect immediately.

Cache mapping:
- **Source**: `~/.claude/plugins/marketplaces/fx-cc/plugins/<plugin>/`
- **Cache**: `~/.claude/plugins/cache/fx-cc/<plugin>/<version>/`

To sync a modified plugin:

```bash
# Get the plugin version from its manifest
PLUGIN=fx-dev  # or fx-meta, fx-research, etc.
VERSION=$(cat ~/.claude/plugins/marketplaces/fx-cc/plugins/$PLUGIN/.claude-plugin/plugin.json | grep '"version"' | sed 's/.*: *"\([^"]*\)".*/\1/')

# Sync marketplace source to cache
rsync -av --delete \
  ~/.claude/plugins/marketplaces/fx-cc/plugins/$PLUGIN/ \
  ~/.claude/plugins/cache/fx-cc/$PLUGIN/$VERSION/
```

Sync every plugin that was modified. This ensures Claude loads the updated definitions immediately without requiring a restart.

### Step 5: Verify Changes

After editing and syncing, show the diff to the user:

```bash
cd ~/.claude/plugins/marketplaces/fx-cc && git diff
```

### Step 6: Leave for Manual Review

**CRITICAL:** Do NOT commit the changes. Inform the user:

> Changes have been made to the following files:
> - `path/to/file1.md`
> - `path/to/file2.md`
>
> Review the changes with `git diff` in `~/.claude/plugins/marketplaces/fx-cc`.
> Commit manually when satisfied.

## Examples

### Example 1: Skill Skipped a Step

User says: "use /learn to update our sdlc skills - they should update PROJECT.md when creating PRs"

1. Locate `plugins/fx-dev/skills/pr-preparer/SKILL.md`
2. Add instruction to check PROJECT.md and update completed tasks
3. Sync fx-dev plugin to cache
4. Show diff, leave uncommitted

### Example 2: Skill Not Triggered

User says: "the github skill didn't load when I ran gh commands"

1. Locate `plugins/fx-dev/skills/github/SKILL.md`
2. Update description to include more trigger phrases (e.g., "gh CLI", "GitHub API")
3. Sync fx-dev plugin to cache
4. Show diff, leave uncommitted

### Example 3: Explicit Prohibition

User says: "/learn to never leave comments on PRs"

1. Locate relevant skills (pr-preparer, pr-reviewer, etc.)
2. Add explicit prohibition with rationale
3. Sync all modified plugins to cache
4. Show diff, leave uncommitted