Evolve an Existing Skill

Improve, extend, or create an advanced variant of a skill that was originally authored with

create-skill

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:

description

tags

version

# 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

Step 2: Gather Evolution Requirements

Identify and categorize what triggered the evolution:

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:

<skill>-advanced

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

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

npm run translation:status

On failure: If

sed

source_commit

npm run translate:scaffold

Step 5: Update Version and Metadata

Bump the

version

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

"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

find skills -name SKILL.md | wc -l

On failure: If the registry count is wrong, run

find skills -name SKILL.md | wc -l

readlink -f

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

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: With 1,288 translation files in the repo, every skill evolution triggers 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's frontmatter, or flag them for re-translation in the commit message. Skipping this 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