Back to Details

skill-creator-doctor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Creator Doctor

Skill Creator Doctor

This skill provides comprehensive skill lifecycle management: creation, repair, and maintenance.
本Skill提供全面的Skill生命周期管理：创建、修复和维护。

About Skills

关于Skill

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.
Skill是模块化、独立的软件包，通过提供专业知识、工作流和工具来扩展Claude的能力。可以将它们视为特定领域或任务的“入门指南”——它们能将Claude从通用型Agent转变为具备程序知识的专业Agent，而这类知识是任何模型都无法完全拥有的。

What Skills Provide

Skill能提供什么

  1. Specialized workflows - Multi-step procedures for specific domains
  2. Tool integrations - Instructions for working with specific file formats or APIs
  3. Domain expertise - Company-specific knowledge, schemas, business logic
  4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
  1. 专业工作流 - 针对特定领域的多步骤流程
  2. 工具集成 - 与特定文件格式或API协作的说明
  3. 领域专业知识 - 公司专属知识、架构、业务逻辑
  4. 捆绑资源 - 用于复杂重复任务的脚本、参考资料和资产

Anatomy of a Skill

Skill的结构

Every skill consists of a required SKILL.md file and optional bundled resources:
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都包含一个必填的SKILL.md文件和可选的捆绑资源：
skill-name/
├── SKILL.md (必填)
│   ├── YAML前置元数据 (必填)
│   │   ├── name: (必填)
│   │   └── description: (必填)
│   └── Markdown说明文档 (必填)
└── 捆绑资源 (可选)
    ├── scripts/          - 可执行代码（Python/Bash等）
    ├── references/       - 可按需加载到上下文的参考文档
    └── assets/           - 输出中使用的文件（模板、图标、字体等）

SKILL.md (required)

SKILL.md (必填)

Metadata Quality: The 
name
and 
description
in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when...").
元数据质量：YAML前置元数据中的
name
和
description
决定了Claude何时会使用该Skill。请明确说明Skill的功能和适用场景，使用第三人称表述（例如：“当需要……时应使用本Skill”，而非“当你需要……时使用本Skill”）。

Bundled Resources (optional)

捆绑资源 (可选)

Scripts (
scripts/
)
脚本 (
scripts/
)
Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
  • When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed
  • Example: 
    scripts/rotate_pdf.py
    for PDF rotation tasks
  • Benefits: Token efficient, deterministic, may be executed without loading into context
  • Note: Scripts may still need to be read by Claude for patching or environment-specific adjustments
用于需要确定性可靠性或需重复编写的任务的可执行代码（Python/Bash等）。
  • 适用场景：当相同代码需要重复编写，或需要确定性可靠性时
  • 示例：用于PDF旋转任务的
    scripts/rotate_pdf.py
  • 优势：高效使用Token、结果确定，无需加载到上下文即可执行
  • 注意：脚本可能仍需被Claude读取以进行补丁或环境特定调整
References (
references/
)
参考资料 (
references/
)
Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
  • When to include: For documentation that Claude should reference while working
  • Examples: 
    references/finance.md
    for financial schemas, 
    references/mnda.md
    for company NDA template, 
    references/policies.md
    for company policies, 
    references/api_docs.md
    for API specifications
  • Use cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
  • Benefits: Keeps SKILL.md lean, loaded only when Claude determines it's needed
  • Best practice: If files are large (>10k words), include grep search patterns in SKILL.md
  • Avoid duplication: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
用于指导Claude流程和思考的文档与参考资料，可按需加载到上下文。
  • 适用场景：Claude在工作中需要参考的文档
  • 示例：用于财务架构的
    references/finance.md
    、公司NDA模板的
    references/mnda.md
    、公司政策的
    references/policies.md
    、API规范的
    references/api_docs.md
  • 使用场景：数据库架构、API文档、领域知识、公司政策、详细工作流指南
  • 优势：保持SKILL.md简洁，仅在Claude判定需要时加载
  • 最佳实践：如果文件过大（>10000字），在SKILL.md中添加grep搜索模式
  • 避免重复：信息应仅存在于SKILL.md或参考文件中，不要重复存储。除非是Skill的核心内容，否则优先将详细信息放在参考文件中——这样既能保持SKILL.md简洁，又能让信息在不占用上下文窗口的情况下被检索到。仅在SKILL.md中保留必要的流程说明和工作流指导；将详细参考资料、架构和示例移至参考文件。
Assets (
assets/
)
资产 (
assets/
)
Files not intended to be loaded into context, but rather used within the output Claude produces.
  • When to include: When the skill needs files that will be used in the final output
  • Examples: 
    assets/logo.png
    for brand assets, 
    assets/slides.pptx
    for PowerPoint templates, 
    assets/frontend-template/
    for HTML/React boilerplate, 
    assets/font.ttf
    for typography
  • Use cases: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
  • Benefits: Separates output resources from documentation, enables Claude to use files without loading them into context
无需加载到上下文，而是用于Claude生成的输出中的文件。
  • 适用场景：Skill需要在最终输出中使用的文件
  • 示例：品牌资产
    assets/logo.png
    、PowerPoint模板
    assets/slides.pptx
    、HTML/React模板
    assets/frontend-template/
    、字体文件
    assets/font.ttf
  • 使用场景：模板、图片、图标、样板代码、字体、可复制或修改的示例文档
  • 优势：将输出资源与文档分离，使Claude无需加载到上下文即可使用文件

Progressive Disclosure Design Principle

渐进式披露设计原则

Skills use a three-level loading system to manage context efficiently:
  1. Metadata (name + description) - Always in context (~100 words)
  2. SKILL.md body - When skill triggers (<5k words)
  3. Bundled resources - As needed by Claude (Unlimited*)
*Unlimited because scripts can be executed without reading into context window.
Skill采用三级加载系统来高效管理上下文：
  1. 元数据（名称+描述） - 始终在上下文中（约100字）
  2. SKILL.md主体 - 当Skill被触发时加载（<5000字）
  3. 捆绑资源 - 由Claude按需加载（*无限制）
*无限制是因为脚本可在不读取到上下文窗口的情况下执行。

Skill Creation Process

Skill创建流程

To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable.
要创建Skill，请按“Skill创建流程”的顺序操作，仅在有明确理由时才可跳过步骤。

Step 1: Understanding the Skill with Concrete Examples

步骤1：通过具体示例理解Skill

Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
For example, when building an image-editor skill, relevant questions include:
  • "What functionality should the image-editor skill support? Editing, rotating, anything else?"
  • "Can you give some examples of how this skill would be used?"
  • "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
  • "What would a user say that should trigger this skill?"
To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
Conclude this step when there is a clear sense of the functionality the skill should support.
仅当Skill的使用模式已明确时才可跳过此步骤。即使是处理现有Skill，此步骤也依然有价值。
要创建有效的Skill，请明确理解Skill的具体使用示例。这些理解可来自直接的用户示例，或经过用户反馈验证的生成示例。
例如，在构建图像编辑Skill时，相关问题包括：
  • “图像编辑Skill应支持哪些功能？编辑、旋转，还是其他？”
  • “你能举一些该Skill的使用示例吗？”
  • “我能想到用户会要求‘去除这张图片的红眼’或‘旋转这张图片’这类操作。你认为用户还有其他使用方式吗？”
  • “用户说什么话时应该触发这个Skill？”
为避免给用户造成负担，请勿在一条消息中提出过多问题。从最重要的问题开始，必要时再跟进，以提升效率。
当明确Skill应支持的功能时，即可完成此步骤。

Step 2: Planning the Reusable Skill Contents

步骤2：规划可复用的Skill内容

To turn concrete examples into an effective skill, analyze each example by:
  1. Considering how to execute on the example from scratch
  2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
