skill-creator-doctor

Skill Creator Doctor

此技能提供全面的技能生命周期管理：创建、修复和维护。

关于技能

技能是模块化的独立软件包，通过提供专业知识、工作流和工具来扩展 Claude 的能力。可以将它们视为特定领域或任务的“入门指南”——它们能将 Claude 从通用 Agent 转变为具备流程性知识的专业 Agent，而这种知识是任何模型都无法完全掌握的。

技能提供什么

1. 专业工作流——特定领域的多步骤流程
2. 工具集成——使用特定文件格式或 API 的说明
3. 领域专长——公司专属知识、架构和业务逻辑
4. 随附资源——用于复杂和重复任务的脚本、参考资料和素材

技能的组成

每项技能都包含一个必需的 SKILL.md 文件，以及可选的随附资源：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必需）

元数据质量： YAML frontmatter 中的 name 和 description 决定 Claude 何时使用该技能。请具体说明技能的功能和使用时机。使用第三人称（例如，“此技能适用于……”而不是“在这种情况下使用此技能……”）。

随附资源（可选）

脚本（scripts/）

用于需要确定性可靠性或会被反复重写的任务的可执行代码（Python/Bash 等）。

• 适用场景：当相同代码被反复重写，或需要确定性可靠性时
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.py
• 优势：节省 Token、结果确定，且无需加载到上下文中即可执行
• 注意：Claude 仍可能需要读取脚本，以便进行修补或针对特定环境做调整

参考资料（references/）

需要时加载到上下文中，为 Claude 的流程和思考提供参考的文档和资料。

• 适用场景：需要 Claude 在工作时查阅的文档
• 示例：财务架构的 references/finance.md、公司 NDA 模板的 references/mnda.md、公司政策的 references/policies.md、API 规范的 references/api_docs.md
• 用途：数据库架构、API 文档、领域知识、公司政策、详细工作流指南
• 优势：让 SKILL.md 保持精简，仅在 Claude 判断有需要时加载
• 最佳实践：如果文件较大（超过 10k 个单词），请在 SKILL.md 中加入 grep 搜索模式
• 避免重复：信息应放在 SKILL.md 或参考资料文件中，而不是两处都放。详细信息优先放在参考资料文件中，除非它确实是技能的核心内容——这样既能让 SKILL.md 保持精简，也便于查找信息，避免占用过多上下文窗口。SKILL.md 中只保留必要的流程说明和工作流指导；将详细参考资料、架构和示例移至参考资料文件。

素材（assets/）

不用于加载到上下文中，而是供 Claude 在生成输出时使用的文件。

• 适用场景：技能需要在最终输出中使用文件时
• 示例：品牌素材 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 样板代码 assets/frontend-template/、字体文件 assets/font.ttf
• 用途：模板、图片、图标、样板代码、字体、需要复制或修改的示例文档
• 优势：将输出资源与文档分开，让 Claude 无需将文件加载到上下文中即可使用

渐进式披露设计原则

技能采用三级加载系统，高效管理上下文：

1. 元数据（名称 + 描述）——始终位于上下文中（约 100 个单词）
2. SKILL.md 正文——技能触发时加载（少于 5k 个单词）
3. 随附资源——由 Claude 按需加载（不限量*）

*之所以不限量，是因为脚本无需读取到上下文窗口中即可执行。

技能创建流程

创建技能时，请按顺序遵循“技能创建流程”，仅在有明确理由表明某个步骤不适用时才跳过。

第 1 步：通过具体示例了解技能

仅当技能的使用模式已经清晰明确时，才跳过此步骤。即使是在使用现有技能时，这一步也很有价值。

要创建有效的技能，必须清楚了解该技能的具体使用方式。这种了解可以来自用户提供的直接示例，也可以来自经用户反馈验证过的生成示例。

例如，构建图像编辑器技能时，相关问题包括：

• “图像编辑器技能应支持哪些功能？编辑、旋转，还是其他功能？”
• “能否给出一些使用此技能的示例？”
• “我能想到用户可能会问‘去掉这张图片中的红眼’或‘旋转这张图片’。你觉得还会有哪些用法？”
• “用户说什么时，应该触发此技能？”

为避免让用户应接不暇，不要在一条消息中提出太多问题。先问最重要的问题，再视需要跟进，以便进一步了解。

当你清楚了解技能应支持的功能后，即可结束此步骤。

第 2 步：规划可复用的技能内容

要将具体示例转化为有效的技能，请针对每个示例进行分析：

1. 思考如何从头开始完成该示例
2. 确定反复执行这些工作流时，哪些脚本、参考资料和资源会有所帮助

