Evolve an Existing Skill

Improve, extend, or create an advanced variant of a skill that was originally authored with create-skill. This procedure covers the maintenance side of the skill lifecycle: assessing gaps, applying targeted improvements, bumping versions, and keeping the registry and cross-references in sync.

When to Use

• A skill's procedure steps are outdated or incomplete after tooling changes
• User feedback reveals missing pitfalls, unclear steps, or weak validation
• A skill needs to grow from basic to intermediate (or intermediate to advanced)
• An advanced variant is needed alongside the original (e.g., create-r-package and create-r-package-advanced)
• Related skills were added or removed and cross-references are stale

Inputs

• Required: Path to the existing SKILL.md to evolve
• Required: Evolution trigger (feedback, tooling change, complexity upgrade, new related skills, discovered pitfalls)
• Optional: Target complexity level if changing (basic, intermediate, advanced)
• Optional: Whether to create an advanced variant instead of refining in-place (default: refine in-place)

Procedure

Step 1: Assess the Current Skill

Read the existing SKILL.md and evaluate each section against the quality checklist:

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

# 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

Expected: A list of specific gaps, weaknesses, or improvement opportunities.

On failure: If the SKILL.md doesn't exist or has no frontmatter, this skill doesn't apply — use create-skill instead to author it from scratch.

Step 2: Gather Evolution Requirements

Identify and categorize what triggered the evolution:

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

Document the specific changes needed before editing. List each change with its target section.

Expected: A 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").

On failure: If the changes are unclear, consult the user for clarification before proceeding. Vague evolution goals produce vague improvements.

Step 3: Choose Evolution Scope

Use this decision matrix to determine whether to refine in-place or create a 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: Choose when improving quality, fixing gaps, or adding modest new content. The skill keeps its identity.

Variant: Choose when the evolved version would double the length, change the target audience, or require substantially different inputs. The original stays as-is for simpler use cases.

Expected: A clear decision — refinement or variant — with rationale.

On failure: If unsure, default to refinement. You can always extract a variant later; it's harder to merge one back.

Step 4: Apply Content Changes

For Refinements

Edit the existing SKILL.md directly:

• 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 editing rules:

• Preserve all existing sections — add content, don't remove sections
• Keep step numbering sequential after insertions
• Every new or modified step must have both Expected and On failure
• New pitfalls go at the end of the Common Pitfalls section — but if appending would push the count above 6, do not append: evict the pitfall with the lowest rediscovery cost instead, the one a competent agent would most likely avoid unaided. An eviction must name the Procedure step or section that already teaches the evicted content — if none does, first fold the pitfall's counterintuitive fact into the step that should carry it, then evict. Pitfalls are ranked by what they save, not by age. Skills already over the cap are grandfathered: evict when a later evolution adds a pitfall, not as a bulk retro-edit
• New related skills go at the end of the 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

Expected: The SKILL.md (refined or new variant) passes the assessment checklist from Step 1.

On failure: If a step edit breaks the document structure, 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 the evolved skill and update them to reflect the new source state:

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

If translations exist

1. Get the current source commit hash:

SOURCE_COMMIT=$(git rev-parse HEAD)

2. Update source_commit in each translated file's frontmatter:

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

3. Flag files for re-translation by including affected locales in the commit message:

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

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

4. Regenerate translation status files:

npm run translation:status

If no translations exist

No action needed. Proceed to Step 5.

For variants

Defer translation of new variants until the variant stabilizes (1-2 versions). Translating a v1.0 variant that may change substantially by v1.2 wastes effort. Add translations after the variant has been refined at least once.

Expected: All translated files have source_commit updated to the current commit. The commit message notes which locales need re-translation and which sections changed. npm run translation:status exits 0.

On failure: If sed fails to match the frontmatter field, the translated file may have non-standard formatting. Open it manually and verify it has source_commit in its YAML frontmatter. If the field is missing, the file was not scaffolded correctly — re-scaffold with npm run translate:scaffold.

Step 5: Update Version and Metadata

Skill versions are two-part, MAJOR.MINOR — there is no patch component, so every change lands in one of exactly two buckets:

Change Type	Version Bump	Example
Typo fix, wording clarification	Minor: 1.0 → 1.1	Fixed unclear sentence in Step 3
Additive: new step, new pitfall, new table	Minor: 1.0 → 1.1	Added Step 7 for edge case handling
Breaking: restructured procedure, changed inputs	Major: 1.0 → 2.0	Reorganized from 5 to 8 steps