Example: When building a 
pdf-editor
skill to handle queries like "Help me rotate this PDF," the analysis shows:
  1. Rotating a PDF requires re-writing the same code each time
  2. A 
    scripts/rotate_pdf.py
    script would be helpful to store in the skill
Example: When designing a 
frontend-webapp-builder
skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
  1. Writing a frontend webapp requires the same boilerplate HTML/React each time
  2. An 
    assets/hello-world/
    template containing the boilerplate HTML/React project files would be helpful to store in the skill
Example: When building a 
big-query
skill to handle queries like "How many users have logged in today?" the analysis shows:
  1. Querying BigQuery requires re-discovering the table schemas and relationships each time
  2. A 
    references/schema.md
    file documenting the table schemas would be helpful to store in the skill
To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
要将具体示例转化为有效的Skill，请按以下方式分析每个示例：
  1. 考虑如何从零开始执行该示例
  2. 确定在重复执行这些工作流时，哪些脚本、参考资料和资产会有帮助
示例：当构建处理“帮我旋转这个PDF”这类查询的
pdf-editor
Skill时，分析显示：
  1. 旋转PDF需要重复编写相同的代码
  2. 将
    scripts/rotate_pdf.py
    脚本存储在Skill中会很有帮助
示例：当设计处理“帮我构建一个待办事项应用”或“帮我构建一个步数追踪仪表盘”这类查询的
frontend-webapp-builder
Skill时，分析显示：
  1. 构建前端Web应用需要重复编写相同的HTML/React样板代码
  2. 将包含HTML/React项目样板代码的
    assets/hello-world/
    模板存储在Skill中会很有帮助
示例：当构建处理“今天有多少用户登录？”这类查询的
big-query
Skill时，分析显示：
  1. 查询BigQuery需要反复查阅表架构和关系
  2. 将记录表架构的
    references/schema.md
    文件存储在Skill中会很有帮助
要确定Skill的内容，请分析每个具体示例，列出要包含的可复用资源：脚本、参考资料和资产。

Step 3: Initializing the Skill

步骤3：初始化Skill

At this point, it is time to actually create the skill.
Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
When creating a new skill from scratch, always run the 
init_skill.py
script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
Usage:
bash
scripts/init_skill.py <skill-name> --path <output-directory>
The script:
  • Creates the skill directory at the specified path
  • Generates a SKILL.md template with proper frontmatter and TODO placeholders
  • Creates example resource directories: 
    scripts/
    , 
    references/
    , and 
    assets/
  • Adds example files in each directory that can be customized or deleted
After initialization, customize or remove the generated SKILL.md and example files as needed.
此时即可开始实际创建Skill。
仅当正在开发的Skill已存在，且需要迭代或打包时才可跳过此步骤。这种情况下，请直接进入下一步。
从头创建新Skill时，请务必运行
init_skill.py
脚本。该脚本会方便地生成一个新的模板Skill目录，自动包含Skill所需的所有内容，使Skill创建过程更高效、更可靠。
使用方法：
bash
scripts/init_skill.py <skill-name> --path <输出目录>
该脚本会：
  • 在指定路径创建Skill目录
  • 生成带有正确前置元数据和待办事项占位符的SKILL.md模板
  • 创建示例资源目录：
    scripts/
    、
    references/
    和
    assets/
  • 在每个目录中添加可自定义或删除的示例文件
初始化完成后，根据需要自定义或删除生成的SKILL.md和示例文件。

Step 4: Edit the Skill

步骤4：编辑Skill

When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
编辑（新生成或现有）Skill时，请记住该Skill是为另一个Claude实例使用而创建的。重点包含对Claude有益且非显而易见的信息。思考哪些流程知识、领域特定细节或可复用资产能帮助另一个Claude实例更有效地执行这些任务。

Start with Reusable Skill Contents

从可复用Skill内容开始

To begin implementation, start with the reusable resources identified above: 
scripts/
, 
references/
, and 
assets/
files. Note that this step may require user input. For example, when implementing a 
brand-guidelines
skill, the user may need to provide brand assets or templates to store in 
assets/
, or documentation to store in 
references/
.
Also, delete any example files and directories not needed for the skill. The initialization script creates example files in 
scripts/
, 
references/
, and 
assets/
to demonstrate structure, but most skills won't need all of them.
开始实现时，请先处理上述确定的可复用资源：
scripts/
、
references/
和
assets/
文件。请注意，此步骤可能需要用户输入。例如，在实现
brand-guidelines
Skill时，用户可能需要提供要存储在
assets/
中的品牌资产或模板，或要存储在
references/
中的文档。
同时，删除Skill不需要的任何示例文件和目录。初始化脚本会在
scripts/
、
references/
和
assets/
中创建示例文件以展示结构，但大多数Skill不需要所有这些文件。

Update SKILL.md

更新SKILL.md

Writing Style: Write the entire skill using imperative/infinitive form (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption.
To complete SKILL.md, answer the following questions:
  1. What is the purpose of the skill, in a few sentences?
  2. When should the skill be used?
  3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.
写作风格：使用命令式/不定式形式（动词开头的指令）编写整个Skill，不要使用第二人称。使用客观的说明性语言（例如：“要完成X，请执行Y”，而非“你应该做X”或“如果你需要做X”）。这样能保持AI读取的一致性和清晰度。
要完成SKILL.md，请回答以下问题：
  1. 该Skill的用途是什么？用几句话说明。
  2. 何时应使用该Skill？
  3. 实际上，Claude应如何使用该Skill？应引用上述开发的所有可复用Skill内容，以便Claude了解如何使用它们。

Step 5: Packaging a Skill

步骤5：打包Skill

Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
bash
scripts/package_skill.py <path/to/skill-folder>
Optional output directory specification:
bash
scripts/package_skill.py <path/to/skill-folder> ./dist
The packaging script will:
  1. Validate the skill automatically, checking:
    • YAML frontmatter format and required fields
    • Skill naming conventions and directory structure
    • Description completeness and quality
    • File organization and resource references
  2. Package the skill if validation passes, creating a zip file named after the skill (e.g., 
    my-skill.zip
    ) that includes all files and maintains the proper directory structure for distribution.
If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
Skill准备就绪后，应将其打包为可分发的zip文件并分享给用户。打包过程会先自动验证Skill，确保其符合所有要求：
bash
scripts/package_skill.py <path/to/skill-folder>
可选的输出目录指定：
bash
scripts/package_skill.py <path/to/skill-folder> ./dist
打包脚本会：
  1. 自动验证Skill，检查：
    • YAML前置元数据格式和必填字段
    • Skill命名规范和目录结构
    • 描述的完整性和质量
    • 文件组织和资源引用
  2. 打包Skill（如果验证通过），创建一个以Skill命名的zip文件（例如：
    my-skill.zip
    ），包含所有文件并保持正确的目录结构以便分发。
如果验证失败，脚本会报告错误并退出，不会创建包。修复所有验证错误后，重新运行打包命令。

Step 6: Iterate

步骤6：迭代

After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
Iteration workflow:
  1. Use the skill on real tasks
  2. Notice struggles or inefficiencies
  3. Identify how SKILL.md or bundled resources should be updated
  4. Implement changes and test again
测试Skill后，用户可能会要求改进。通常这会发生在用户刚使用Skill后，此时用户对Skill的表现有清晰的上下文认知。
迭代工作流：
  1. 在实际任务中使用Skill
  2. 注意遇到的困难或低效之处
  3. 确定应如何更新SKILL.md或捆绑资源
  4. 实施更改并再次测试

Skill Repair & Maintenance

Skill修复与维护

When Skills Break

Skill故障场景

Skills can fail to load due to various issues. Common symptoms include:
  • "Unknown skill" errors when trying to activate a skill
  • Missing registry entries in skills.json
  • Invalid metadata format in SKILL.md frontmatter
  • Structural problems with missing directories or files
Skill可能因多种原因无法加载。常见症状包括：
  • 尝试激活Skill时出现**“未知Skill”错误**
  • skills.json中缺少注册表项
  • SKILL.md前置元数据中元数据格式无效
  • 结构问题：缺少目录或文件

Automated Skill Repair

自动Skill修复

Use the built-in repair functionality to automatically diagnose and fix common issues:
bash
undefined
使用内置的修复功能自动诊断并修复常见问题：
bash
undefined

Repair a specific skill

修复特定Skill

scripts/repair_skill.py <skill-name>
scripts/repair_skill.py <skill-name>

Diagnose without repairing

仅诊断不修复

scripts/repair_skill.py --diagnose <skill-name>
scripts/repair_skill.py --diagnose <skill-name>

List all skills with issues

列出所有有问题的Skill

scripts/repair_skill.py --list-issues
undefined
scripts/repair_skill.py --list-issues
undefined

Common Repair Scenarios

常见修复场景

Scenario 1: Skill Not Found in Registry

场景1：注册表中找不到Skill

Problem: "Error: Unknown skill: my-skill-name" Solution: The repair script automatically adds missing skills to the skills.json registry with proper metadata extracted from SKILL.md.
问题：“错误：未知Skill: my-skill-name” 解决方案：修复脚本会自动将缺少的Skill添加到skills.json注册表中，并从SKILL.md中提取正确的元数据。

Scenario 2: Invalid Frontmatter Format

场景2：前置元数据格式无效

Problem: YAML parsing errors or missing required fields Solution: The repair script fixes frontmatter format, adds missing required fields (name, description), and ensures proper YAML structure.
问题：YAML解析错误或缺少必填字段 解决方案：修复脚本会修复前置元数据格式，添加缺少的必填字段（name、description），并确保YAML结构正确。

Scenario 3: Missing Skill Structure

场景3：Skill结构缺失

Problem: Missing SKILL.md or required directories Solution: The repair script identifies structural issues and provides guidance for fixing them.
问题：缺少SKILL.md或必填目录 解决方案：修复脚本会识别结构问题，并提供修复指导。

Scenario 4: Category Not Defined

场景4：未定义类别

Problem: Skill references undefined category in registry Solution: The repair script adds missing category definitions to skills.json.
问题：Skill在注册表中引用了未定义的类别 解决方案：修复脚本会将缺少的类别定义添加到skills.json中。

Manual Registry Fixes

手动注册表修复

For advanced users, skills.json can be manually edited:
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"
    }
  }
}
高级用户可手动编辑skills.json：
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"
    }
  }
}

