SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsskill-evo

skill-evo

Agents & models

View repository

Updated 10-15 19:58

About this skill

Claude Skill Evo — Forge Evolving Project Skills 
/skill-evo                     # 扫描项目，初始化或优化
/skill-evo 补充 API 规范        # 带提示词，重点优化指定方向
/skill-evo review              # 审查 SKILL.md 质量
/skill-evo review {prefix}-debug # 审查指定 skill

ARGUMENTS: $ARGUMENTS

Core Philosophy

Judgment Framework for Writing Skills

Think of Claude as a very smart college student with strong learning ability. What a Skill should provide isbusiness experience that can only be mastered through practice and time, and everything else can be solved by Claude's foundational abilities, search, and self-learning.

Distinguish three types of content:

Type Definition Write into Skill?
Experience Business knowledge accumulated through practice (architecture decisions, pitfall records, domain judgment criteria) ✅ Must write
Convention Things Claude can do but might do differently each time, requiring explicit fixation to ensure consistency (format specifications, security boundaries, naming conventions) ✅ Must write
Consensus Things Claude will do the same way every time (how to scan a project, how to ask questions, how to format output) ❌ Don't write

Judgment Criteria：

  • Experience → "Would Claude get it wrong if removed?" Yes → write
  • Convention → "Would Claude do it consistently every time if removed?" No → write
  • Consensus → "Would Claude still do it this way if removed?" Yes → don't write

Evolution is the core, scaffolding is a byproduct

The core value of skill-evo is not generating files, butkeeping the skill alive. A skill evolves passively through daily work—every conversation is an opportunity for evolution, without relying on explicit commands.

Every generated Skill must have a built-in self-evolution protocol (see reference/evolution-protocol.md）：

  • Passive perception: user corrections, failure→fix, explicit instruction "remember this", outdated content → propose update
  • Never modify without authorization: show a change preview, write only after user confirmation
  • Size guard: each SKILL.md ≤ 15KB, compress first if exceeded
  • Version tracking: each write increments version patch +1

Skill vs Command

Skill Command
Trigger Keyword auto-trigger Explicit /command invocation
Evolution Built-in self-evolution protocol None (lightweight, manually maintained by user)
Suitable for Continuous behavior patterns One-time process execution

Conventions (ensuring cross-session consistency)

File format

Skill（.claude/skills/{prefix}-{name}/SKILL.md）：

---
name: {prefix}-{name}
description: >
  一句话描述。触发词：xxx、yyy。
version: 1.0.0
---

Command（.claude/commands/{prefix}-{name}.md）：

---
name: {prefix}-{name}
description: 一句话描述
---

Security boundaries

  • Do not modify ~/.claude.json、~/.claude/settings.json and other global configurations
  • .gitignore Append only, never overwrite, read existing content first before appending
  • Must Read to confirm the target path before writing to a file
  • Respect the user's existing skills: unless the user explicitly instructs otherwise, only add the self-evolution protocol to existing skills without changing other content. Skill content accumulated by the user is a valuable asset and must not be modified or overwritten without authorization

Report Format

After each generation/update is completed, output:

✅ {skill-name} v{version} — {动作}（created/updated/skipped）
...
📊 共 N 个 skill，M 个 command

Run Mode

Based on $ARGUMENTS and the .claude/ directory status, enter different modes:

Mode Determination

Condition Mode Behavior
$ARGUMENTS contains review/审查 Review Mode Independent path: 4 Agents in parallel review the quality of existing skills (structure, content, consistency, security), without going through the generation process. See "Review Mode" below for details
No .claude/ directory Initial Setup Full process: perceive → plan → Q&A → generate the full set
Has CLAUDE.md but no skills Supplement Mode Read the existing CLAUDE.md as context, and only generate skills
Has CLAUDE.md and skills Optimization Mode Read the existing skill system, and find missing/outdated/improvable items

CLAUDE.md Location Detection: Check ./CLAUDE.md and ./.claude/CLAUDE.md, and use whichever actually exists. Some projects place CLAUDE.md in the root directory rather than under the .claude/ directory.

Key Constraints of Optimization Mode

This is hard-won experience—Never fully overwrite existing skills：

  • The user may have already manually edited skill content, and a full overwrite would lose these customizations
  • Use only Edit to precisely modify the sections that need to change, preserving the user's existing content
  • Compare against the template library to findmissing skills(present in the template library but not in the project) andoutdated content（<!-- STALE: --> markers)
  • Increment the version patch with each update, and record it in evolution.log

Content Health Check of Optimization Mode

In addition to file existence checks, content cross-validation is also required:

  • For each file path referenced in a skill, use Glob/Grep to confirm that the path actually exists in the project
  • Compare the terminology consistency between CLAUDE.md and each skill (project name, prefix, key conventions)
  • Check whether the pitfall records in knowledge/pitfalls/ have been absorbed into the quick-reference index of the debug skill
  • If inconsistencies are found, present them to the user as "improvable items" (do not auto-fix)