示例：构建 pdf-editor 技能来处理“帮我旋转这个 PDF”之类的请求时，分析表明：

1. 每次旋转 PDF 都需要重新编写相同的代码
2. 将 scripts/rotate_pdf.py 脚本存放在技能中会有所帮助

示例：设计 frontend-webapp-builder 技能来处理“帮我构建一个待办事项应用”或“帮我构建一个用于追踪步数的仪表板”之类的请求时，分析表明：

1. 编写前端 Web 应用时，每次都需要相同的 HTML/React 样板代码
2. 将包含 HTML/React 项目样板文件的 assets/hello-world/ 模板存放在技能中会有所帮助

示例：构建 big-query 技能来处理“今天有多少用户登录了？”之类的请求时，分析表明：

1. 每次查询 BigQuery 都需要重新查找表架构和关系
2. 将记录表架构的 references/schema.md 文件存放在技能中会有所帮助

要确定技能的内容，请分析每个具体示例，并整理出要纳入的可复用资源清单：脚本、参考资料和资源。

第 3 步：初始化技能

此时即可开始创建技能。

仅当要开发的技能已经存在，且需要迭代或打包时，才跳过此步骤。在这种情况下，请继续下一步。

从头创建新技能时，务必运行 init_skill.py 脚本。此脚本会便捷地生成一个新的技能模板目录，自动包含技能所需的全部内容，从而使技能创建过程更加高效、可靠。

用法：

scripts/init_skill.py <skill-name> --path <output-directory>

该脚本会：

• 在指定路径创建技能目录
• 生成带有正确 frontmatter 和 TODO 占位内容的 SKILL.md 模板
• 创建示例资源目录：scripts/、references/ 和 assets/
• 在每个目录中添加可自定义或删除的示例文件

初始化后，请根据需要自定义或移除生成的 SKILL.md 和示例文件。

步骤 4：编辑技能

编辑（新生成或现有的）技能时，请记住，该技能是为另一个 Claude 实例创建的。重点添加对 Claude 有帮助且不显而易见的信息。考虑哪些流程知识、特定领域的细节或可复用资源能帮助另一个 Claude 实例更有效地完成这些任务。

从可复用的技能内容开始

开始实施时，先使用上面确定的可复用资源：scripts/、references/ 和 assets/ 文件。请注意，此步骤可能需要用户提供输入。例如，实施 brand-guidelines 技能时，用户可能需要提供品牌素材或模板，以存放在 assets/ 中，或提供文档，以存放在 references/ 中。

此外，删除技能不需要的所有示例文件和目录。初始化脚本会在 scripts/、references/ 和 assets/ 中创建示例文件来展示结构，但大多数技能并不需要这些文件。

更新 SKILL.md

写作风格： 整个技能都使用祈使式／不定式形式（以动词开头的指令），而不是第二人称。使用客观、指导性的语言（例如，“要完成 X，请执行 Y”，而不是“你应该执行 X”或“如果你需要执行 X”）。这样可以保持内容一致清晰，便于 AI 使用。

要完成 SKILL.md，请回答以下问题：

1. 技能的目的是什么？请用几句话说明。
2. 何时应使用该技能？
3. 在实际使用中，Claude 应如何使用该技能？引用上面开发的所有可复用技能内容，让 Claude 知道如何使用这些内容。

步骤 5：打包技能

技能准备就绪后，应将其打包成可分发的 zip 文件，并与用户共享。打包过程会先自动验证技能，确保其符合所有要求：

scripts/package_skill.py <path/to/skill-folder>

可选的输出目录指定方式：

scripts/package_skill.py <path/to/skill-folder> ./dist

打包脚本将：

1. 验证技能，自动检查：

   • YAML frontmatter 格式和必需字段
   • 技能命名规范和目录结构
   • 描述的完整性和质量
   • 文件组织方式和资源引用

2. 如果验证通过，则打包技能，创建一个以技能命名的 zip 文件（例如，my-skill.zip），其中包含所有文件，并保留适用于分发的正确目录结构。

如果验证失败，脚本会报告错误并退出，不会创建软件包。修复所有验证错误，然后重新运行打包命令。

步骤 6：迭代

测试技能后，用户可能会要求改进。用户通常会在使用技能后立即提出改进要求，此时对技能表现的印象还很鲜明。

迭代工作流：

1. 在实际任务中使用技能
2. 留意遇到的困难或效率低下之处
3. 确定应如何更新 SKILL.md 或打包的资源
4. 实施更改并再次测试

技能修复与维护

技能无法使用时

技能可能因各种问题而无法加载。常见症状包括：