Skill Health Monitoring

Skill健康监控

Regular maintenance ensures skills remain functional:
bash
undefined
定期维护可确保Skill保持可用状态：
bash
undefined

Validate a single skill

验证单个Skill

python scripts/quick_validate.py <path/to/skill>
python scripts/quick_validate.py <path/to/skill>

Comprehensive system health check

全面系统健康检查

scripts/repair_skill.py --list-issues
undefined
scripts/repair_skill.py --list-issues
undefined

Prevention Best Practices

预防最佳实践

  1. Always validate skills after creation with the packaging script
  2. Test skill loading immediately after creation or modification
  3. Use consistent naming between directory names and registry entries
  4. Maintain proper YAML format in SKILL.md frontmatter
  5. Update registry entries when modifying skill metadata
  1. 创建后始终验证Skill：使用打包脚本进行验证
  2. 创建或修改后立即测试Skill加载
  3. 保持命名一致：目录名称与注册表项一致
  4. 保持YAML格式正确：在SKILL.md前置元数据中
  5. 修改Skill元数据时更新注册表项

Real-World Example: ts-foundation-restorer

实际示例：ts-foundation-restorer

The ts-foundation-restorer skill was successfully repaired using this system:
Issue: Skill existed in filesystem but wasn't discoverable Root Cause: Missing registry entry in skills.json Solution: Added proper registry entry with metadata extracted from SKILL.md Result: Skill became discoverable and functional
This demonstrates how the repair system can quickly resolve skill loading failures without manual intervention.
ts-foundation-restorerSkill已通过本系统成功修复：
问题：Skill存在于文件系统中，但无法被发现 根本原因：skills.json中缺少注册表项 解决方案：添加从SKILL.md中提取的正确元数据到注册表项 结果：Skill可被发现并正常使用
这展示了修复系统无需人工干预即可快速解决Skill加载故障的能力。

Advanced Troubleshooting Guide

高级故障排除指南

Understanding Claude Code Skill Discovery

理解Claude Code Skill发现机制

Claude Code uses a declarative, prompt-based system for skill discovery. The system scans skills from multiple locations and loads metadata into the system prompt. Claude decides when to invoke skills based on textual descriptions—there's no algorithmic matching at the code level.
Claude Code使用声明式、基于提示的系统进行Skill发现。系统从多个位置扫描Skill，并将元数据加载到系统提示中。Claude根据文本描述决定何时调用Skill——代码层面没有算法匹配。

Critical YAML Frontmatter Requirements

关键YAML前置元数据要求

The most common cause of "Unknown skill" errors is YAML frontmatter validation failures.
Required Fields:
  • name
    : Must use lowercase letters, numbers, and hyphens only (kebab-case), max 64 characters
  • description
    : Brief description (max 1024 characters)
Correct Format:
yaml
---
name: my-skill-name
description: Brief description of what the skill does and when to use it
---
Common Validation Failures:
❌ Title Case: 
name: My Skill Name
❌ snake_case: 
name: my_skill_name
❌ camelCase: 
name: mySkillName
❌ Underscores: 
name: my_skill_name
❌ XML tags: 
<name>my-skill</name>
❌ Reserved words: Names containing "anthropic", "claude"
“未知Skill”错误最常见的原因是YAML前置元数据验证失败。
必填字段：
  • name
    ：只能使用小写字母、数字和连字符（短横线命名法），最多64个字符
  • description
    ：简短描述（最多1024个字符）
正确格式：
yaml
---
name: my-skill-name
description: Brief description of what the skill does and when to use it
---
常见验证失败情况：
❌ 标题大小写：
name: My Skill Name
❌ 下划线命名：
name: my_skill_name
❌ 驼峰命名：
name: mySkillName
❌ 包含下划线：
name: my_skill_name
❌ XML标签：
<name>my-skill</name>
❌ 保留字：名称包含“anthropic”、“claude”

Systematic Troubleshooting Process

系统化故障排除流程

1. Validate YAML Frontmatter Format

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

Check for common issues:
bash
undefined
检查常见问题：
bash
undefined

View the frontmatter

查看前置元数据

cat .claude/skills/my-skill/SKILL.md | head -n 15
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

- 多余空格或隐藏字符

undefined
undefined

2. Check for Hidden Characters and Encoding

2. 检查隐藏字符和编码

Even if YAML looks correct, hidden characters can cause parsing failures:
bash
undefined
即使YAML看起来正确，隐藏字符也可能导致解析失败：
bash
undefined

Check for hidden characters

检查隐藏字符

cat -A .claude/skills/my-skill/SKILL.md | head -n 15
cat -A .claude/skills/my-skill/SKILL.md | head -n 15

Verify UTF-8 encoding

验证UTF-8编码

file .claude/skills/my-skill/SKILL.md
undefined
file .claude/skills/my-skill/SKILL.md
undefined

3. Verify File Structure

3. 验证文件结构

Ensure the directory structure is correct:
.claude/skills/my-skill/
└── SKILL.md  (required, exact capitalization)
The file must be named 
SKILL.md
(all caps).
确保目录结构正确：
.claude/skills/my-skill/
└── SKILL.md  (必填，大小写必须完全一致)
文件必须命名为
SKILL.md
（全大写）。

4. Clear Claude Code Cache

4. 清除Claude Code缓存

Claude Code maintains caches that may not refresh after skill modifications:
bash
undefined
Claude Code会维护缓存，修改Skill后缓存可能不会刷新：
bash
undefined

