[FEATURE] Skill Mutations — persistent incremental edits that survive regeneration

[yusufkaraaslan]

🚀 Feature Description

Add a mutation system that allows small, tracked edits to generated skills that persist across regenerations. When a skill is regenerated, mutations are re-applied if still relevant — like a smart git rebase for skills.

Problem

Users tweak generated skills (add notes, fix examples, adjust wording), then regenerate and lose their edits. There's no way to persist manual improvements.

Solution: Skill Mutations

Mutation Format (JSON records)

Each mutation is stored as a structured JSON record:

{
  "id": "mut_abc123",
  "target_skill": "react/SKILL.md",
  "section_match": "## Hooks",
  "action": "append",
  "content": "**Note:** Always use `useCallback` for event handlers passed to child components to avoid unnecessary re-renders.",
  "reason": "Team convention established in PR #245",
  "created_at": "2026-03-29T10:00:00Z",
  "applied_count": 3,
  "last_applied": "2026-03-28T15:30:00Z"
}

Mutation Actions

• append — Add content after a matched section
• replace — Replace matched content with new content
• insert — Insert content before a matched section
• delete — Remove matched content

Storage

• Mutations stored in .skill-seekers/mutations/ directory (or user-configured location)
• One JSON file per skill (e.g., react.mutations.json)
• Mutations are version-controlled alongside the project

MCP Tools

Register mutations via MCP tools for seamless AI assistant integration:

• apply_skill_mutation(skill_path, section, action, content, reason) — Record and apply a mutation
• list_skill_mutations(skill_path?) — List all mutations (optionally filtered by skill)
• remove_skill_mutation(mutation_id) — Remove a mutation
• preview_mutations(skill_path) — Show what mutations would be applied on next regeneration

Re-application on Regeneration

When a skill is regenerated:

1. Iterate through all registered mutations for that skill
2. For each mutation, check if section_match still exists in the regenerated skill
3. If match found → apply the mutation, increment applied_count
4. If no match → warn the user: "Mutation mut_abc123 could not be applied — section '## Hooks' no longer exists"
5. Stale mutations (failed to apply N times) can be auto-archived

Conflict Resolution

• If a mutation's section_match matches but content has changed significantly, warn but still apply
• If replace action target text doesn't exist, skip with warning
• User can review and resolve via skill-seekers mutations review

CLI Commands

# Add a mutation
skill-seekers mutate ./skills/react/SKILL.md \
  --section "## Hooks" \
  --action append \
  --content "Always prefer useCallback for handlers." \
  --reason "Team convention"

# List mutations
skill-seekers mutations list
skill-seekers mutations list --skill react

# Preview what would be applied
skill-seekers mutations preview ./skills/react/SKILL.md

# Remove a mutation
skill-seekers mutations remove mut_abc123

# Review stale mutations
skill-seekers mutations review --stale

Implementation Notes

• Mutation storage: JSON files in configurable directory
• Section matching: heading-based regex (e.g., ## Section Name) or line-range
• MCP tools in src/skill_seekers/mcp/tools/mutation_tools.py
• Hook into the regeneration pipeline (after build/enhance, before final write)
• Consider fuzzy section matching for minor heading changes