• 尝试激活技能时出现 “Unknown skill” 错误
• skills.json 中缺少注册条目
• SKILL.md frontmatter 中的元数据格式无效
• 目录或文件缺失等结构问题

自动修复技能

使用内置修复功能，自动诊断并修复常见问题：

# Repair a specific skill
scripts/repair_skill.py <skill-name>

# Diagnose without repairing
scripts/repair_skill.py --diagnose <skill-name>

# List all skills with issues
scripts/repair_skill.py --list-issues

常见修复场景

场景 1：注册表中找不到技能

问题：“Error: Unknown skill: my-skill-name” 解决方案：修复脚本会从 SKILL.md 中提取正确的元数据，并自动将缺失的技能添加到 skills.json 注册表中。

场景 2：Frontmatter 格式无效

问题：YAML 解析错误或缺少必需字段 解决方案：修复脚本会修正 frontmatter 格式，添加缺失的必需字段（name、description），并确保 YAML 结构正确。

场景 3：缺少技能结构

问题：缺少 SKILL.md 或必需目录 解决方案：修复脚本会识别结构问题，并提供修复指导。

场景 4：未定义类别

问题：技能引用了注册表中未定义的类别 解决方案：修复脚本会将缺失的类别定义添加到 skills.json。

手动修复注册表

对于高级用户，可以手动编辑 skills.json：

{
  "skills": {
    "my-skill": {
      "name": "My Skill Display Name",
      "category": "create",
      "triggers": ["using my skill", "activate my skill"],
      "keywords": ["my", "skill", "automation"],
      "activation_count": 0,
      "last_used": null,
      "related_skills": ["skill-creator-doctor"],
      "description": "Skill description for discovery"
    }
  },
  "categories": {
    "create": {
      "description": "Skills for building new components and features",
      "color": "#45B7D1"
    }
  }
}

技能健康状况监控

定期维护可确保技能正常运行：

# Validate a single skill
python scripts/quick_validate.py <path/to/skill>

# Comprehensive system health check
scripts/repair_skill.py --list-issues

预防最佳实践

1. 创建技能后，始终使用打包脚本进行验证
2. 创建或修改技能后，立即测试技能加载
3. 保持目录名称与注册表条目使用一致的命名
4. 在 SKILL.md 前置元数据中保持正确的 YAML 格式
5. 修改技能元数据时，更新注册表条目

实际示例：ts-foundation-restorer

ts-foundation-restorer 技能已通过此系统成功修复：

问题：技能存在于文件系统中，但无法被发现 根本原因：skills.json 中缺少注册表条目 解决方案：添加了从 SKILL.md 提取元数据的正确注册表条目 结果：技能变得可被发现且能够正常运行

这表明，修复系统无需手动干预即可快速解决技能加载失败问题。

高级故障排除指南

了解 Claude Code 技能发现机制

Claude Code 使用一种声明式、基于提示词的系统来发现技能。该系统会从多个位置扫描技能，并将元数据加载到系统提示词中。Claude 会根据文本描述决定何时调用技能——代码层面不存在算法匹配。

YAML 前置元数据的关键要求

“未知技能”错误最常见的原因是 YAML 前置元数据验证失败。

必填字段：

• name：只能使用小写字母、数字和连字符（kebab-case），最多 64 个字符
• description：简短描述（最多 1024 个字符）

正确格式：

---
name: my-skill-name
description: Brief description of what the skill does and when to use it
---

常见验证失败情况：

❌ 标题式大小写：name: My Skill Name ❌ snake_case：name: my_skill_name ❌ camelCase：name: mySkillName ❌ 下划线：name: my_skill_name ❌ XML 标签：<name>my-skill</name> ❌ 保留字：名称中包含 "anthropic"、"claude"

系统化故障排除流程

1. 验证 YAML 前置元数据格式

检查常见问题：

# View the frontmatter
cat .claude/skills/my-skill/SKILL.md | head -n 15

# Common issues to look for:
# - Missing opening or closing ---
# - Tabs instead of spaces (use spaces only)
# - Unquoted strings with special characters
# - Extra spaces or hidden characters

2. 检查隐藏字符和编码

即使 YAML 看起来正确，隐藏字符也可能导致解析失败：

# Check for hidden characters
cat -A .claude/skills/my-skill/SKILL.md | head -n 15

# Verify UTF-8 encoding
file .claude/skills/my-skill/SKILL.md

3. 验证文件结构

确保目录结构正确：

.claude/skills/my-skill/
└── SKILL.md  (required, exact capitalization)

文件必须命名为 SKILL.md（全大写）。

4. 清除 Claude Code 缓存