Option 1: Use /clear command (may not fully clear skill cache)

选项1：使用/clear命令（可能无法完全清除Skill缓存）

In Claude Code session, type:

在Claude Code会话中输入：

/clear
/clear

Option 2: Completely restart Claude Code (recommended)

选项2：完全重启Claude Code（推荐）

Exit current session and restart:

退出当前会话并重启：

claude

For persistent cache issues:
- Quit Claude Code completely
- Clear cache directories (if they exist):
  - macOS: `~/Library/Caches/Claude/`
  - Clear any residual temp files
- Restart Claude Code
claude

对于持续的缓存问题：
- 完全退出Claude Code
- 清除缓存目录（如果存在）：
  - macOS: `~/Library/Caches/Claude/`
  - 清除所有残留临时文件
- 重启Claude Code

5. Test with Minimal Skill

5. 使用最小化Skill测试

Create a test skill to isolate the issue:
bash
mkdir -p .claude/skills/test-skill
cat > .claude/skills/test-skill/SKILL.md << 'EOF'
---
name: test-skill
description: Simple test skill for validation
---
创建测试Skill以隔离问题：
bash
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

Test Skill

This is a test skill. EOF

Restart Claude Code and test if the minimal skill works.
This is a test skill. EOF

重启Claude Code并测试最小化Skill是否可用。

Known Issues and Limitations

已知问题和限制

1. SDK vs CLI Behavior

1. SDK与CLI行为差异

Skills may not load correctly when using the Claude Agent SDK compared to the standalone CLI. If you're using the SDK, this is a known issue where skills are not auto-discovered despite correct configuration.
与独立CLI相比，使用Claude Agent SDK时Skill可能无法正确加载。如果使用SDK，这是一个已知问题：尽管配置正确，Skill仍无法被自动发现。

2. Skill System Cache Inconsistencies

2. Skill系统缓存不一致

  • The 
    /clear
    command may not fully clear skill-related caches
  • Skills added or modified during a session may require a complete restart to be recognized
  • Some users report skills only load after exiting and restarting Claude Code entirely
  • /clear
    命令可能无法完全清除与Skill相关的缓存
  • 会话期间添加或修改的Skill可能需要完全重启才能被识别
  • 一些用户报告Skill仅在退出并完全重启Claude Code后才能加载

3. Frontmatter Parser Strictness

3. 前置元数据解析器严格性

The frontmatter parser is extremely strict and may reject files that appear valid. The parser specifically checks for:
  • Exact YAML syntax (no tabs, proper spacing)
  • Kebab-case naming convention
  • Absence of reserved words
  • No XML tags or special characters in metadata
前置元数据解析器极为严格，可能会拒绝看起来有效的文件。解析器会专门检查：
  • 精确的YAML语法（无制表符、正确缩进）
  • 短横线命名规范
  • 无保留字
  • 元数据中无XML标签或特殊字符

Advanced Debugging Techniques

高级调试技术

1. Compare Working vs Broken Skills

1. 对比可用Skill与故障Skill

Since some skills work correctly, compare their frontmatter format exactly:
bash
undefined
由于部分Skill可正常工作，请精确对比它们的前置元数据格式：
bash
undefined

View working skill

查看可用Skill

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

View broken skill

查看故障Skill

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

Look for differences in:

查找以下方面的差异：

- Spacing (tabs vs spaces)

- 缩进（制表符vs空格）

- Line endings (CRLF vs LF)

- 行尾（CRLF vs LF）

- Character encoding

- 字符编码

- YAML structure

- YAML结构

undefined
undefined

2. Check Claude Code Logs

2. 查看Claude Code日志

View logs to see specific skill loading errors:
  • macOS: 
    ~/Library/Logs/Claude/
  • Linux: Check terminal output with 
    --verbose
    flag
  • Look for parsing errors or skill validation failures
查看日志以了解具体的Skill加载错误：
  • macOS: 
    ~/Library/Logs/Claude/
  • Linux: 使用
    --verbose
    标志查看终端输出
  • 查找解析错误或Skill验证失败信息

Recommended Solution Path

推荐解决方案路径

Based on troubleshooting experience, follow these steps in order:
  1. Recreate the SKILL.md file with guaranteed-clean formatting:
    • Copy the content to a new file
    • Ensure name uses only lowercase letters, numbers, and hyphens
    • Use spaces (not tabs) for indentation
    • Save with UTF-8 encoding, Unix line endings (LF)
  2. Verify the exact name format:
    yaml
    ---
name: my-skill-name
description: Your description here
---
  3. Completely restart Claude Code:
    • Exit the current session
    • Close all terminal windows
    • Start fresh with 
      claude
  4. Test skill recognition:
    • Ask: "List all available Skills"
    • Check if your skill appears
  5. If still failing, try renaming the skill:
    • Change to something simpler: 
      my-skill
      or 
      skill-fix
    • Sometimes shorter names work better
基于故障排除经验，请按以下顺序操作：
  1. 重新创建SKILL.md文件，确保格式干净：
    • 将内容复制到新文件
    • 确保名称仅使用小写字母、数字和连字符
    • 使用空格（而非制表符）进行缩进
    • 以UTF-8编码保存，使用Unix行尾（LF）
  2. 验证名称格式是否精确：
    yaml
    ---
name: my-skill-name
description: Your description here
---
  3. 完全重启Claude Code：
    • 退出当前会话
    • 关闭所有终端窗口
    • 使用
      claude
      命令重新启动
  4. 测试Skill识别：
    • 询问：“列出所有可用的Skill”
    • 检查你的Skill是否出现
  5. 如果仍然失败，尝试重命名Skill：
    • 改为更简单的名称：
      my-skill
      或
      skill-fix
    • 有时较短的名称效果更好

Why Some Skills Work and Others Don't

为何部分Skill可用，部分不可用

The inconsistency you're experiencing (some skills load, others don't with identical formats) suggests:
  1. Subtle formatting differences invisible to the eye (tabs vs spaces, line endings)
  2. Character encoding issues in the specific file
  3. Cache corruption for that particular skill
  4. Name validation edge case
The fact that renaming doesn't help suggests the issue is likely in the file content itself (encoding, hidden characters, or YAML structure) rather than the name.
你遇到的不一致情况（部分Skill可加载，部分格式相同却不可加载）可能由以下原因导致：
  1. 肉眼不可见的细微格式差异（制表符vs空格、行尾）
  2. 特定文件的字符编码问题
  3. 该Skill的缓存损坏
  4. 名称验证的边缘情况
重命名无效表明问题可能出在文件内容本身（编码、隐藏字符或YAML结构），而非名称。

Skill Consolidation & Optimization

Skill整合与优化

Manage growing skill collections by identifying duplicates, resolving conflicts, merging similar skills, and archiving obsolete skills. This ensures your skill ecosystem remains efficient, maintainable, and free of redundancy.
通过识别重复项、解决冲突、合并相似Skill和归档过时Skill来管理不断增长的Skill集合。这可确保你的Skill生态系统保持高效、易于维护且无冗余。

When to Use

适用场景

  • Managing growing skill collections (10+ skills)
  • Suspecting duplicate/overlapping skills with similar purposes
  • Changing technology stacks (e.g., migrating from MongoDB to PostgreSQL)
  • Removing deprecated features or outdated workflows
  • Similar names/triggers/keywords causing activation confusion
  • Wanting to optimize the skill ecosystem for better organization
  • 管理不断增长的Skill集合（10个以上Skill）
  • 怀疑存在重复/重叠Skill，用途相似
  • 技术栈变更（例如：从MongoDB迁移到PostgreSQL）
  • 移除已弃用功能或过时工作流
  • 相似名称/触发器/关键词导致激活混淆
  • 希望优化Skill生态系统以提升组织性

Core Workflows

