---

name: evolve-skill locale: wenyan 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

演既有技

改、擴、或造以 create-skill 所造技之進變體。此術司技生之維：評缺、施針對改、升版、保 registry 與互引同步。

用時

• 工具易後技步陳或缺
• 用戶回示缺陷、不明步、弱驗
• 技須自 basic 升 intermediate（或中升 advanced）
• 原外需進變體（如 create-r-package 與 create-r-package-advanced）
• 加去相關技而互引陳

入

• 必要：欲演 SKILL.md 之路
• 必要：演之因（回、工具易、繁升、新相關技、察陷）
• 可選：易時之目標繁級（basic、intermediate、advanced）
• 可選：是否造變體而非就地改（默：就地改）

法

第一步：評當技

讀 SKILL.md 並按質清單評各節：

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

得： 具體缺、弱、或改機之列。

敗則： 若 SKILL.md 不存或無 frontmatter，此技不適——當用 create-skill 從頭造。

第二步：集演求

識並類演之因：

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

編前記具體改。各改附目節。

得： 具體改之列（如「加 On failure 於第四步」「加新第六步於邊例 X」「更 Related Skills 含 new-skill」）。

敗則： 若改不明，進前請用戶澄。模糊演目生模糊改。

第三步：擇演範

用此決表定就地改或造變體：

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

改：提質、修缺、或加少容時擇。技保其身。

變體：演後版倍長、易眾、或需顯異之入時擇。原留供簡用。

得： 明決——改或變——附理。

敗則： 不確時默改。後可析變體；合回更難。

第四步：施容改

於改

直編 SKILL.md：

• 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

循此編則：

• 保諸有節——加容，勿去節
• 插後步號保序
• 新或改步皆須有 Expected 與 On failure
• 新陷置 Common Pitfalls 節末
• 新相關技置 Related Skills 節末

於變體

# 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

得： SKILL.md（改或新變體）過第一步之評清單。

敗則： 若編破文構，用 git diff 審改並以 git checkout -- <file> 回退部分編。

第四·五步：同譯變體

譯存時必需。 此步適人與 AI 二者。勿略——陳 source_commit 致 npm run validate:translations 於諸 locale 生誤陳警。

察演技是否有譯並更譯以映新源態：

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

譯存之時

1. 取當源提交哈：

npm run validate:translations

2. 於各譯文 frontmatter 更 source_commit：

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. 於提交訊中標所涉 locale 以供重譯：

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

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

4. 重生譯狀文：

npm run translation:status

無譯之時

無須行。進第五步。

於變體

新變體之譯延至變體穩（1-2 版）。譯 v1.0 變體而 v1.2 或大變廢工。變體改至少一次後方加譯。

得： 諸譯文 source_commit 更至當提交。提交訊記何 locale 須重譯、何節易。npm run translation:status 出 0。

敗則： 若 sed 不配 frontmatter 域，譯文或有非標格式。手開驗其 YAML frontmatter 含 source_commit。若缺，文未正造——以 npm run translate:scaffold 再造。

第五步：更版與元數

於 frontmatter 升 version：

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

亦更：

• complexity 若範擴（如 basic → intermediate）
• tags 若覆域易
• description 若技範實異

得： Frontmatter version 映改之大。新變體始於 "1.0"。

敗則： 若忘升版，下演無法辨當態與前。提交前必升。

第六步：更 Registry 與互引

於改

無須更 registry（路不易）。唯他技之 Related Skills 改時更互引：

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

於變體

於 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

然後：

1. 增 registry 頂之 total_skills
2. 於原技 Related Skills 加指變體之引
3. 於變體 Related Skills 加指原之引
4. 為斜線命發現造 symlink：

# 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

得： Registry total_skills 合 find skills -name SKILL.md | wc -l。互引雙向。

敗則： 若 registry 計誤，運 find skills -name SKILL.md | wc -l 取實數正 registry。Symlink 破則以 readlink -f 查。

第七步：驗演技

行全驗清單：

• SKILL.md 存於預路
• YAML frontmatter 解無誤
• version 已升（改）或設「1.0」（變）
• 諸節存：When to Use、Inputs、Procedure、Validation、Common Pitfalls、Related Skills
• 諸步皆有 Expected 與 On failure
• Related Skills 引有效存
• Registry 條存附正路（唯變體）
• total_skills 合盤實數
• Symlink 正解（唯變體）
• git diff 示原容無誤刪
• 有譯之改：source_commit 已更或譯已標供重譯

# 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

得： 清單皆過。演技可提交。

敗則： 各敗項各處。最常演後問為陳 total_skills——最後必驗。

驗

• SKILL.md 存且 YAML frontmatter 有效
• version 映所改
• 諸步皆有 Expected 與 On failure
• Related Skills 引有效（無破互引）
• Registry total_skills 合盤實數
• 變體時：_registry.yml 新條附正路
• 變體時：.claude/skills/ 與 ~/.claude/skills/ 造 symlink
• git diff 確無誤刪
• 有譯之改：source_commit 已更或譯已標供重譯

陷

• 忘升版：無升則不能追何變何時。提交前必更 frontmatter version
• 誤刪容：重構步時易落 On failure 或表行。提交前必審 git diff
• 陳互引：造變體時原與變須互引。單向引令圖不全
• Registry 計漂：造變體後必增 total_skills。忘則他技察 registry 時驗敗
• 演後陳譯：庫中 1,288 譯文，每技演引至 4 locale 文陳。必以 ls i18n/*/skills/<skill-name>/SKILL.md 察並更各譯文 source_commit，或於提交訊標供重譯。略則 npm run validate:translations 報陳警
• 改中目擴：改而使技倍長或宜為變體。若加逾三新步，復察第三步決
• NTFS 掛路（WSL）避 git mv：於 /mnt/ 路，目錄之 git mv 或生壞權（d?????????）。用 mkdir -p + 複製 + git rm 舊路。見環境指之排疑節

參

• create-skill — 造新技之基；evolve-skill 假此先循
• commit-changes — 以述訊提交演技
• configure-git-repository — 版控技之改
• security-audit-codebase — 審演技免誤含秘