Frontmatter 配置详解
SKILL.md 的 YAML Frontmatter 定义了 Skill 的元数据和行为。
完整参考
yaml
---
name: python-docstring # 必需：kebab-case 名称
description: | # 必需：用于触发匹配的描述
Generate Google-style Python docstrings for functions and classes.
Triggered when user asks to add documentation to Python code.
metadata:
type: workflow # Skill 分类
version: "1.2.0" # 语义化版本
author: team-backend # 作者标识
triggers: # 额外触发关键词
- "add docstring"
- "document this function"
- "generate docs"
allowed-tools: # 工具白名单
- Read
- Write
- Edit
---字段说明
name（必需）
- 格式：
kebab-case，全小写，连字符分隔 - 全局唯一标识符
- 例子：
python-docstring、security-audit、db-migration-helper
yaml
# 好
name: user-auth-helper
# 不好
name: UserAuthHelper # 不是 kebab-case
name: auth # 太泛，可能冲突description（必需）
这是最重要的字段 — 它直接影响 Skill 的触发准确率。
- 长度：1-3 句话
- 内容：描述 Skill 做什么、何时触发
- 包含自然语言触发词
- 避免与已有 Skill 的描述过于相似
yaml
# 好 — 具体明确
description: |
Generate Google-style docstrings for Python functions.
Triggers on "add docstring", "document this function".
# 不好 — 太模糊
description: |
Helps with documentation.triggers（可选）
额外的触发词列表。Skill 也可以通过 /name 直接触发。
yaml
triggers:
- "add docstring"
- "document this"
- "generate docs for"
- "add python docs"触发词设计原则：
- 2-5 个自然语言短语
- 包含常见变体
- 避免过于通用的词（如「帮我」）
- 测试是否与其他 Skill 冲突
allowed-tools（可选）
限制 Skill 可以使用的工具列表。安全最佳实践。
yaml
# 只读 Skill
allowed-tools:
- Read
# 代码生成 Skill
allowed-tools:
- Read
- Write
- Edit
- Bash
# 不限制（默认）
# 不写 allowed-tools 字段metadata（可选）
yaml
metadata:
type: workflow # workflow | tool | reference
version: "1.0.0"
author: your-team
tags:
- python
- documentation常见配置组合
只读分析 Skill
yaml
name: code-metrics
description: Analyze code complexity and generate metrics report
allowed-tools: [Read, Bash]写操作 Skill
yaml
name: db-migration
description: Create and validate database migration files
allowed-tools: [Read, Write, Edit, Bash]交互式 Skill
yaml
name: onboarding-wizard
description: Interactive onboarding guide for new team members
# 不限制工具