核心工作流

Workflow 1: Scan & Inventory

工作流1：扫描与盘点

Build comprehensive inventory of all skills with usage statistics and metadata.
bash
undefined
构建包含使用统计数据和元数据的全面Skill盘点。
bash
undefined

Generate skill inventory

生成Skill盘点

python scripts/scan_skills.py --output skill_inventory.json

**What it does:**
- Scans all skills in skills/ directory
- Extracts metadata: name, description, category, triggers, keywords
- Reads usage stats from config/skills.json
- Analyzes bundled resources: scripts, references, assets
- Outputs structured JSON with summary statistics

**Output includes:**
- Skill metadata and purpose
- Activation counts and last used dates
- Resource analysis (scripts, references, assets)
- Category distribution
- Usage patterns and trends
python scripts/scan_skills.py --output skill_inventory.json

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

**输出内容**：
- Skill元数据和用途
- 激活次数和最后使用日期
- 资源分析（脚本、参考资料、资产）
- 类别分布
- 使用模式和趋势

Workflow 2: Analyze Similarity

工作流2：相似性分析

Identify merge candidates, trigger conflicts, and obsolete skills.
bash
undefined
识别合并候选、触发器冲突和过时Skill。
bash
undefined

Analyze for consolidation opportunities

分析整合机会

python scripts/analyze_similarity.py --inventory skill_inventory.json --threshold 0.65
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

**Similarity Detection Methods:**

1. **Keyword/Trigger Overlap** (Jaccard Similarity)
   - J(A,B) = |A ∩ B| / |A ∪ B|
   - Identifies skills with shared triggers (conflicts)
   - Detects >50% trigger overlap

2. **Content Similarity**
   - Compares skill descriptions and metadata
   - Analyzes semantic similarity
   - Identifies complementary workflows

3. **Category Matching**
   - Skills in same category have higher consolidation likelihood
   - Groups related domain-specific skills

4. **Usage Statistics**
   - Identifies unused skills (activation_count = 0)
   - Finds outdated skills (last_used > 6 months)
   - Prioritizes based on usage patterns

**Outputs:**
- `skill_consolidation_report.md` (human-readable recommendations)
- `skill_analysis.json` (detailed analysis data)
- Priority categorization: High (>80%), Medium (65-80%), Review (<65%)
python scripts/analyze_similarity.py --inventory skill_inventory.json --threshold 0.80

**相似性检测方法**：

1. **关键词/触发器重叠**（杰卡德相似性）
   - J(A,B) = |A ∩ B| / |A ∪ B|
   - 识别具有共享触发器的Skill（冲突）
   - 检测>50%的触发器重叠

2. **内容相似性**
   - 比较Skill描述和元数据
   - 分析语义相似性
   - 识别互补工作流

3. **类别匹配**
   - 同一类别的Skill更有可能被整合
   - 分组相关的领域特定Skill

4. **使用统计数据**
   - 识别未使用的Skill（activation_count = 0）
   - 发现过时Skill（last_used > 6个月）
   - 根据使用模式确定优先级

**输出**：
- `skill_consolidation_report.md`（人类可读的建议）
- `skill_analysis.json`（详细分析数据）
- 优先级分类：高（>80%）、中（65-80%）、待审核（<65%）

Workflow 3: Review Consolidation Report

工作流3：审核整合报告

Analyze the generated report and make informed decisions.
bash
undefined
分析生成的报告并做出明智决策。
bash
undefined

Open the generated report

打开生成的报告

cat skill_consolidation_report.md
cat skill_consolidation_report.md

Key sections to review:

需审核的关键部分：

- High Priority Merge Candidates (>80% similarity)

- 高优先级合并候选（>80%相似性）

- Trigger Conflicts (ambiguous activations)

- 触发器冲突（激活模糊）

- Obsolete Skills (unused or outdated)

- 过时Skill（未使用或已过期）

- Medium Priority Candidates (65-80% similarity)

- 中优先级候选（65-80%相似性）


**Decision Criteria:**

**Merge When:**
- 80%+ similarity with overlapping functionality
- Trigger conflicts causing ambiguous activation
- Complementary workflows in same domain
- One skill rarely used, fits naturally in another

**Archive When:**
- Never used (activation_count = 0)
- Not used in 6+ months
- Tech stack changed (old technology references)
- Features removed from project

**决策标准**：

**合并场景**：
- 80%+相似性，功能重叠
- 触发器冲突导致激活模糊
- 同一领域的互补工作流
- 一个Skill很少使用，可自然融入另一个Skill

**归档场景**：
- 从未使用过（activation_count = 0）
- 6个月以上未使用
- 技术栈变更（引用旧技术）
- 项目中已移除相关功能

Workflow 4: Execute Skill Merges

工作流4：执行Skill合并

Safely merge similar skills while preserving functionality.
Natural Language Commands:
"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"
Merge Process:
  1. Analyze both skills - Read SKILL.md files completely
  2. Identify unique content - Find different/valuable content in each
  3. Create unified SKILL.md - Preserve all unique functionality
  4. Combine metadata - Merge triggers, keywords, related_skills
  5. Copy bundled resources - Move scripts/references/assets to primary skill
  6. Update registry - Modify config/skills.json with merged metadata
  7. Archive secondary skill - Move to skills/archive/ with documentation
  8. Validate merged skill - Ensure it loads and functions correctly
  9. Report completion - List merged triggers/keywords and changes
Registry Updates:
json
{
  "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
}
安全地合并相似Skill，同时保留功能。
自然语言命令：
"根据整合报告合并task-creator和task-manager"
"合并这些重复的Vue调试Skill"
"将skill-a合并到skill-b中，保留skill-b作为主Skill"
合并流程：
  1. 分析两个Skill - 完整读取SKILL.md文件
  2. 识别独特内容 - 找出每个Skill中不同/有价值的内容
  3. 创建统一的SKILL.md - 保留所有独特功能
  4. 合并元数据 - 合并触发器、关键词、related_skills
  5. 复制捆绑资源 - 将脚本/参考资料/资产移动到主Skill
  6. 更新注册表 - 在config/skills.json中修改合并后的元数据
  7. 归档次要Skill - 移至skills/archive/并添加文档
  8. 验证合并后的Skill - 确保其可加载并正常运行
  9. 报告完成情况 - 列出合并后的触发器/关键词和变更内容
注册表更新：
json
{
  "merged_from": ["task-creator", "task-editor"],
  "activation_count": 37,  // 两个Skill的总和
  "triggers": ["create task", "edit task", "manage tasks", "task operations"],
  "last_used": "2025-11-13"  // 最新日期
}

Workflow 5: Archive/Remove Obsolete Skills

工作流5：归档/移除过时Skill

Clean up unused or outdated skills safely.
Natural Language Commands:
"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"
Archive Process:
  1. Create archive directory - 
    skills/archive/[skill-name]archived[date]/
  2. Move skill - Relocate entire skill directory
  3. Create ARCHIVED.md - Document reason, date, and restoration instructions
  4. Update registry - Remove skill entry from config/skills.json
  5. Update references - Remove from related_skills in other skills
  6. Update archive index - Add to skills/archive/ARCHIVE_INDEX.md
ARCHIVED.md Template:
markdown
undefined
安全清理未使用或过时的Skill。
自然语言命令：
"归档old-mongodb-helperSkill，我们已迁移到PostgreSQL"
"移除unused-experimental-skill，它从未被激活过"
"归档所有与已弃用功能X相关的Skill"
归档流程：
  1. 创建归档目录 - 
    skills/archive/[skill-name]archived[date]/
  2. 移动Skill - 迁移整个Skill目录
  3. 创建ARCHIVED.md - 记录原因、日期和恢复说明
  4. 更新注册表 - 从config/skills.json中移除Skill条目
  5. 更新引用 - 从其他Skill的related_skills中移除
  6. 更新归档索引 - 添加到skills/archive/ARCHIVE_INDEX.md
