本文聚焦两个问题：

• SKILL.md 应该怎么写，结构如何设计。
• 如何写出高质量、可维护、可复用的 Skills。

1. SKILL.md 规范详解

SKILL.md 是一个技能的核心描述文件。它通常由两部分组成：

• YAML Frontmatter：定义技能元信息。
• Markdown 正文：定义执行说明与实践方法。

1.1 Frontmatter 示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

---
# === 必需字段 ===
name: skill-name
# 技能的唯一标识符，建议使用 kebab-case 命名

description: >
  简洁但精确地说明：
  1) 这个技能做什么
  2) 什么时候应该使用它
  3) 核心价值是什么
# 注意：description 通常是智能体选择技能的关键依据，必须写清楚

# === 可选字段 ===
version: 1.0.0
allowed_tools: [tool1, tool2]
required_context: [context_item1]
license: MIT
author: Your Name <email@example.com>
tags: [database, analysis, sql]
---

1.2 正文推荐结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# 技能标题

## 概述
（技能介绍、适用场景、技术背景）

## 前置条件
（运行环境、依赖项、权限要求）

## 工作流程
（分步骤说明：输入、处理、输出）

## 最佳实践
（经验总结、注意事项、常见陷阱）

## 示例
（典型任务示例，便于快速上手）

## 故障排查
（常见问题与解决方案）

2. 编写高质量 Skills 的原则

结合官方文档与社区实践，建议遵循以下四条原则。

2.1 Description 要精准

description 是技能匹配的关键入口，建议做到：

• 明确适用范围，避免“帮助处理数据”这类泛化描述。
• 包含触发关键词，便于匹配用户意图。
• 说明独特价值，和其他技能形成边界。

不佳示例：

1

description: 处理数据库查询

推荐示例：

1
2
3
4

description: >
  将中文业务问题转换为 SQL 查询，并分析 MySQL employees 示例数据库。
  适用于员工信息查询、薪资统计、部门分析、职位变动历史等场景。
  当用户询问员工、薪资、部门相关数据时使用此技能。

2.2 模块化与单一职责

一个 Skill 应聚焦一个明确任务域。若一个 Skill 试图覆盖过多能力，通常会导致：

• Description 变宽，匹配精度下降。
• 指令变长，增加上下文负担。
• 维护和迭代成本上升。

建议将“通用大技能”拆分为多个专用技能，例如：

• mysql-employees-analysis
• sales-data-analysis
• user-behavior-analysis

2.3 确定性优先

对于复杂且要求精确的任务，优先“脚本执行”，不要完全依赖 LLM 文本生成。

例如在数据导出场景，与其让 LLM 直接生成 Excel 二进制内容，不如使用专用脚本处理；SKILL.md 只需说明触发条件与调用方式。

2.4 渐进式披露

将信息按重要性和频率分层，避免无效上下文占用：

• SKILL.md 主体：核心工作流与常用模式
• 附加文档（如 advanced.md）：高级用法与边缘场景
• 数据文件：大型参考数据，通过脚本按需读取

总结

高质量 Skills 的目标不是“写得多”，而是“边界清晰、触发准确、执行稳定、可持续维护”。

从规范化 SKILL.md 开始，再结合单一职责与渐进式披露，你就能构建出更高效的技能体系。