Claude Code 会维护缓存，这些缓存可能不会在技能修改后刷新：

# Option 1: Use /clear command (may not fully clear skill cache)
# In Claude Code session, type:
/clear

# Option 2: Completely restart Claude Code (recommended)
# Exit current session and restart:
claude

如果缓存问题持续存在：

• 完全退出 Claude Code
• 清除缓存目录（如果存在）：
  • macOS：~/Library/Caches/Claude/
  • 清除所有残留的临时文件
• 重启 Claude Code

5. 使用最小技能进行测试

创建一个测试技能以隔离问题：

mkdir -p .claude/skills/test-skill
cat > .claude/skills/test-skill/SKILL.md << 'EOF'
---
name: test-skill
description: Simple test skill for validation
---

# Test Skill

This is a test skill.
EOF

重启 Claude Code，并测试最小技能是否正常运行。

已知问题和限制

1. SDK 与 CLI 的行为差异

与独立 CLI 相比，使用 Claude Agent SDK 时技能可能无法正确加载。如果你使用 SDK，这是一个已知问题：即使配置正确，技能也不会自动发现。

2. 技能系统缓存不一致

• /clear 命令可能无法完全清除与技能相关的缓存
• 会话期间添加或修改的技能可能需要完全重启才能被识别
• 有些用户报告称，只有完全退出并重启 Claude Code 后，技能才会加载

3. Frontmatter 解析严格性

Frontmatter 解析器极其严格，可能会拒绝看似有效的文件。解析器会专门检查：

• YAML 语法是否准确（不能使用制表符，空格使用是否正确）
• 是否遵循 kebab-case 命名约定
• 是否包含保留字
• 元数据中是否含有 XML 标签或特殊字符

高级调试技巧

1. 对比正常与异常的 Skills

由于部分 Skills 可以正常工作，请准确对比它们的 frontmatter 格式：

# View working skill
cat .claude/skills/working-skill/SKILL.md | head -n 15

# View broken skill
cat .claude/skills/broken-skill/SKILL.md | head -n 15

# Look for differences in:
# - Spacing (tabs vs spaces)
# - Line endings (CRLF vs LF)
# - Character encoding
# - YAML structure

2. 检查 Claude Code 日志

查看日志，了解具体的 Skill 加载错误：

• macOS：~/Library/Logs/Claude/
• Linux：使用 --verbose 标志检查终端输出
• 查找解析错误或 Skill 验证失败

推荐的解决步骤

根据故障排除经验，按以下顺序操作：

1. 重新创建 SKILL.md 文件，确保格式干净：

   • 将内容复制到新文件
   • 确保名称仅使用小写字母、数字和连字符
   • 使用空格（而非制表符）进行缩进
   • 使用 UTF-8 编码和 Unix 换行符（LF）保存

2. 确认准确的名称格式：

   ---
   name: my-skill-name
   description: Your description here
   ---
   

3. 完全重启 Claude Code：

   • 退出当前会话
   • 关闭所有终端窗口
   • 使用 claude 重新启动

4. 测试 Skill 识别情况：

   • 提问：“列出所有可用的 Skills”
   • 检查是否显示你的 Skill

5. 如果仍然失败，请尝试重命名 Skill：

   • 改用更简单的名称：my-skill 或 skill-fix
   • 有时较短的名称效果更好

为什么有些 Skills 能正常工作，有些却不行

你遇到的不一致情况（部分 Skills 可以加载，而其他 Skills 即使格式相同也无法加载）表明可能存在以下问题：

1. 不易察觉的格式差异（制表符与空格、换行符）
2. 特定文件的字符编码问题
3. 该 Skill 的缓存损坏
4. 名称验证的边缘情况

重命名无济于事这一事实表明，问题可能出在文件内容本身（编码、隐藏字符或 YAML 结构），而非名称。

Skill 整合与优化

通过识别重复项、解决冲突、合并相似 Skills 并归档过时 Skills，管理不断增长的 Skill 集合。这能确保你的 Skill 生态系统保持高效、易于维护且没有冗余。

适用场景

• 管理不断增长的 Skill 集合（10 个以上 Skills）
• 怀疑存在用途相似的重复或重叠 Skills
• 更换技术栈（例如，从 MongoDB 迁移到 PostgreSQL）
• 移除已弃用的功能或过时的工作流
• 相似名称、触发条件或关键词导致激活混淆
• 希望优化 Skill 生态系统，以便更好地组织

核心工作流

工作流 1：扫描与清点

根据使用统计数据和元数据，全面清点所有 Skills。

# Generate skill inventory
python scripts/scan_skills.py --output skill_inventory.json

功能：