ARCHIVED.md模板：
markdown
undefined

Archived: [skill-name]

已归档: [skill-name]

Archive Date: 2025-11-13 Reason: [Archive reason] Original Description: [Skill description]
归档日期: 2025-11-13 原因: [归档原因] 原始描述: [Skill描述]

Archive Reason

归档原因

[Detailed explanation of why skill was archived]
[详细说明归档该Skill的原因]

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
要恢复此Skill：
  1. 将目录从
    archive/
    移回
    skills/
  2. 将条目添加到
    config/skills.json
  3. 更新所有related_skills引用
  4. 测试Skill加载

Related Skills

相关Skill

[List of skills that referenced this skill]
undefined
[引用过此Skill的Skill列表]
undefined

Natural Language Interface

自然语言界面

Use consolidation features through natural conversation:
Analysis Commands:
  • "Scan my skills and find duplicates"
  • "Analyze my skills for consolidation opportunities"
  • "Find skills I haven't used in 6 months"
  • "Check for trigger conflicts in my skills"
  • "What consolidation opportunities do I have?"
Action Commands:
  • "Merge [skill-a] and [skill-b]"
  • "Archive [old-skill] because [reason]"
  • "Combine these Vue debugging skills"
  • "We migrated from MongoDB to PostgreSQL, clean up old skills"
  • "Fix the trigger conflicts for 'create task'"
通过自然对话使用整合功能：
分析命令：
  • "扫描我的Skill并找出重复项"
  • "分析我的Skill的整合机会"
  • "找出我6个月未使用的Skill"
  • "检查我的Skill是否存在触发器冲突"
  • "我有哪些整合机会？"
操作命令：
  • "合并[skill-a]和[skill-b]"
  • "归档[old-skill]，原因是[原因]"
  • "合并这些Vue调试Skill"
  • "我们已从MongoDB迁移到PostgreSQL，请清理旧Skill"
  • "修复'创建任务'的触发器冲突"

Examples

示例

Example 1: Duplicate Skills

示例1：重复Skill

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
用户: "我创建了task-creator，后来又创建了task-manager。它们是重复项吗？"

Claude分析：
- task-creator: "创建新任务"（触发器: ["create task", "new task"]，激活次数:25）
- task-manager: "创建、编辑、删除任务"（触发器: ["manage tasks", "create task"]，激活次数:12）

发现：87%相似（触发器重叠，用途相似）

建议：合并到task-manager（使用更频繁，范围更广）

执行：
- 将两个Skill合并到task-manager
- 归档task-creator
- 在注册表中更新merged_from字段
- 报告合并后的触发器和完成情况

Example 2: Tech Stack Migration

示例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
用户: "我们已从MongoDB迁移到PostgreSQL。我应该清理哪些Skill？"

Claude：
- 扫描所有Skill
- 发现：mongodb-helper、mongo-query-builder、mongodb-schema
- 建议：归档这三个Skill，更新database-helper以专注于PostgreSQL

执行：
- 归档MongoDB Skill并添加正确文档
- 更新database-helper的PostgreSQL特定内容
- 从注册表中移除MongoDB Skill
- 更新related_skills引用

Example 3: Trigger Conflicts

示例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
用户: "检查触发器冲突"

Claude发现：
- "create task"被以下Skill使用：task-creator、task-manager、project-tasks

建议：
- task-creator：改为"create new task"、"add task"
- task-manager：保留"manage tasks"、"organize tasks"
- project-tasks：改为"create project task"、"add to project"

执行：
- 更新每个Skill注册表条目中的触发器
- 验证无冲突残留
- 报告更新后的触发器映射

Best Practices

最佳实践

Naming Consolidated Skills

整合Skill的命名

  • Use broader names: 
    task-creator
    + 
    task-editor
    → 
    task-manager
  • Use domain + action pattern: 
    [domain]-[action]
  • Avoid vague names: "helper", "utils"
  • Keep names under 64 characters with kebab-case
  • 使用更宽泛的名称：
    task-creator
    + 
    task-editor
    → 
    task-manager
  • 使用领域+动作模式：
    [domain]-[action]
  • 避免模糊名称："helper"、"utils"
  • 名称保持在64个字符以内，使用短横线命名法

Maintenance Schedule

维护计划

  • Monthly (5 minutes): Quick scan for obvious duplicates
  • Quarterly (30-60 minutes): Full analysis and consolidation
  • After major changes: Tech stack migration, feature removal
  • 每月（5分钟）：快速扫描明显的重复项
  • 每季度（30-60分钟）：全面分析和整合
  • 重大变更后：技术栈迁移、功能移除

Quality Assurance

质量保证

  • Always test merged skills before archiving originals
  • Keep archive documentation thorough
  • Validate registry consistency after changes
  • Test skill loading after major consolidation
  • 在归档原始Skill前始终测试合并后的Skill
  • 保持归档文档详尽
  • 变更后验证注册表一致性
  • 重大整合后测试Skill加载

Implementation Scripts

实现脚本

scan_skills.py

scan_skills.py

Scans skills directory and extracts comprehensive inventory including metadata, usage statistics, bundled resources analysis, and emoji assignments.
扫描skills目录并提取全面盘点信息，包括元数据、使用统计数据、捆绑资源分析和表情符号分配。

analyze_similarity.py

analyze_similarity.py

Analyzes skill inventory using multiple similarity detection methods to identify merge candidates, trigger conflicts, and obsolete skills. Generates detailed consolidation reports with emoji-enhanced displays.
使用多种相似性检测方法分析Skill盘点，识别合并候选、触发器冲突和过时Skill。生成带有表情符号增强显示的详细整合报告。

assign_emoji.py

assign_emoji.py

Comprehensive emoji management utility for skills. Supports custom emoji assignment, conflict detection, category-based defaults, and batch operations. Integrates with both registry and SKILL.md frontmatter.
全面的Skill表情符号管理工具。支持自定义表情符号分配、冲突检测、基于类别的默认值和批量操作。与注册表和SKILL.md前置元数据集成。

References

参考资料

  • references/skill-consolidation-guide.md
    - Quick start guide with examples
  • skill_consolidation_report.md
    - Generated analysis report
  • skill_analysis.json
    - Detailed analysis data
  • references/skill-consolidation-guide.md
    - 带示例的快速入门指南
  • skill_consolidation_report.md
    - 生成的分析报告
  • skill_analysis.json
    - 详细分析数据

Skill Emoji Management

Skill表情符号管理

Manage visual identification of skills through custom emoji assignment. Emojis appear during skill activation and execution, providing instant recognition of active skills and better user experience.
通过自定义表情符号分配管理Skill的视觉识别。表情符号会在Skill激活和执行时显示，提供即时的活动Skill识别，提升用户体验。

When to Use Emoji Management

表情符号管理的适用场景

  • Visual Skill Identification: Make skills instantly recognizable during activation
  • Category Organization: Use consistent emojis for skill categories (🐛 debug, ⚡ create, 🔧 fix)
  • Custom Branding: Assign specific emojis to important or frequently used skills
  • Folder Organization: Align folder names with registry emoji assignments
  • Team Consistency: Standardize emoji usage across team skill collections
  • 视觉Skill识别：使Skill在激活时可被即时识别
  • 类别组织：为Skill类别使用一致的表情符号（🐛调试、⚡创建、🔧修复）
  • 自定义品牌：为重要或频繁使用的Skill分配特定表情符号
  • 文件夹组织：使文件夹名称与注册表表情符号分配保持一致
  • 团队一致性：在团队Skill集合中标准化表情符号使用

Emoji Assignment Workflow

表情符号分配工作流

Workflow 1: Individual Skill Emoji Assignment

工作流1：单个Skill表情符号分配