The criterion is whether existing callers break, not how much text changed. Bump MINOR when a caller who followed the previous version still gets a correct result — clarifications and additions are minor no matter how many lines they touch. Bump MAJOR (and reset MINOR to 0) only when the change invalidates how the skill was being used: steps renumbered or removed, required Inputs added or renamed, or an Expected outcome redefined so that following the old version now produces the wrong result.

Existing corpus versions are grandfathered — do not retro-bump a skill to correct a historical mislabel.

Also update:

• complexity if the scope expanded (e.g., basic → intermediate)
• tags if the coverage area changed
• description if the skill's scope is materially different

Expected: Frontmatter version reflects the magnitude of changes. New variants start at "1.0".

On failure: If you forget to bump the version, the next evolution will have no way to distinguish the current state from the previous one. Always bump before committing.

Step 6: Update Registry and Cross-References

For Refinements

No registry changes are needed (path unchanged). Update cross-references only if Related Skills changed in other skills:

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

For Variants

Add the 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. Increment total_skills at the top of the registry
2. Add Related Skills cross-reference in the original skill pointing to the variant
3. Add Related Skills cross-reference in the variant pointing to the original
4. Create 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

Expected: Registry total_skills matches find skills -name SKILL.md | wc -l. Cross-references are bidirectional.

On failure: If the registry count is wrong, run find skills -name SKILL.md | wc -l to get the true count and correct the registry. For broken symlinks, use readlink -f to debug resolution.

Step 7: Validate the Evolved Skill

Run the full validation checklist:

• SKILL.md exists at the expected path
• YAML frontmatter parses without 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 reference valid, existing skill names
• Registry entry exists with correct path (variants only)
• total_skills count matches actual skill count on disk
• Symlinks resolve correctly (variants only)
• git diff shows no accidental deletions from the 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

Expected: All checklist items pass. The evolved skill is ready to commit.

On failure: Address each failing item individually. The most common post-evolution issue is a stale total_skills count — always verify it last.

Validation

• SKILL.md exists and has valid YAML frontmatter
• version field reflects the changes made
• All procedure steps have Expected and On failure blocks
• Related Skills references are valid (no broken cross-references)
• Registry total_skills matches actual count on disk
• For variants: new entry in _registry.yml with correct path
• For variants: symlinks created at .claude/skills/ and ~/.claude/skills/
• git diff confirms no accidental content removal
• For refinements with translations: source_commit updated or translations flagged for re-sync

Common Pitfalls

• Forgetting to bump version: Without version bumps, there's no way to track what changed or when. Always update version in frontmatter before committing.
• Accidental content deletion: When restructuring steps, it's easy to drop an On failure block or a table row. Always review git diff before committing.
• Stale cross-references: When creating a variant, both the original and the variant need to reference each other. One-directional references leave the graph incomplete.
• Registry count drift: After creating a variant, the total_skills count must be incremented. Forgetting this causes validation failures in other skills that check the registry.
• Stale translations after evolution: The repo mirrors content across 10 locale trees (i18n/<locale>/skills/<skill-name>/SKILL.md), so a single skill evolution can stale up to 10 locale copies. Always check for existing translations with ls i18n/*/skills/<skill-name>/SKILL.md and either update source_commit in each translated file's frontmatter after re-translating, or flag them for re-translation in the commit message. Bumping source_commit without re-translating marks stale content as fresh and suppresses the freshness check — never do that. Skipping the check entirely causes npm run validate:translations to report stale warnings.
• Scope creep during refinement: A refinement that doubles the skill's length should probably be a variant instead. If you're adding more than 3 new procedure steps, reconsider the scope decision from Step 3.
• Avoid git mv on NTFS-mounted paths (WSL): On /mnt/ paths, git mv for directories can create broken permissions (d?????????). Use mkdir -p + copy files + git rm the old path instead. See the environment guide troubleshooting section.

Related Skills

• create-skill — foundation for authoring new skills; evolve-skill assumes this was followed originally
• commit-changes — commit the evolved skill with a descriptive message
• configure-git-repository — version-controlled skill changes
• security-audit-codebase — review evolved skills for accidentally included secrets