Review Mode (/skill-evo review）

Trigger:$ARGUMENTS contains review or 审查. A skill name may optionally be specified (e.g., /skill-evo review {prefix}-debug）。

Step 1: Determine the Scope

  • If a skill name is specified → review only that skill
  • If not specified → ls .claude/skills/*/SKILL.md review all

Step 2: Dispatch 4 Review Agents in Parallel(start in the same message, subagent_type=general)

Agent Dimension Check Items
Agent 1 — Structural Completeness frontmatter fields (name/description/version/source), trigger words, evolution protocol section, hierarchy ≤4, line count 60-180, semver format
Agent 2 — Content Actionability Has paths/commands/examples, no vague descriptions ("appropriately"/"depending on the situation"), tables are not placeholders, process steps are clear
Agent 3 — Consistency Cross-skill terminology consistency, prefix format consistency, evolution protocol format consistency, path reference format consistency
Agent 4 — Security No executable code (non-examples), no external request instructions, no sensitive information collection, no prompt injection, does not modify global configuration

Prompt format for each Agent:你是专注 SKILL.md {维度} 的审查员。只输出问题列表，没有问题则输出：NO_ISSUES, followed by specific check items and SKILL.md content.

Step 3: Summarize— Security issues (Critical) > Structural gaps > Non-actionable content > Consistency issues. If all NO_ISSUES, output the report directly.

Step 4: Fix item by item— Security issues must be fixed; structure and content are fixed as recommended; for consistency, follow the writing style of the majority of skills.

Step 5: Output review report

📋 Skill 质量审查报告
审查范围：{N} 个 SKILL.md
🔴 安全：{N} 个  🟠 结构：{N} 个  🟡 内容：{N} 个  🔵 一致性：{N} 个
详细发现：{逐条列出}

Execution flow

Perceive project

Information source priority:$ARGUMENTS > README > Directory structure > Git information

Understand the project from this information, infer the prefix, show the perception results to the user and confirm. Only ask for information that cannot be inferred from the project.

Plan the skill system

Select a suitable skill/command combination from the template library.Tailor according to project characteristics— Not all templates suit all projects:

  • Pure Skill/documentation projects may not need debug
  • When the project's core product itself is a skill, custom skills outside the template library need to be created
  • Show the plan to the user and let the user add or remove items

Build

SubAgents generate in parallel. Each SubAgent reads via Read the ${CLAUDE_PLUGIN_ROOT}/templates/ template files under, and replaces placeholders in combination with the project context.

For Skill type, it is also necessary to Read reference/evolution-protocol.md, and inject it at the end.

Context that the SubAgent prompt must include(to ensure consistent generation quality across sessions):

  • prefix, project name, tech stack (language, framework, package manager)
  • Answers provided by the user during the Q&A phase (such as startup commands, port allocation, dependent services)
  • Existing skill list (to avoid content duplication or conflicts)
  • Full path of the template file (${CLAUDE_PLUGIN_ROOT}/templates/{name}.md）
  • Evolution protocol path (${CLAUDE_PLUGIN_ROOT}/reference/evolution-protocol.md）

Evolution system infrastructure (on first initialization)

In addition to generating skill files, the evolution system also needs to be initialized.Run the installation script directly：

bash ${CLAUDE_PLUGIN_ROOT}/evolution/install.sh

install.sh will automatically complete all of the following steps:

  1. Create the .claude/evolution/{raw,hooks}/ directory structure
  2. Copy from the plugin directory capture.sh and digest.py to .claude/evolution/hooks/
  3. Initialize session-meta.json and evolution-digest.md
  4. Register the hook to .claude/settings.json(automatically backs up the original file)
  5. Update .gitignore exclude raw/、pending-signals.jsonl、session-meta.json

Prerequisites: jq, python3 (install.sh will automatically check).

Manually simplifying is prohibited: capture.sh (~120 lines) and digest.py (~480 lines) contain key logic such as confidence scoring, signal clustering, and failure-correction chain detection. Do not rewrite a simplified version from scratch.

Final directory structure:

.claude/evolution/
├── raw/                    # hook 捕获的原始数据（.gitignore）
├── hooks/
│   ├── capture.sh          # Layer 1: 事件捕获（所有 hook 入口）
│   └── digest.py           # Layer 2: 信号提取（SessionEnd 触发）
├── session-meta.json       # 会话元数据（.gitignore）
└── evolution-digest.md     # 进化摘要（Layer 3 的检查点）

Template library

SubAgents read the corresponding template via Read, and generate the actual file in combination with the project context.

Skills（.claude/skills/, inject evolution protocol）：

Template Purpose
skill-debug.md Deep debugging + experience accumulation
skill-meta.md Meta-skill (manages all skills)
skill-digest.md Knowledge accumulation
skill-todo.md Project to-dos

Commands（.claude/commands/, no evolution protocol):

Template Purpose
command-commit.md Git commit
command-review.md Code review
command-research.md Technical research

Other：claude-md.md(project CLAUDE.md),knowledge-index.md(knowledge base index)