• 扫描 skills/ 目录中的所有 Skills
• 提取元数据：名称、描述、类别、触发条件、关键词
• 从 config/skills.json 读取使用统计数据
• 分析捆绑资源：脚本、参考资料、资源文件
• 输出包含汇总统计数据的结构化 JSON

输出包括：

• Skill 元数据和用途
• 激活次数和上次使用日期
• 资源分析（脚本、参考资料、资源文件）
• 类别分布
• 使用模式和趋势

工作流 2：分析相似性

识别合并候选项、触发词冲突和过时的技能。

# Analyze for consolidation opportunities
python scripts/analyze_similarity.py --inventory skill_inventory.json --threshold 0.65

# Custom threshold
python scripts/analyze_similarity.py --inventory skill_inventory.json --threshold 0.80

相似性检测方法：

1. 关键词／触发词重叠（Jaccard 相似度）

   • J(A,B) = |A ∩ B| / |A ∪ B|
   • 识别触发词相同的技能（冲突）
   • 检测触发词重叠超过 50% 的情况

2. 内容相似性

   • 比较技能描述和元数据
   • 分析语义相似性
   • 识别互补的工作流

3. 类别匹配

   • 同一类别的技能更有可能进行整合
   • 将相关的领域专用技能分组

4. 使用统计

   • 识别未使用的技能（activation_count = 0）
   • 找出过时的技能（last_used > 6 个月）
   • 根据使用模式确定优先级

输出：

• skill_consolidation_report.md（便于阅读的建议）
• skill_analysis.json（详细的分析数据）
• 优先级分类：高（>80%）、中（65-80%）、需审核（<65%）

工作流 3：审核整合报告

分析生成的报告并做出明智的决定。

# Open the generated report
cat skill_consolidation_report.md

# Key sections to review:
# - High Priority Merge Candidates (>80% similarity)
# - Trigger Conflicts (ambiguous activations)
# - Obsolete Skills (unused or outdated)
# - Medium Priority Candidates (65-80% similarity)

决策标准：

满足以下情况时合并：

• 相似度达到 80% 以上且功能重叠
• 触发词冲突导致激活结果含糊不清
• 同一领域内存在互补的工作流
• 某项技能很少使用，且适合自然地并入另一项技能

满足以下情况时归档：

• 从未使用（activation_count = 0）
• 6 个月或更久未使用
• 技术栈已变更（引用了旧技术）
• 项目已移除相关功能

工作流 4：执行技能合并

在保留功能的同时，安全地合并相似技能。

自然语言命令：

"Merge task-creator and task-manager based on the consolidation report"
"Combine these duplicate Vue debugging skills"
"Merge skill-a into skill-b, keep skill-b as primary"

合并流程：

1. 分析两项技能 - 完整阅读 SKILL.md 文件
2. 识别独有内容 - 找出每项技能中不同且有价值的内容
3. 创建统一的 SKILL.md - 保留所有独有功能
4. 合并元数据 - 合并触发词、关键词和 related_skills
5. 复制捆绑资源 - 将脚本／参考资料／资源移至主要技能
6. 更新注册表 - 使用合并后的元数据修改 config/skills.json
7. 归档次要技能 - 将其移至 skills/archive/ 并附上说明文档
8. 验证合并后的技能 - 确保其能够正常加载和运行
9. 报告完成情况 - 列出合并后的触发词／关键词和变更

注册表更新：

{
  "merged_from": ["task-creator", "task-editor"],
  "activation_count": 37,  // Sum of both skills
  "triggers": ["create task", "edit task", "manage tasks", "task operations"],
  "last_used": "2025-11-13"  // Most recent date
}

工作流 5：归档／移除过时技能

安全清理未使用或过时的技能。

自然语言命令：

"Archive old-mongodb-helper skill, we migrated to PostgreSQL"
"Remove unused-experimental-skill, it was never activated"
"Archive all skills related to deprecated feature X"

归档流程：

1. 创建归档目录 - skills/archive/[skill-name]archived[date]/
2. 移动技能 - 移动整个技能目录
3. 创建 ARCHIVED.md - 记录原因、日期和恢复说明
4. 更新注册表 - 从 config/skills.json 中移除技能条目
5. 更新引用 - 从其他技能的 related_skills 中移除该技能
6. 更新归档索引 - 添加到 skills/archive/ARCHIVE_INDEX.md

ARCHIVED.md 模板：

# Archived: [skill-name]

**Archive Date:** 2025-11-13
**Reason:** [Archive reason]
**Original Description:** [Skill description]

## Archive Reason
[Detailed explanation of why skill was archived]