Natural Language Commands:
"Assign 🎨 emoji to ui-design skill"
"Set custom emoji for vue-debugging to 🐛"
"Give the database-helper skill the 🗃️ emoji"
Script Execution:
bash
undefined
自然语言命令：
"为ui-designSkill分配🎨表情符号"
"为vue-debugging设置自定义表情符号🐛"
"为database-helperSkill分配🗃️表情符号"
脚本执行：
bash
undefined

Assign specific emoji to skill

为Skill分配特定表情符号

python scripts/assign_emoji.py --skill vue-debugging --emoji "🐛"
python scripts/assign_emoji.py --skill vue-debugging --emoji "🐛"

The system will:

系统会：

1. Validate emoji character

1. 验证表情符号字符

2. Check for conflicts with other skills

2. 检查与其他Skill的冲突

3. Update skills.json registry

3. 更新skills.json注册表

4. Update SKILL.md frontmatter

4. 更新SKILL.md前置元数据

5. Report success or conflicts

5. 报告成功或冲突情况

undefined
undefined

Workflow 2: Category-Based Emoji Assignment

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

Natural Language Commands:
"Assign 🐛 emoji to all debug skills"
"Set ⚡ emoji for create category skills"
"Apply default emojis to all skills in fix category"
Script Execution:
bash
undefined
自然语言命令：
"为所有调试Skill分配🐛表情符号"
"为创建类别Skill设置⚡表情符号"
"为所有修复类别Skill应用默认表情符号"
脚本执行：
bash
undefined

Assign emoji to entire category

为整个类别分配表情符号

python scripts/assign_emoji.py --category debug --emoji "🐛"
python scripts/assign_emoji.py --category debug --emoji "🐛"

System will:

系统会：

1. Find all skills in the category

1. 找出该类别中的所有Skill

2. Check for emoji conflicts

2. 检查表情符号冲突

3. Update all skills in category

3. 更新类别中的所有Skill

4. Handle conflicts with user confirmation

4. 经用户确认后处理冲突

undefined
undefined

Workflow 3: Automatic Emoji Assignment

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

Natural Language Commands:
"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"
Script Execution:
bash
undefined
自然语言命令：
"为所有Skill自动分配默认表情符号"
"为未分配自定义表情符号的Skill应用基于类别的表情符号"
"为我的整个Skill集合设置表情符号默认值"
脚本执行：
bash
undefined

Auto-assign based on categories

基于类别自动分配

python scripts/assign_emoji.py --auto-assign
python scripts/assign_emoji.py --auto-assign

System will:

系统会：

1. Identify skills without emojis

1. 识别未分配表情符号的Skill

2. Apply category default emojis

2. 应用类别默认表情符号

3. Handle conflicts intelligently

3. 智能处理冲突

4. Report assignments and any conflicts

4. 报告分配情况和任何冲突

undefined
undefined

Workflow 4: Emoji Conflict Resolution

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

Natural Language Commands:
"Check for emoji conflicts in my skills"
"Show me which skills have duplicate emojis"
"Suggest alternative emojis for conflicting skills"
Script Execution:
bash
undefined
自然语言命令：
"检查我的Skill是否存在表情符号冲突"
"告诉我哪些Skill使用了重复的表情符号"
"为冲突的Skill建议替代表情符号"
脚本执行：
bash
undefined

List all emoji assignments and conflicts

列出所有表情符号分配和冲突

python scripts/assign_emoji.py --list
python scripts/assign_emoji.py --list

The system will:

系统会：

1. Show all emoji assignments

1. 显示所有表情符号分配

2. Highlight conflicts (multiple skills with same emoji)

2. 突出显示冲突（多个Skill使用相同表情符号）

3. List skills without emojis

3. 列出未分配表情符号的Skill

4. Provide suggestions for resolution

4. 提供解决建议

undefined
undefined

Workflow 5: Emoji Suggestions

工作流5：表情符号建议

Natural Language Commands:
"Suggest emojis for my new skill"
"What emoji would work best for api-integration skill?"
"Recommend emojis based on my skill description"
Script Execution:
bash
undefined
自然语言命令：
"为我的新Skill建议表情符号"
"api-integrationSkill使用什么表情符号最好？"
"根据我的Skill描述推荐表情符号"
脚本执行：
bash
undefined

Get emoji suggestions for a skill

获取Skill的表情符号建议

python scripts/assign_emoji.py --suggest skill-name
python scripts/assign_emoji.py --suggest skill-name

System will:

系统会：

1. Analyze skill name, category, and description

1. 分析Skill名称、类别和描述

2. Suggest relevant emojis based on keywords

2. 根据关键词建议相关表情符号

3. Check for conflicts with existing assignments

3. 检查与现有分配的冲突

4. Provide context for each suggestion

4. 为每个建议提供上下文

undefined
undefined

Emoji Category Defaults

表情符号类别默认值

