name: evolve-skill locale: caveman source_locale: en source_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-24" description: > Evolve an existing skill by refining its content in-place or creating an advanced variant. Covers assessing the current skill, gathering evolution requirements, choosing scope (refinement vs. variant), applying changes, updating version metadata, and synchronizing the registry and cross-references. Use when a skill's procedure steps are outdated, user feedback reveals gaps, a skill needs a complexity upgrade, an advanced variant is needed alongside the original, or related skills are added and cross-references are stale. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.2" domain: general complexity: intermediate language: multi tags: meta, skill, agentskills, maintenance, evolution, versioning

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:

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

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:

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

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

# Check for existing translations
ls i18n/*/skills/<skill-name>/SKILL.md 2>/dev/null

If translations exist

1. Get current source commit hash:

SOURCE_COMMIT=$(git rev-parse HEAD)

1. Update source_commit in each translated file frontmatter:

for locale_file in i18n/*/skills/<skill-name>/SKILL.md; do
  sed -i "s/^source_commit: .*/source_commit: $SOURCE_COMMIT/" "$locale_file"
done

1. Flag files for re-translation by adding affected locales in commit msg:

evolve(<skill-name>): <description of changes>

Translations flagged for re-sync: de, zh-CN, ja, es
Changed sections: <list sections that changed>

1. Regen translation status files:

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 by semver:

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:

# Check if any skill references the evolved skill
grep -r "<skill-name>" skills/*/SKILL.md

For Variants

Add new skill to skills/_registry.yml:

- 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:

# 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

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