第 51 章
Plugin 打包 MCP Server：安装即启动的实现方式与 userConfig 动态配置
第五十一章：Skill 文件格式：Markdown 驱动的行为定义与参数声明
51.1 Skill 的本质：自然语言即代码
在传统软件开发中，"行为"总是通过代码来定义。但 Claude 的 Skill 系统颠覆了这一假设：一个 .md 文件，配合恰当的 YAML frontmatter，就能定义出 Claude 的一套完整行为模式。
为什么自然语言能作为"代码"？根本原因在于 Claude 是一个语言模型，对自然语言的理解和遵循能力远超对传统编程语言的执行能力。一个精心撰写的 Skill 文件，能以极低的成本传达复杂的行为约束，而不需要开发者学习特定的 DSL 或 API。
这并不意味着 Skill 是随意的文档。恰恰相反，Skill 文件有严格的格式规范，每个字段都有明确的语义和作用。理解这些规范是写出高质量 Skill 的前提。
51.2 Skill 文件的完整结构
一个完整的 Skill 文件由两个部分组成：
- YAML frontmatter：机器可读的元数据，用
---包裹 - Markdown 正文：人类可读的行为描述
---
# YAML frontmatter（机器可读）
name: skill-identifier
version: 1.0.0
description: 一句话说明这个 Skill 做什么
# ... 更多字段 ...
---
## Markdown 正文（自然语言行为描述）
### 触发条件
...
### 执行步骤
...
51.3 YAML Frontmatter 字段全解
必填字段
name
Skill 的唯一标识符。用于在 Plugin 中引用、在市场中搜索、在代码中调用。
name: sql-query-builder
命名规范：
- 只能包含小写字母、数字、连字符
- 不能以连字符开头或结尾
- 长度 3-64 个字符
- 在同一个 Plugin 中必须唯一
version
遵循 Semantic Versioning 规范的版本号。
version: 2.1.0
版本号的含义：
主版本号：不兼容的 API 变更（修改了 required 参数）次版本号：向下兼容的功能新增（增加了 optional 参数）修订号：向下兼容的问题修正（改善了说明文字）
description
一句话描述。这是用户在市场中看到的第一行文字，应当准确、具体、不超过 120 个字符。
description: Generate optimized SQL queries from natural language descriptions, supporting PostgreSQL and MySQL dialects
参数声明：parameters
parameters 字段是 Skill 与外部世界的接口定义。它告诉 Claude 这个 Skill 接受哪些输入，每个输入的类型和约束是什么。
parameters:
- name: query_description
type: string
description: Natural language description of the data you want to retrieve
required: true
- name: dialect
type: string
description: SQL dialect to use
required: false
default: postgresql
enum:
- postgresql
- mysql
- sqlite
- mssql
- name: max_rows
type: number
description: Maximum number of rows to return
required: false
default: 100
minimum: 1
maximum: 10000
- name: include_explanation
type: boolean
description: Whether to include a plain-language explanation of the generated SQL
required: false
default: true
- name: tables
type: array
description: List of table names to consider (if known)
required: false
items:
type: string
参数类型系统
Skill 支持以下参数类型：
| 类型 | 说明 | 支持的约束字段 |
|---|---|---|
string |
字符串 | enum, minLength, maxLength, pattern |
number |
数值（整数或浮点数） | minimum, maximum, multipleOf |
integer |
整数 | minimum, maximum, multipleOf |
boolean |
布尔值 | 无额外约束 |
array |
数组 | items, minItems, maxItems |
object |
对象 | properties, required |
嵌套对象参数示例
parameters:
- name: filter
type: object
description: Filter conditions for the query
required: false
properties:
date_range:
type: object
properties:
start:
type: string
description: Start date (ISO 8601 format)
end:
type: string
description: End date (ISO 8601 format)
status:
type: array
items:
type: string
enum: [active, inactive, pending]
元数据字段
author
Skill 的作者信息。在市场中显示，用于归因和联系。
author: Jane Doe <[email protected]>
tags
用于市场搜索的标签列表。建议使用 3-8 个标签，涵盖功能类别、适用领域、技术栈。
tags:
- database
- sql
- query-builder
- postgresql
- developer-tools
license
Skill 的许可证。开源 Skill 建议使用 MIT 或 Apache-2.0；专有 Skill 填写 Proprietary。
license: MIT
homepage
Skill 的主页 URL，通常是 GitHub 仓库或文档页面。
homepage: https://github.com/yourname/sql-query-builder-skill
依赖声明
requires_tools
声明这个 Skill 需要哪些 MCP 工具才能运行。如果对应工具不可用，Claude 会提前告知用户而不是在执行到一半时才报错。
requires_tools:
- execute_sql
- list_tables
- describe_table
requires_plugins
声明这个 Skill 依赖哪些 Plugin（通过 Plugin 名称引用）。
requires_plugins:
- database-plugin@^2.0.0
claude_version
声明这个 Skill 所需的最低 Claude 模型版本。某些 Skill 使用了较新模型才支持的能力。
claude_version: ">=claude-3-5-sonnet"
行为控制字段
max_turns
限制执行这个 Skill 时允许的最大对话轮次（工具调用次数）。防止 Skill 在复杂场景中无限循环。
max_turns: 10
timeout_seconds
单次 Skill 执行的超时时间（秒）。超时后 Claude 会中止执行并返回部分结果。
timeout_seconds: 60
confirmation_required
是否在执行前请求用户确认。适用于会产生不可撤销操作的 Skill（如发送邮件、提交代码）。
confirmation_required: true
confirmation_message: "This will send an email to {recipient}. Proceed?"
output_format
建议 Claude 使用的输出格式。
output_format: markdown # markdown | plain | json | code
51.4 Markdown 正文的结构规范
Markdown 正文是 Skill 的"行为说明书"，Claude 会将其作为执行指引。正文的质量直接决定了 Skill 的执行质量。
推荐章节结构
## 使用场景（What & When）
描述这个 Skill 解决什么问题、在什么情况下应该被激活。
## 前置条件（Prerequisites）
描述使用这个 Skill 前需要满足的条件，例如需要连接数据库、需要特定格式的输入。
## 执行步骤（How）
分步骤描述 Claude 应当如何执行这个 Skill，包括：
- 收集哪些信息
- 调用哪些工具（按什么顺序）
- 如何处理工具返回值
## 输出规范（Output）
描述输出的格式、内容和质量标准。
## 边界情况（Edge Cases）
描述常见的异常情况和处理方式。
## 示例（Examples）
提供输入-输出的具体示例。
编写高质量行为描述的原则
原则一：具体而非模糊
# 差：
根据用户需求生成 SQL。
# 好：
1. 首先调用 `list_tables` 获取所有表名
2. 对用户描述中提到的实体，调用 `describe_table` 获取字段定义
3. 基于表结构和用户需求生成 SQL，优先使用 JOIN 而非子查询
4. 验证生成的 SQL 没有笛卡尔积风险（未加 WHERE 条件的多表 JOIN）
原则二：定义成功标准
## 质量标准
生成的 SQL 必须满足以下条件：
- 语法正确，能在目标数据库版本（PostgreSQL 14+）上执行
- 使用适当的索引友好写法（避免 `SELECT *`，用具体字段名）
- 对于分页查询，使用 LIMIT/OFFSET 或 keyset pagination
- 所有字符串比较使用大小写不敏感方式（ILIKE 或 LOWER()）
原则三：明确工具调用时机
## 工具调用策略
- 在生成 SQL 之前，**必须**先调用 `list_tables` 了解可用的表
- 只为查询中涉及的表调用 `describe_table`，不要一次性拉取所有表的结构
- 生成 SQL 后，调用 `explain_query` 检查执行计划，确认没有全表扫描
原则四：错误处理
## 错误处理
| 情况 | 处理方式 |
|------|----------|
| 描述中的实体找不到对应表 | 列出最相似的表名，询问用户确认 |
| 生成的 SQL 执行报错 | 分析错误信息，自动修正并重试（最多 3 次） |
| 用户描述歧义 | 列出可能的理解方式，请用户选择 |
| 超出 max_rows 限制 | 自动添加 LIMIT 子句，告知用户结果已截断 |
51.5 完整 Skill 文件示例
下面是一个生产级别的 SQL 查询构建器 Skill 的完整文件：
---
name: sql-query-builder
version: 2.0.0
description: Generate optimized SQL queries from natural language descriptions with schema awareness
author: Jane Doe <[email protected]>
license: MIT
tags:
- database
- sql
- developer-tools
- postgresql
- mysql
parameters:
- name: description
type: string
description: Natural language description of the data you want to retrieve
required: true
minLength: 10
maxLength: 2000
- name: dialect
type: string
description: SQL dialect
required: false
default: postgresql
enum: [postgresql, mysql, sqlite, mssql]
- name: max_rows
type: number
description: Maximum rows to return
required: false
default: 100
minimum: 1
maximum: 50000
requires_tools:
- list_tables
- describe_table
- execute_sql
max_turns: 15
timeout_seconds: 120
output_format: markdown
---
## 使用场景
当用户需要从数据库中查询数据，但不熟悉数据库的表结构或 SQL 语法时，使用此 Skill。
适用于：
- 数据分析师需要快速查询数据
- 后端开发者需要验证查询逻辑
- 运营团队需要临时数据报表
## 执行步骤
### 第一步：理解需求
仔细阅读用户的 `description`，识别：
1. 需要查询哪些实体（用户、订单、产品等）
2. 需要哪些条件过滤（时间范围、状态、用户属性等）
3. 需要哪些聚合操作（计数、求和、平均值等）
4. 需要如何排序和分页
如果需求不清晰，先提问澄清，不要猜测。
### 第二步：了解数据库结构
1. 调用 `list_tables` 获取所有表名
2. 根据需求分析，识别可能相关的表（1-5 个）
3. 对每个相关表调用 `describe_table` 获取字段定义
4. 分析外键关系，确定 JOIN 路径
### 第三步：生成 SQL
基于需求和表结构生成 SQL。遵循以下规范：
**查询质量规范：**
- 明确列出 SELECT 的字段，不使用 `SELECT *`
- 多表 JOIN 必须有明确的 ON 条件
- 添加适当的 WHERE 条件防止全表扫描
- 对大结果集使用 LIMIT（不超过 `max_rows`）
**{{dialect}} 特定规范：**
- postgresql：字符串使用 ILIKE 进行大小写不敏感比较
- mysql：注意 `=` 默认大小写不敏感，日期函数使用 DATE_FORMAT
- sqlite：不支持 FULL OUTER JOIN，用 UNION 替代
### 第四步：验证与解释
1. 检查 SQL 的语法正确性
2. 如果设置了 `include_explanation: true`，用中文解释 SQL 的逻辑
3. 提示用户注意潜在的性能问题（如缺少索引的字段过滤）
## 输出格式
```sql
-- 生成的 SQL
SELECT
u.id,
u.email,
COUNT(o.id) AS order_count
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
WHERE u.created_at >= '2024-01-01'
GROUP BY u.id, u.email
ORDER BY order_count DESC
LIMIT 100;
解释：（可选，根据 include_explanation 参数决定）
此查询从 users 表关联 orders 表，统计 2024 年以来注册的每位用户的订单数量，
按订单数量降序排列，返回前 100 条记录。
边界情况
- 表不存在：列出最相似的表名（使用编辑距离算法思维），询问用户是否指这些表
- 字段名模糊：当多个表有同名字段时，明确使用表名.字段名前缀
- 复杂聚合：超过 3 层嵌套子查询时，考虑使用 CTE（WITH 子句）提升可读性
- 权限限制：某些表可能有行级安全策略，在注释中提醒用户
## 51.6 Skill 文件的版本管理
### 版本演进策略
```yaml
# v1.0.0：初始版本
parameters:
- name: description
type: string
required: true
# v1.1.0：新增可选参数（向下兼容）
parameters:
- name: description
type: string
required: true
- name: dialect # 新增，有默认值，不影响现有用户
type: string
required: false
default: postgresql
# v2.0.0：修改必填参数（破坏性变更，升级主版本号）
parameters:
- name: description
type: string
required: true
minLength: 10 # 新增约束，可能导致之前能运行的查询失败
Changelog 格式
在 Skill 文件末尾维护一个 changelog 部分（对用户可见）：
## Changelog
### 2.0.0 (2026-03-15)
**Breaking**: Added minimum length requirement (10 chars) to `description` parameter.
- Added `dialect` parameter for database-specific SQL generation
- Improved JOIN detection for complex multi-table queries
### 1.1.0 (2026-02-01)
- Added `include_explanation` parameter
- Better handling of aggregate functions
### 1.0.0 (2026-01-15)
- Initial release
51.7 Skill 文件的测试
虽然 Skill 不包含可执行代码，但仍需测试。Claude Code 提供了 Skill 测试工具：
# 测试 Skill 的 frontmatter 语法
claude-plugin skill validate ./skills/sql-query-builder.md
# 用给定参数模拟 Skill 执行（不实际调用工具）
claude-plugin skill test ./skills/sql-query-builder.md \
--param description="查询所有2024年以来注册的用户" \
--param dialect=postgresql \
--dry-run
# 完整端到端测试（需要已安装的 MCP 工具）
claude-plugin skill test ./skills/sql-query-builder.md \
--param description="查询所有2024年以来注册的用户"
51.8 多语言 Skill 支持
一个 Skill 可以提供多语言版本的正文，Claude 会根据用户的语言偏好选择对应版本：
skills/
├── sql-query-builder.md ← 默认版本（英文）
├── sql-query-builder.zh.md ← 中文版本
└── sql-query-builder.ja.md ← 日文版本
在 plugin.json 中声明多语言支持：
{
"skills": [
{
"default": "./skills/sql-query-builder.md",
"zh": "./skills/sql-query-builder.zh.md",
"ja": "./skills/sql-query-builder.ja.md"
}
]
}
小结
Skill 文件是 Claude 行为的自然语言规范。YAML frontmatter 提供机器可读的元数据（名称、版本、参数类型约束、依赖声明、执行控制），Markdown 正文提供人类可读的行为指导（使用场景、执行步骤、错误处理、输出规范）。高质量的 Skill 文件的关键在于具体、明确、有约束——"模糊指令"是低质量 Skill 的最主要特征。下一章将介绍如何将 Skill 和 Plugin 发布到 clawhub.ai 市场。