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

Author: yusufkaraaslanCreated Mar 29, 2026Updated Mar 29, 2026
Labelsenhancement

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:

json
{
  "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

bash
# 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

Source: yusufkaraaslan/Skill_Seekers