[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:
{
"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 mutationlist_skill_mutations(skill_path?)— List all mutations (optionally filtered by skill)remove_skill_mutation(mutation_id)— Remove a mutationpreview_mutations(skill_path)— Show what mutations would be applied on next regeneration
Re-application on Regeneration
When a skill is regenerated:
- Iterate through all registered mutations for that skill
- For each mutation, check if
section_matchstill exists in the regenerated skill - If match found → apply the mutation, increment
applied_count - If no match → warn the user: "Mutation
mut_abc123could not be applied — section '## Hooks' no longer exists" - Stale mutations (failed to apply N times) can be auto-archived
Conflict Resolution
- If a mutation's
section_matchmatches but content has changed significantly, warn but still apply - If
replaceaction 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 --staleImplementation 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