## Restoration Instructions
To restore this skill:
1. Move directory from `archive/` back to `skills/`
2. Add entry to `config/skills.json`
3. Update any related_skills references
4. Test skill loading

## Related Skills
[List of skills that referenced this skill]

自然语言界面

通过自然对话使用整合功能：

分析命令：

• “扫描我的技能并查找重复项”
• “分析我的技能，找出整合机会”
• “找出我在过去 6 个月内未使用的技能”
• “检查我的技能是否存在触发词冲突”
• “有哪些整合机会？”

操作命令：

• “合并 [skill-a] 和 [skill-b]”
• “因 [reason] 归档 [old-skill]”
• “合并这些 Vue 调试技能”
• “我们已从 MongoDB 迁移到 PostgreSQL，清理旧技能”
• “修复 ‘create task’ 的触发词冲突”

示例

示例 1：重复技能

User: "I created task-creator and later task-manager. Are they duplicates?"

Claude analyzes:
- task-creator: "Create new tasks" (triggers: ["create task", "new task"], activations: 25)
- task-manager: "Create, edit, delete tasks" (triggers: ["manage tasks", "create task"], activations: 12)

Finding: 87% similar (overlapping triggers, similar purpose)

Recommendation: Merge into task-manager (more used, broader scope)

Execution:
- Merges both skills into task-manager
- Archives task-creator
- Updates registry with merged_from field
- Reports completion with consolidated triggers

示例 2：技术栈迁移

User: "We migrated from MongoDB to PostgreSQL. Which skills should I clean up?"

Claude:
- Scans all skills
- Finds: mongodb-helper, mongo-query-builder, mongodb-schema
- Recommends: Archive all three, update database-helper to focus on PostgreSQL

Execution:
- Archives MongoDB skills with proper documentation
- Updates database-helper with PostgreSQL-specific content
- Removes MongoDB skills from registry
- Updates related_skills references

示例 3：触发词冲突

User: "Check for trigger conflicts"

Claude finds:
- "create task" used by: task-creator, task-manager, project-tasks

Recommendation:
- task-creator: Change to "create new task", "add task"
- task-manager: Keep "manage tasks", "organize tasks"
- project-tasks: Change to "create project task", "add to project"

Execution:
- Updates triggers in each skill's registry entry
- Validates no conflicts remain
- Reports updated trigger mappings

最佳实践

为整合后的技能命名

• 使用范围更广的名称：task-creator + task-editor → task-manager
• 使用“领域 + 操作”模式：[domain]-[action]
• 避免使用含糊的名称：“helper”“utils”
• 名称长度控制在 64 个字符以内，并使用 kebab-case

维护计划

• 每月（5 分钟）： 快速检查明显的重复项
• 每季度（30-60 分钟）： 全面分析并整合
• 重大变更后： 技术栈迁移、移除功能

质量保证

• 归档原始技能前，务必测试合并后的技能
• 保持归档文档详尽
• 变更后验证注册表的一致性
• 重大整合后测试技能加载

实施脚本

scan_skills.py

扫描技能目录并提取全面的清单，包括元数据、使用统计、捆绑资源分析和表情符号分配。

analyze_similarity.py

使用多种相似度检测方法分析技能清单，以识别合并候选项、触发条件冲突和过时技能。生成详细的整合报告，并采用表情符号增强显示效果。

assign_emoji.py

用于管理技能表情符号的综合工具。支持自定义表情符号分配、冲突检测、基于类别的默认设置和批量操作。可与注册表和 SKILL.md frontmatter 集成。

参考资料

• references/skill-consolidation-guide.md - 包含示例的快速入门指南
• skill_consolidation_report.md - 生成的分析报告
• skill_analysis.json - 详细分析数据

技能表情符号管理

通过分配自定义表情符号来管理技能的可视化识别。技能激活和执行时会显示表情符号，让你能够即时识别当前启用的技能，并提升用户体验。

何时使用表情符号管理

• 可视化识别技能： 让技能在激活时一目了然
• 类别组织： 为技能类别使用一致的表情符号（🐛 调试、⚡ 创建、🔧 修复）
• 自定义品牌标识： 为重要或常用的技能分配特定表情符号
• 文件夹组织： 使文件夹名称与注册表中的表情符号分配保持一致
• 团队一致性： 统一团队技能集合中的表情符号用法

表情符号分配工作流

工作流 1：为单个技能分配表情符号

自然语言命令：

"Assign 🎨 emoji to ui-design skill"
"Set custom emoji for vue-debugging to 🐛"
"Give the database-helper skill the 🗃️ emoji"

脚本执行：

# Assign specific emoji to skill
python scripts/assign_emoji.py --skill vue-debugging --emoji "🐛"