The system includes built-in emoji defaults for common skill categories:
json
{
  "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类别的内置表情符号默认值：
json
{
  "emoji_defaults": {
    "debug": "🐛",      // 错误修复和故障排除
    "create": "⚡",     // 构建和创建
    "fix": "🔧",        // 维护和修复
    "optimize": "🚀",   // 性能和优化
    "test": "🧪",      // 测试和验证
    "analyze": "📊",    // 分析和报告
    "implement": "🛠️",  // 实现和开发
    "specialized": "⭐", // 专业功能
    "meta": "🎯",       // 元Skill和管理
    "emergency": "🚨",   // 紧急和关键问题
    "default": "⚙️"     // 通用 fallback
  }
}

Folder Name Integration

文件夹名称集成

Use the skill-folder-emoji-updater skill to synchronize folder names with registry assignments:
Natural Language Commands:
"Update all skill folders to match their registry emojis"
"Add 🐛 emoji to all debug skill folders"
"Make sure my skill folders have emoji prefixes"
Script Execution:
bash
undefined
使用skill-folder-emoji-updaterSkill使文件夹名称与注册表分配保持同步：
自然语言命令：
"更新所有Skill文件夹以匹配其注册表表情符号"
"为所有调试Skill文件夹添加🐛表情符号"
"确保我的Skill文件夹有表情符号前缀"
脚本执行：
bash
undefined

Update all folders to match registry

更新所有文件夹以匹配注册表

python ../skill-folder-emoji-updater/scripts/update_folder_emojis.py --all
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
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
undefined
python ../skill-folder-emoji-updater/scripts/update_folder_emojis.py --all --dry-run
undefined

Natural Language Interface

自然语言界面

Emoji Assignment:
  • "Assign 🎨 emoji to ui-design skill"
  • "Give vue-debugging the 🐛 emoji"
  • "Set custom emoji for task-manager"
Category Management:
  • "Apply bug emoji to all debug skills"
  • "Use lightning bolt for create category"
  • "Set default emojis for my skills"
Conflict Resolution:
  • "Check for emoji conflicts"
  • "Show me skills with duplicate emojis"
  • "Fix emoji conflicts automatically"
Folder Integration:
  • "Update skill folders with emojis"
  • "Sync folder names with registry"
  • "Add emoji prefixes to all skill folders"
Discovery and Analysis:
  • "Suggest emoji for my new skill"
  • "List all emoji assignments"
  • "Show which skills need emojis"
表情符号分配：
  • "为ui-designSkill分配🎨表情符号"
  • "为vue-debugging分配🐛表情符号"
  • "为task-manager设置自定义表情符号"
类别管理：
  • "为所有调试Skill应用🐛表情符号"
  • "为创建类别使用⚡表情符号"
  • "为我的Skill设置默认表情符号"
冲突解决：
  • "检查表情符号冲突"
  • "显示使用重复表情符号的Skill"
  • "自动修复表情符号冲突"
文件夹集成：
  • "用表情符号更新Skill文件夹"
  • "同步文件夹名称与注册表"
  • "为所有Skill文件夹添加表情符号前缀"
发现与分析：
  • "为我的新Skill建议表情符号"
  • "列出所有表情符号分配"
  • "显示哪些Skill需要表情符号"

Examples

示例

Example 1: Individual Skill Assignment

示例1：单个Skill分配

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"
用户: "为ui-designSkill分配🎨表情符号"

系统:
✅ 已为Skill: ui-design分配表情符号🎨
✅ 更新了skills.json注册表
✅ 更新了SKILL.md前置元数据
✅ 更新了显示名称: 🎨 UI Design

自然语言使用：
- "🎨 使用ui-designSkill进行组件样式设计"
- "🎨 UI DesignSkill已激活，用于布局修复"

Example 2: Category Assignment

示例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
用户: "为所有调试Skill分配🐛表情符号"

系统:
⚠️ 检测到🐛表情符号冲突：
   - component-debugger（已存在）
   - vue-debugger（已存在）

是否继续？(y/N): y

✅ 已为'debug'类别中的5个Skill分配表情符号🐛
   - api-debugger → 🐛 API Debugger
   - performance-debug → 🐛 Performance Debug
   - state-debugger → 🐛 State Debugger
   - render-debug → 🐛 Render Debug
   - memory-debug → 🐛 Memory Debug

Example 3: Folder Integration

示例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
用户: "更新所有Skill文件夹以匹配其注册表表情符号"

系统:
📋 将重命名8个Skill文件夹：
   🐛 vue-debugging（原: vue-debugging）
   ⚡ task-creator（原: task-creator）
   🔧 pinia-fixer（原: pinia-fixer）
   📊 analytics（原: analytics）
   ...

应用更改？(y/N): y

✅ 已用表情符号更新8个Skill文件夹

Technical Implementation

技术实现

Registry Storage

注册表存储

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

Frontmatter Integration

前置元数据集成

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

Validation Features

验证功能

  • Emoji Validation: Ensures only valid Unicode emojis
  • Conflict Detection: Identifies duplicate emoji assignments
  • Category Consistency: Maintains logical emoji-category relationships
  • Cross-Reference Sync: Keeps registry and SKILL.md aligned
  • 表情符号验证：确保仅使用有效的Unicode表情符号
  • 冲突检测：识别重复的表情符号分配
  • 类别一致性：保持表情符号与类别的逻辑关系
  • 交叉引用同步：保持注册表和SKILL.md一致

Best Practices

最佳实践

Emoji Selection Guidelines

表情符号选择指南

  1. Relevance: Choose emojis that relate to skill purpose
  2. Category Consistency: Use category defaults when possible
  3. Uniqueness: Avoid duplicate emojis within the same category
  4. Clarity: Use well-recognized emojis (🐛, ⚡, 🔧, etc.)
  5. Accessibility: Ensure emojis render correctly across platforms
  1. 相关性：选择与Skill用途相关的表情符号
  2. 类别一致性：尽可能使用类别默认值
  3. 唯一性：避免同一类别中使用重复表情符号
  4. 清晰度：使用广为人知的表情符号（🐛、⚡、🔧等）
  5. 可访问性：确保表情符号在所有平台上都能正确显示

Assignment Workflow

分配工作流

  1. Check existing assignments to avoid conflicts
  2. Consider category defaults first
  3. Test emoji before widespread assignment
  4. Update both registry and frontmatter
  5. Verify skill loading after changes
  1. 检查现有分配以避免冲突
  2. 优先考虑类别默认值
  3. 测试表情符号后再广泛分配
  4. 同时更新注册表和前置元数据
  5. 更改后验证Skill加载

Maintenance Schedule

维护计划

  • Monthly: Review new skills for emoji assignment
  • Quarterly: Check for emoji conflicts and consistency
  • After skill creation: Assign emoji as part of creation process
  • During consolidation: Preserve or update emojis for merged skills
  • 每月：为新Skill分配表情符号
  • 每季度：检查表情符号冲突和一致性
  • Skill创建后：将表情符号分配作为创建流程的一部分
  • 整合期间：为合并后的Skill保留或更新表情符号

Integration with Skill Ecosystem

与Skill生态系统的集成

Works With:
  • skill-creator-doctor: For emoji assignment and management
  • skill-folder-emoji-updater: For folder name synchronization
  • skill consolidation system: Emoji-enhanced reports and displays
  • skills.json registry: Central storage for emoji assignments
Enhanced Features:
  • Visual skill identification during activation
  • Category-based organization through consistent emojis
  • Folder visual organization matching registry
  • Conflict prevention through detection and resolution
兼容工具：
  • skill-creator-doctor：用于表情符号分配和管理
  • skill-folder-emoji-updater：用于文件夹名称同步
  • Skill整合系统：表情符号增强的报告和显示
  • skills.json注册表：表情符号分配的中央存储
增强功能：
  • 激活时的视觉Skill识别
  • 通过一致表情符号实现类别组织
  • 与注册表匹配的文件夹视觉组织
  • 通过检测和解决实现冲突预防

MANDATORY USER VERIFICATION REQUIREMENT

强制用户验证要求

Policy: No Fix Claims Without User Confirmation

政策：无用户确认不得声称修复完成

CRITICAL: Before claiming ANY issue, bug, or problem is "fixed", "resolved", "working", or "complete", the following verification protocol is MANDATORY:
关键：在声称任何问题、错误或故障已“修复”、“解决”、“可用”或“完成”之前，必须遵循以下验证协议：

Step 1: Technical Verification

步骤1：技术验证

  • Run all relevant tests (build, type-check, unit tests)
  • Verify no console errors
  • Take screenshots/evidence of the fix
  • 运行所有相关测试（构建、类型检查、单元测试）
  • 验证控制台无错误
  • 截图/记录修复证据

Step 2: User Verification Request

步骤2：请求用户验证

REQUIRED: Use the 
AskUserQuestion
tool to explicitly ask the user to verify the fix:
"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."
必填：使用
AskUserQuestion
工具明确请求用户验证修复：
"我已完成[修复内容描述]。在标记为完成前，请验证：
1. [要检查的具体内容#1]
2. [要检查的具体内容#2]
3. 这是否解决了你遇到的问题？

请确认修复是否符合预期，或告知我仍存在的问题。"

Step 3: Wait for User Confirmation

步骤3：等待用户确认

  • DO NOT proceed with claims of success until user responds
  • DO NOT mark tasks as "completed" without user confirmation
  • DO NOT use phrases like "fixed", "resolved", "working" without user verification
  • 在用户回复前，不得声称成功
  • 无用户确认，不得将任务标记为“已完成”
  • 无用户验证，不得使用“已修复”、“已解决”、“可用”等表述

Step 4: Handle User Feedback

步骤4：处理用户反馈

  • If user confirms: Document the fix and mark as complete
  • If user reports issues: Continue debugging, repeat verification cycle
  • 如果用户确认：记录修复并标记为完成
  • 如果用户报告问题：继续调试，重复验证周期

Prohibited Actions (Without User Verification)

禁止操作（无用户验证时）

  • Claiming a bug is "fixed"
  • Stating functionality is "working"
  • Marking issues as "resolved"
  • Declaring features as "complete"
  • Any success claims about fixes
  • 声称错误已“修复”
  • 声明功能“可用”
  • 将问题标记为“已解决”
  • 宣布功能“已完成”
  • 任何关于修复的成功声明

Required Evidence Before User Verification Request

请求用户验证前的必填证据

  1. Technical tests passing
  2. Visual confirmation via Playwright/screenshots
  3. Specific test scenarios executed
  4. Clear description of what was changed
Remember: The user is the final authority on whether something is fixed. No exceptions.
  1. 技术测试通过
  2. 通过Playwright/截图提供视觉确认
  3. 执行了特定测试场景
  4. 清晰描述更改内容
请记住：用户是判断问题是否已修复的最终权威。无例外。