企业官网建设流程全解析

一、痛点引入：打开 SKILL.md 一脸懵

你下载了一个 Skill，打开 SKILL.md 一看：

---name:code-reviewdescription:自动审查代码质量version:1.0.0---# Code Review Skill...

这些字段到底是什么意思？哪些是必填的？哪些是可选的？写错了会怎样？description写"一个工具"行不行？

这一篇，我们把SKILL.md逐字段拆解，让你彻底读懂这个文件的每一个部分。

二、SKILL.md 的整体结构

三、Frontmatter 字段详解

3.1name（必填）

作用：Skill 的唯一标识符，用于引用、索引和目录命名。

格式要求：

• 只能包含：小写字母、数字、连字符（-）
• 不能以数字开头
• 不能包含空格或特殊字符
• 长度：3-50 个字符

# ✅ 正确的 namename:code-reviewname:excel-analyzername:my-custom-skillname:skill-v2# ❌ 错误的 namename:Code Review# 包含空格name:code_review# 包含下划线name:123-skill# 以数字开头name:skill!# 包含特殊字符

命名建议：

格式：{功能}-{对象} 示例： - code-review → 代码审查 - excel-analyzer → Excel 分析 - pdf-generator → PDF 生成 - git-commit → Git 提交

3.2description（必填）

作用：一行描述，用于渐进式加载时的语义匹配。这是 SKILL.md 中最重要的字段。

为什么最重要：

AI 在启动时只读取name+description，通过语义匹配决定加载哪个 Skill。如果description写得不好，AI 就无法正确匹配你的 Skill。

好的 description vs 差的 description：

# ❌ 差的描述description:一个很有用的工具description:处理文件description:我的第一个 Skill# ✅ 好的描述description:处理 Excel/CSV 文件，进行数据分析和可视化description:自动审查代码质量、安全性和性能description:生成符合 Conventional Commits 规范的 Git 提交信息

description 编写公式：

{动作} + {对象} + {核心能力} 示例： - 处理 Excel 文件 + 数据分析和可视化 - 自动审查代码 + 质量、安全性、性能 - 生成 Git 提交信息 + 符合 Conventional Commits 规范

3.3version（可选）

作用：Skill 的版本号，用于版本管理和更新。

格式：遵循语义化版本（SemVer）

主版本.次版本.修订号 1.0.0 主版本：不兼容的 API 变更 次版本：向下兼容的功能新增 修订号：向下兼容的问题修正

示例：

version:1.0.0# 初始版本version:1.1.0# 新增功能version:1.1.1# 修复 Bugversion:2.0.0# 重大重构

3.4author（可选）

作用：Skill 的作者信息。

author:your-nameauthor:your-teamauthor:"Your Company, Inc."

3.5tags（可选）

作用：分类标签，帮助 Skill 在平台上被发现。

tags:[code-review,security,quality]tags:[excel,data,analysis,visualization]tags:[pdf,document,generation]

标签建议：

• 数量：3-5 个
• 格式：小写，连字符分隔
• 内容：功能关键词 + 领域关键词

四、正文部分详解

4.1 使用时机（强烈建议）

作用：告诉 AI 在什么场景下应该使用这个 Skill。

## 使用时机 当用户提交代码变更、创建 Pull Request 或明确请求代码审查时使用此 Skill。 当用户说以下关键词时触发： - "审查代码" - "review" - "检查代码质量" - "代码有什么问题"

为什么重要：这是渐进式加载的第二道匹配。即使 description 匹配上了，AI 还会检查"使用时机"来确认是否真的应该使用这个 Skill。

4.2 能力列表（强烈建议）

作用：列出 Skill 的核心能力，让用户快速了解它能做什么。

## 能力 - **安全审查**：检测 SQL 注入、XSS、CSRF、密钥泄露等安全漏洞 - **性能审查**：识别 N+1 查询、内存泄漏、阻塞操作等性能问题 - **质量审查**：检查函数长度、嵌套深度、命名规范、代码重复 - **最佳实践**：对照语言和框架的最佳实践进行检查

4.3 详细指令（核心部分）

作用：这是 Skill 的核心——详细描述 AI 应该怎么执行任务。

编写原则：

指令结构示例：

## 指令 ### 步骤 1：获取代码变更 使用以下命令获取最近的代码变更： ```bash git diff HEAD~1

如果是单个文件，直接读取文件内容。

步骤 2：安全检查

按照以下规则逐项检查：

步骤 3：生成报告

按以下格式输出审查报告：

# 代码审查报告 ## 概览 - 审查文件：X 个 - 发现问题：Y 个

### 4.4 工具依赖（按需） **作用**：列出 Skill 依赖的外部工具、库或 API。 ```markdown ## 工具 - Python 3.8+ - pandas >= 1.5.0 - Git - grep 或 ripgrep

4.5 示例（强烈建议）