# The system will:
# 1. Validate emoji character
# 2. Check for conflicts with other skills
# 3. Update skills.json registry
# 4. Update SKILL.md frontmatter
# 5. Report success or conflicts

工作流 2：基于类别分配表情符号

自然语言命令：

"Assign 🐛 emoji to all debug skills"
"Set ⚡ emoji for create category skills"
"Apply default emojis to all skills in fix category"

脚本执行：

# Assign emoji to entire category
python scripts/assign_emoji.py --category debug --emoji "🐛"

# System will:
# 1. Find all skills in the category
# 2. Check for emoji conflicts
# 3. Update all skills in category
# 4. Handle conflicts with user confirmation

工作流 3：自动分配表情符号

自然语言命令：

"Auto-assign default emojis to all skills"
"Apply category-based emojis to skills without custom assignments"
"Set up emoji defaults for my entire skill collection"

脚本执行：

# Auto-assign based on categories
python scripts/assign_emoji.py --auto-assign

# System will:
# 1. Identify skills without emojis
# 2. Apply category default emojis
# 3. Handle conflicts intelligently
# 4. Report assignments and any conflicts

工作流 4：解决表情符号冲突

自然语言命令：

"Check for emoji conflicts in my skills"
"Show me which skills have duplicate emojis"
"Suggest alternative emojis for conflicting skills"

脚本执行：

# List all emoji assignments and conflicts
python scripts/assign_emoji.py --list

# The system will:
# 1. Show all emoji assignments
# 2. Highlight conflicts (multiple skills with same emoji)
# 3. List skills without emojis
# 4. Provide suggestions for resolution

工作流 5：表情符号建议

自然语言命令：

"Suggest emojis for my new skill"
"What emoji would work best for api-integration skill?"
"Recommend emojis based on my skill description"

脚本执行：

# Get emoji suggestions for a skill
python scripts/assign_emoji.py --suggest skill-name

# System will:
# 1. Analyze skill name, category, and description
# 2. Suggest relevant emojis based on keywords
# 3. Check for conflicts with existing assignments
# 4. Provide context for each suggestion

表情符号类别默认值

系统为常见技能类别内置了默认表情符号：

{
  "emoji_defaults": {
    "debug": "🐛",      // Bug fixing and troubleshooting
    "create": "⚡",     // Building and creating
    "fix": "🔧",        // Maintenance and repair
    "optimize": "🚀",   // Performance and optimization
    "test": "🧪",      // Testing and validation
    "analyze": "📊",    // Analysis and reporting
    "implement": "🛠️",  // Implementation and development
    "specialized": "⭐", // Specialized functionality
    "meta": "🎯",       // Meta-skills and management
    "emergency": "🚨",   // Emergency and critical issues
    "default": "⚙️"     // Generic fallback
  }
}

文件夹名称集成

使用 skill-folder-emoji-updater 技能，使文件夹名称与注册表中的分配保持同步：

自然语言命令：

"Update all skill folders to match their registry emojis"
"Add 🐛 emoji to all debug skill folders"
"Make sure my skill folders have emoji prefixes"

脚本执行：

# Update all folders to match registry
python ../skill-folder-emoji-updater/scripts/update_folder_emojis.py --all

# Update specific category folders
python ../skill-folder-emoji-updater/scripts/update_folder_emojis.py --category debug

# Dry run to see what would change
python ../skill-folder-emoji-updater/scripts/update_folder_emojis.py --all --dry-run

自然语言接口

表情符号分配：

• “为 ui-design 技能分配 🎨 表情符号”
• “给 vue-debugging 分配 🐛 表情符号”
• “为 task-manager 设置自定义表情符号”

类别管理：

• “为所有调试技能应用虫子表情符号”
• “为创建类别使用闪电表情符号”
• “为我的技能设置默认表情符号”

解决冲突：

• “检查表情符号冲突”
• “显示使用重复表情符号的技能”
• “自动修复表情符号冲突”

文件夹集成：

• “使用表情符号更新技能文件夹”
• “使文件夹名称与注册表同步”
• “为所有技能文件夹添加表情符号前缀”

发现与分析：

• “为我的新技能推荐表情符号”
• “列出所有表情符号分配”
• “显示哪些技能还没有表情符号”

示例

示例 1：为单个技能分配表情符号

User: "Assign 🎨 emoji to ui-design skill"

System:
✅ Assigned emoji 🎨 to skill: ui-design
✅ Updated skills.json registry
✅ Updated SKILL.md frontmatter
✅ Updated display name: 🎨 UI Design

