阅读提示：本章节将深入 Skill 开发的每个技术细节。如果你需要构建生产级 Skill，这是你的完整参考手册。

2.1 SKILL.md 深度解析

SKILL.md 是 Skill 的核心入口，它由两部分组成：

1. YAML Frontmatter：元数据配置（机器可读）
2. Markdown Body：指令内容（Claude 可执行）

YAML Frontmatter 全字段详解

字段详解

name（标识符）

name: code-review

• 类型：字符串
• 约束：
  • 最大 64 字符
  • 仅限小写字母、数字、连字符
  • 不能包含 XML 标签
  • 不能使用保留词：anthropic、claude
• 影响：
  • 成为 /slash-command 的名称
  • Plugin 中的 Skill 会添加命名空间前缀：plugin-name:skill-name

description（描述）

description: |
  分析代码质量、发现潜在问题、提供改进建议。
  当用户请求代码审查、质量检查、或提到 "review" 时自动激活。

• 类型：字符串
• 约束：
  • 必须非空
  • 最大 1024 字符
  • 不能包含 XML 标签
• 关键作用：
  • 这是 Claude 决定是否激活 Skill 的唯一依据
  • 应该包含"做什么"和"何时使用"
  • 使用用户自然会说的关键词

最佳实践：

# ✅ 好的 description
description: |
  生成符合团队规范的 Git 提交信息。
  当用户请求提交代码、生成 commit message、或提到 "commit" 时使用。

# ❌ 差的 description
description: "处理 Git 相关任务"  # 太模糊，可能过度触发

user-invocable（用户可调用）

user-invocable: false

• 类型：布尔值
• 默认值：true
• 作用：控制是否在 / 菜单中显示

使用场景：