作用：提供具体的使用示例，帮助 AI 理解预期行为。

## 示例 ### 输入 ```python def get_user(user_id): query = f"SELECT * FROM users WHERE id = {user_id}" return db.execute(query)

输出

🔴 安全风险：SQL 注入 - 文件：app.py:15 - 问题：使用 f-string 构建 SQL 查询 - 修复：使用参数化查询

### 4.6 注意事项（建议） **作用**：边界条件、安全提醒、常见错误。 ```markdown ## 注意事项 - 审查结果仅供参考，安全相关问题必须人工确认 - 不要自动修改用户的代码，只提供建议 - 敏感代码（密钥、密码）不要输出到报告中 - 大型 PR（>500 行）建议分批审查

五、完整示例

---name:csv-cleanerdescription:清洗和规范化 CSV 数据文件，处理缺失值、去重、格式标准化version:1.2.0author:data-teamtags:[csv,data,cleaning,etl,preprocessing]---# CSV Cleaner Skill## 使用时机当用户提供 CSV 文件并需要数据清洗、去重、格式规范化时使用。 触发关键词："清洗数据"、"clean CSV"、"处理缺失值"、"数据预处理"。## 能力-**编码检测**：自动检测并修复编码问题（UTF-8、GBK、ISO-8859-1）-**去重处理**：基于全列或指定列去除重复行-**缺失值处理**：支持删除、填充（均值/中位数/众数/自定义值）-**格式标准化**：统一日期格式、数字格式、字符串格式-**异常值检测**：基于IQR 或 Z-score 检测异常值-**变更报告**：生成详细的清洗变更记录## 工具-Python 3.8+-pandas>= 1.5.0-chardet>= 4.0（编码检测）-numpy>= 1.21（数值计算）## 指令### 步骤 1：读取并检测编码```python import chardet import pandas as pd# 检测编码with open(file_path,'rb') as f:raw = f.read() encoding = chardet.detect(raw)['encoding']# 读取文件df = pd.read_csv(file_path,encoding=encoding)

步骤 2：统计基本信息

info={"行数":len(df),"列数":len(df.columns),"缺失值":df.isnull().sum().to_dict(),"重复行":df.duplicated().sum(),"数据类型":df.dtypes.to_dict()}

步骤 3：执行清洗

根据用户选择执行清洗操作：

• 去重：df.drop_duplicates()
• 填充缺失值：df.fillna(method='ffill')或df.fillna(df.mean())
• 格式标准化：pd.to_datetime(df['date'])

步骤 4：生成变更报告

# 数据清洗报告 ## 原始数据 - 行数：10,000 - 列数：8 - 缺失值：234 个 - 重复行：15 行 ## 清洗操作 1. 删除重复行：15 行 → 9,985 行 2. 填充缺失值：234 个 → 0 个 3. 日期格式标准化：2026/3/17 → 2026-03-17 ## 清洗后数据 - 行数：9,985 - 列数：8 - 缺失值：0 个

示例

输入

name,date,amount 张三,2026/3/1,100 李四,2026/3/2, 张三,2026/3/1,100 王五,2026-3-3,200

输出

name,date,amount 张三,2026-03-01,100 李四,2026-03-02,0 王五,2026-03-03,200

注意事项

• 大文件（>500MB）使用分块处理：pd.read_csv(file, chunksize=10000)
• 清洗前自动备份原文件
• 变更报告必须记录所有修改，便于用户审计
• 敏感数据列（身份证、手机号）需标记为脱敏处理
• 日期格式推断可能不准确，需要用户确认

六、常见错误清单

七、最佳实践

1. description 是生命线：花 50% 的时间打磨这一行描述
2. 指令要具体：不要写"处理数据"，要写"用 pandas 读取 CSV，检测缺失值，用均值填充"
3. 提供示例：一个好示例胜过十段描述
4. 标注边界：明确说明 Skill 不能做什么
5. 保持更新：随着使用反馈迭代优化
6. 测试验证：写完后实际测试，确保 AI 能正确理解和执行

八、总结

SKILL.md的设计哲学是极简而完整——一个文件包含了元数据、指令、工具、示例和注意事项。理解了这个结构，你就掌握了 Skill 开发的基础。

记住：好的 SKILL.md = 好的 description + 具体的指令 + 清晰的示例。

下一篇预告：SK-05 将揭秘 Skill 的"渐进式加载"原理——为什么装 100 个 Skill 也不会爆上下文。我们会深入到代码层面，看看 AI 是如何实现"只加载需要的"这个精妙设计的。

本系列覆盖AI 大模型基础、Agent 开发、MCP 协议、Skill 开发、RAG、模型微调、部署推理七大方向，从入门到实战的全栈内容持续更新中。

所有文章的 Markdown 源文件、可运行代码、高清配图已整理成完整资料包。

👍 点赞 + ⭐ 关注，评论区扣「1」，挨个发你领取方式 👇