Natural Language Usage:
- "🎨 Using ui-design skill for component styling"
- "🎨 UI Design skill activated for layout fixes"

示例 2：类别分配

User: "Assign 🐛 emoji to all debug skills"

System:
⚠️ Emoji conflicts detected for 🐛:
   - component-debugger (existing)
   - vue-debugger (existing)

Continue anyway? (y/N): y

✅ Assigned emoji 🐛 to 5 skills in category 'debug'
   - api-debugger → 🐛 API Debugger
   - performance-debug → 🐛 Performance Debug
   - state-debugger → 🐛 State Debugger
   - render-debug → 🐛 Render Debug
   - memory-debug → 🐛 Memory Debug

示例 3：文件夹集成

User: "Update all skill folders to match their registry emojis"

System:
📋 Would rename 8 skill folders:
   🐛 vue-debugging (from: vue-debugging)
   ⚡ task-creator (from: task-creator)
   🔧 pinia-fixer (from: pinia-fixer)
   📊 analytics (from: analytics)
   ...

Apply changes? (y/N): y

✅ Updated 8 skill folders with emojis

技术实现

注册表存储

{
  "skills": {
    "vue-debugging": {
      "name": "Vue Debugging",
      "emoji": "🐛",
      "display_name": "🐛 Vue Debugging",
      "category": "debug"
    }
  }
}

Frontmatter 集成

---
name: vue-debugging
emoji: "🐛"
description: Debug Vue.js applications
---

验证功能

• Emoji 验证：确保仅使用有效的 Unicode Emoji
• 冲突检测：识别重复的 Emoji 分配
• 类别一致性：保持 Emoji 与类别之间的逻辑关联
• 交叉引用同步：确保注册表与 SKILL.md 保持一致

最佳实践

Emoji 选择指南

1. 相关性：选择与技能用途相关的 Emoji
2. 类别一致性：尽可能使用类别默认值
3. 唯一性：避免在同一类别中重复使用 Emoji
4. 清晰度：使用广为人知的 Emoji（🐛、⚡、🔧 等）
5. 可访问性：确保 Emoji 在不同平台上均能正确显示

分配工作流

1. 检查现有分配，避免冲突
2. 优先考虑类别默认值
3. 先测试 Emoji，再大规模分配
4. 同时更新注册表和 frontmatter
5. 更改后验证技能加载情况

维护计划

• 每月：检查新技能并分配 Emoji
• 每季度：检查 Emoji 冲突和一致性
• 创建技能后：将分配 Emoji 纳入创建流程
• 整合期间：保留或更新合并技能的 Emoji

与技能生态系统集成

配合使用：

• skill-creator-doctor：用于 Emoji 分配和管理
• skill-folder-emoji-updater：用于文件夹名称同步
• 技能整合系统：提供 Emoji 增强的报告和显示
• skills.json 注册表：集中存储 Emoji 分配信息

增强功能：

• 激活期间进行技能可视化识别
• 通过一致的 Emoji 实现基于类别的组织
• 文件夹可视化组织与注册表保持一致
• 通过检测和解决问题实现冲突预防

---

必须由用户验证

政策：未经用户确认，不得声称问题已修复

重要：在声称任何问题、漏洞或故障已“修复”“解决”“正常运行”或“完成”之前，必须遵循以下验证流程：

第 1 步：技术验证

• 运行所有相关测试（构建、类型检查、单元测试）
• 确认没有控制台错误
• 截取修复结果的屏幕截图或留存其他证据

第 2 步：请求用户验证

必须：使用 AskUserQuestion 工具明确请求用户验证修复结果：

"I've implemented [description of fix]. Before I mark this as complete, please verify:
1. [Specific thing to check #1]
2. [Specific thing to check #2]
3. Does this fix the issue you were experiencing?

Please confirm the fix works as expected, or let me know what's still not working."

第 3 步：等待用户确认

• 在用户回复前，不得声称已成功
• 未经用户确认，不得将任务标记为“已完成”
• 未经用户验证，不得使用“已修复”“已解决”“正常运行”等表述

第 4 步：处理用户反馈

• 如果用户确认：记录修复内容并标记为完成
• 如果用户报告问题：继续调试，并重复验证流程

未经用户验证时禁止的操作

• 声称漏洞已“修复”
• 表示功能“正常运行”
• 将问题标记为“已解决”
• 宣布功能“已完成”
• 对修复结果作出任何成功声明

请求用户验证前必须具备的证据

1. 技术测试通过
2. 通过 Playwright 或屏幕截图进行视觉确认
3. 已执行具体测试场景
4. 清楚说明所做更改

请记住：用户是判断问题是否已修复的最终权威，不得例外。