evolve-skill

# Evolve an Existing Skill Fix, grow, or make advanced variant of skill first made with `create-skill`. This proc covers upkeep side of skill life: check gaps, apply tight fixes, bump versions, keep registry and cross-refs in sync. ## When Use - Skill proc steps stale or thin after tool shifts - User feedback shows missing pitfalls, unclear steps, or weak check - Skill need grow from basic to intermediate (or intermediate to advanced) - Advanced variant needed next to original (e.g., `create-r-package` and `create-r-package-advanced`) - Related skills added or removed and cross-refs are stale ## Inputs - **Required**: Path to existing SKILL.md to evolve - **Required**: Evolve trigger (feedback, tool change, complexity bump, new related skills, spotted pitfalls) - **Optional**: Target complexity if changing (basic, intermediate, advanced) - **Optional**: Make advanced variant vs refine in-place (default: refine in-place) ## Steps ### Step 1: Assess the Current Skill Read existing SKILL.md and check each section vs quality list: | Section | What to Check | Common Issues | |---|---|---| | Frontmatter | All required fields present, `description` < 1024 chars | Missing `tags`, stale `version` | | When to Use | 3-5 concrete trigger conditions | Vague or overlapping triggers | | Inputs | Required vs optional clearly separated | Missing defaults for optional inputs | | Procedure | Each step has code + Expected + On failure | Missing On failure blocks, pseudocode instead of real commands | | Validation | Each item is binary pass/fail | Subjective criteria ("code is clean") | | Common Pitfalls | 3-6 with cause and avoidance | Too generic ("be careful") | | Related Skills | 2-5 valid skill references | Stale references to renamed/removed skills | ```bash # Read the skill cat skills/<skill-name>/SKILL.md # Check frontmatter parses head -20 skills/<skill-name>/SKILL.md # Verify related skills still exist grep -oP '`[\w-]+`' skills/<skill-name>/SKILL.md | sort -u ``` **Got:** List of specific gaps, weak spots, or fix chances. **If fail:** SKILL.md not exist or no frontmatter? This skill not apply — use `create-skill` instead to make from scratch. ### Step 2: Gather Evolution Requirements Spot and sort what fired evolve: | Trigger | Example | Typical Scope | |---|---|---| | User feedback | "Step 3 is unclear" | Refinement | | Tooling change | New API version, deprecated command | Refinement | | Discovered pitfall | Common failure not documented | Refinement | | Complexity upgrade | Skill is too shallow for real use | Refinement or variant | | New related skills | Adjacent skill was added | Refinement (cross-refs) | | Advanced use case | Power users need deeper coverage | Variant | Log specific changes needed before edit. List each change with target section. **Got:** Concrete list of changes (e.g., "Add On failure to Step 4", "Add new Step 6 for edge case X", "Update Related Skills to include `new-skill`"). **If fail:** Changes unclear? Ask user for clarity before go on. Vague evolve goals give vague fixes. ### Step 3: Choose Evolution Scope Use this pick matrix to decide refine in-place or make variant: | Criteria | Refinement (in-place) | Advanced Variant (new skill) | |---|---|---| | Skill ID | Unchanged | New ID: `<skill>-advanced` | | File path | Same SKILL.md | New directory | | Version bump | Minor (major only if breaking) | Starts at 1.0 | | Complexity | May increase | Higher than original | | Registry | No new entry | New entry added | | Symlinks | No change | New symlinks needed | | Original skill | Modified directly | Left intact, gains cross-reference | **Refinement**: Pick when fixing quality, patching gaps, or adding modest new content. Skill keeps its identity. **Variant**: Pick when evolved version would double length, change target audience, or need different inputs. Original stays as-is for simpler use cases. **Got:** Clear pick — refine or variant — with reason. **If fail:** Unsure? Default to refine. Can always pull variant later; harder to merge one back. ### Step 4: Apply Content Changes #### For Refinements Edit existing SKILL.md direct: - Open for editing - Add/revise procedure steps - Strengthen Expected/On failure pairs - Add tables or examples - Update When to Use triggers - Revise Inputs if scope changed Follow these edit rules: - Keep all existing sections — add content, do not remove sections - Keep step numbering sequential after inserts - Every new or modified step must have both Expected and On failure - New pitfalls go at end of Common Pitfalls section - New related skills go at end of Related Skills section #### For Variants ```bash # Create the variant directory mkdir -p skills/<skill-name>-advanced/ # Copy the original as a starting point cp skills/<skill-name>/SKILL.md skills/<skill-name>-advanced/SKILL.md # Edit the variant: # - Change `name` to `<skill-name>-advanced` # - Update `description` to reflect the advanced scope # - Raise `complexity` (e.g., intermediate → advanced) # - Reset `version` to "1.0" # - Add/expand procedure steps for the advanced use case # - Reference the original in Related Skills as a prerequisite ``` **Got:** SKILL.md (refined or new variant) passes check list from Step 1. **If fail:** Step edit breaks doc shape? Use `git diff` to review changes and revert partial edits with `git checkout -- <file>`. ### Step 4.5: Sync Translated Variants > **Required when translations exist.** This step applies to both human authors and AI agents following this procedure. Do not skip — stale `source_commit` values cause `npm run validate:translations` to report false staleness warnings across all locales. Check whether translations exist for evolved skill and update to match new source state: ```bash # Check for existing translations ls i18n/*/skills/<skill-name>/SKILL.md 2>/dev/null ``` #### If translations exist 1. Get current source commit hash: ```bash npm run validate:translations ``` 2. Update `source_commit` in each translated file frontmatter: ```bash npm run check:fence-propagation -- --id <skill-name> node tools/provenance-field.mjs --field fence_basis_commit --set $(git rev-parse --short HEAD) <mirror paths> ``` 3. Flag files for re-translation by adding affected locales in commit msg: ```text evolve(<skill-name>): <description of changes> Translations flagged for re-sync: de, zh-CN, ja, es Changed sections: <list sections that changed> ``` 4. Regen translation status files: ```bash npm run translation:status ``` #### If no translations exist No action needed. Go to Step 5. #### For variants Wait translation of new variants until variant stabilizes (1-2 versions). Translating v1.0 variant that may change much by v1.2 wastes effort. Add translations after variant refined at least once. **Got:** All translated files have `source_commit` updated to current commit. Commit msg notes which locales need re-translation and which sections changed. `npm run translation:status` exits 0. **If fail:** `sed` fails to match frontmatter field? Translated file may have odd format. Open by hand and check it has `source_commit` in its YAML frontmatter. Field missing? File not scaffolded right — re-scaffold with `npm run translate:scaffold`. ### Step 5: Update Version and Metadata Bump `version` field in frontmatter: | Change Type | Version Bump | Example | |---|---|---| | Typo fix, wording clarification | Minor: 1.0 → 1.1 | Fixed unclear sentence in Step 3 | | New step, new pitfall, new table | Minor: 1.0 → 1.1 | Added Step 7 for edge case handling | | Restructured procedure, changed inputs | Major: 1.0 → 2.0 | Reorganized from 5 to 8 steps | Also update: - `complexity` if scope grew (e.g., basic → intermediate) - `tags` if coverage area shifted - `description` if skill scope materially different **Got:** Frontmatter `version` shows size of changes. New variants start at `"1.0"`. **If fail:** Forget to bump version? Next evolve will have no way to tell current state from old. Always bump before commit. ### Step 6: Update Registry and Cross-References #### For Refinements No registry changes needed (path unchanged). Update cross-refs only if Related Skills shifted in other skills: ```bash # Check if any skill references the evolved skill grep -r "<skill-name>" skills/*/SKILL.md ``` #### For Variants Add new skill to `skills/_registry.yml`: ```yaml - id: <skill-name>-advanced path: <skill-name>-advanced/SKILL.md complexity: advanced language: multi description: One-line description of the advanced variant ``` Then: 1. Bump `total_skills` at top of registry 2. Add Related Skills cross-ref in original skill pointing to variant 3. Add Related Skills cross-ref in variant pointing to original 4. Make symlinks for slash command discovery: ```bash # Project-level ln -s ../../skills/<skill-name>-advanced .claude/skills/<skill-name>-advanced # Global ln -s /mnt/d/dev/p/agent-almanac/skills/<skill-name>-advanced ~/.claude/skills/<skill-name>-advanced ``` **Got:** Registry `total_skills` matches `find skills -name SKILL.md | wc -l`. Cross-refs two-way. **If fail:** Registry count wrong? Run `find skills -name SKILL.md | wc -l` to get true count and fix registry. Broken symlinks? Use `readlink -f` to debug. ### Step 7: Validate the Evolved Skill Run full check list: - [ ] SKILL.md exists at expected path - [ ] YAML frontmatter parses with no errors - [ ] `version` was bumped (refinement) or set to "1.0" (variant) - [ ] All sections present: When to Use, Inputs, Procedure, Validation, Common Pitfalls, Related Skills - [ ] Every procedure step has Expected and On failure blocks - [ ] Related Skills ref valid, existing skill names - [ ] Registry entry exists with right path (variants only) - [ ] `total_skills` count matches real skill count on disk - [ ] Symlinks resolve right (variants only) - [ ] `git diff` shows no slip deletes from original content - [ ] For refinements with translations: `source_commit` updated or translations flagged for re-sync ```bash # Verify frontmatter head -20 skills/<skill-name>/SKILL.md # Count skills on disk vs registry find skills -name SKILL.md | wc -l grep total_skills skills/_registry.yml # Check symlinks (for variants) ls -la .claude/skills/<skill-name>-advanced readlink -f .claude/skills/<skill-name>-advanced/SKILL.md # Review all changes git diff ``` **Got:** All check items pass. Evolved skill ready to commit. **If fail:** Fix each failing item one by one. Most common post-evolve issue is stale `total_skills` count — always check it last. ## Validation - [ ] SKILL.md exists and has valid YAML frontmatter - [ ] `version` field shows changes made - [ ] All procedure steps have Expected and On failure blocks - [ ] Related Skills refs valid (no broken cross-refs) - [ ] Registry `total_skills` matches real count on disk - [ ] For variants: new entry in `_registry.yml` with right path - [ ] For variants: symlinks made at `.claude/skills/` and `~/.claude/skills/` - [ ] `git diff` confirms no slip content removal - [ ] For refinements with translations: `source_commit` updated or translations flagged for re-sync ## Pitfalls - **Forget to bump version**: No version bump, no way to track what changed or when. Always update `version` in frontmatter before commit. - **Slip content delete**: Restructure steps, easy to drop On failure block or table row. Always review `git diff` before commit. - **Stale cross-refs**: Make variant, both original and variant need ref each other. One-way refs leave graph broken. - **Registry count drift**: After make variant, `total_skills` count must bump. Forget this cause check fails in other skills that test registry. - **Stale translations after evolve**: With 1,288 translation files in repo, every skill evolve fires staleness in up to 4 locale files. Always check for existing translations with `ls i18n/*/skills/<skill-name>/SKILL.md` and update `source_commit` in each translated file frontmatter, or flag them for re-translation in commit msg. Skip this cause `npm run validate:translations` to report stale warnings. - **Scope creep during refine**: Refine that doubles skill length should probably be variant instead. Adding more than 3 new procedure steps? Rethink scope pick from Step 3. - **Avoid `git mv` on NTFS-mounted paths (WSL)**: On `/mnt/` paths, `git mv` for directories can make broken perms (`d?????????`). Use `mkdir -p` + copy files + `git rm` old path instead. See [environment guide](../../guides/setting-up-your-environment.md) troubleshoot section. ## See Also - `create-skill` — base for making new skills; evolve-skill assumes this was followed first - `commit-changes` — commit evolved skill with clear msg - `configure-git-repository` — version-tracked skill changes - `security-audit-codebase` — review evolved skills for slip-added secrets