一、痛点引入打开 SKILL.md 一脸懵你下载了一个 Skill打开 SKILL.md 一看---name:code-reviewdescription:自动审查代码质量version:1.0.0---# Code Review Skill...这些字段到底是什么意思哪些是必填的哪些是可选的写错了会怎样description写一个工具行不行这一篇我们把SKILL.md逐字段拆解让你彻底读懂这个文件的每一个部分。二、SKILL.md 的整体结构正文内容Frontmatter 内容SKILL.md 文件---YAML Frontmatter元数据区---Markdown 正文指令区name (必填)description (必填)version (可选)author (可选)tags (可选)使用时机能力列表详细指令工具依赖示例注意事项三、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 中最重要的字段。为什么最重要Skill 索引AI Agent用户任务Skill 索引AI Agent用户任务帮我处理这个 Excel 文件语义匹配 descriptionexcel-analyzer (0.95)csv-cleaner (0.82)y1="263" x2="339" y2="263" stroke-width="2" stroke="none" marker-end="url(#arrowhead)" style="stroke-dasharray: 3, 3; fill: none;">选择最匹配的 Skill加载完整 SKILL.mdAI 在启动时只读取namedescription通过语义匹配决定加载哪个 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、密钥泄露等安全漏洞 - **性能审查**识别 N1 查询、内存泄漏、阻塞操作等性能问题 - **质量审查**检查函数长度、嵌套深度、命名规范、代码重复 - **最佳实践**对照语言和框架的最佳实践进行检查4.3 详细指令核心部分作用这是 Skill 的核心——详细描述 AI 应该怎么执行任务。编写原则好的指令具体可执行有顺序有示例❌ 处理数据✅ 用 pandas 读取 CSV❌ 分析一下✅ 执行 git diff HEAD~1❌ 随意执行✅ 1. 先做这个 2. 再做那个❌ 只有文字✅ 附带代码示例指令结构示例## 指令 ### 步骤 1获取代码变更 使用以下命令获取最近的代码变更 bash git diff HEAD~1如果是单个文件直接读取文件内容。步骤 2安全检查按照以下规则逐项检查检查项模式风险等级SQL 注入fSELECT.*{ 高XSSinnerHTML 高密钥泄露api_key 高步骤 3生成报告按以下格式输出审查报告# 代码审查报告 ## 概览 - 审查文件X 个 - 发现问题Y 个### 4.4 工具依赖按需 **作用**列出 Skill 依赖的外部工具、库或 API。 markdown ## 工具 - Python 3.8 - pandas 1.5.0 - Git - grep 或 ripgrep4.5 示例强烈建议作用提供具体的使用示例帮助 AI 理解预期行为。## 示例 ### 输入 python def get_user(user_id): query fSELECT * FROM users WHERE id {user_id} return db.execute(query)输出 安全风险SQL 注入 - 文件app.py:15 - 问题使用 f-string 构建 SQL 查询 - 修复使用参数化查询### 4.6 注意事项建议 **作用**边界条件、安全提醒、常见错误。 markdown ## 注意事项 - 审查结果仅供参考安全相关问题必须人工确认 - 不要自动修改用户的代码只提供建议 - 敏感代码密钥、密码不要输出到报告中 - 大型 PR500 行建议分批审查五、完整示例---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,encodingencoding)步骤 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(methodffill)或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, chunksize10000)清洗前自动备份原文件变更报告必须记录所有修改便于用户审计敏感数据列身份证、手机号需标记为脱敏处理日期格式推断可能不准确需要用户确认六、常见错误清单错误后果修正方法缺少nameSkill 无法被索引添加唯一标识符name包含大写目录名不一致改为全小写description太模糊AI 无法正确匹配写清楚具体能力缺少---分隔符Frontmatter 解析失败添加---Tab 缩进YAML 解析错误改为空格缩进指令太笼统AI 执行结果不稳定细化每一步缺少示例AI 不理解预期行为添加输入/输出示例缺少注意事项边界情况处理不当添加限制条件七、最佳实践description 是生命线花 50% 的时间打磨这一行描述指令要具体不要写处理数据要写用 pandas 读取 CSV检测缺失值用均值填充提供示例一个好示例胜过十段描述标注边界明确说明 Skill 不能做什么保持更新随着使用反馈迭代优化测试验证写完后实际测试确保 AI 能正确理解和执行八、总结SKILL.md的设计哲学是极简而完整——一个文件包含了元数据、指令、工具、示例和注意事项。理解了这个结构你就掌握了 Skill 开发的基础。记住好的 SKILL.md 好的 description 具体的指令 清晰的示例。下一篇预告SK-05 将揭秘 Skill 的渐进式加载原理——为什么装 100 个 Skill 也不会爆上下文。我们会深入到代码层面看看 AI 是如何实现只加载需要的这个精妙设计的。本系列覆盖AI 大模型基础、Agent 开发、MCP 协议、Skill 开发、RAG、模型微调、部署推理七大方向从入门到实战的全栈内容持续更新中。所有文章的 Markdown 源文件、可运行代码、高清配图已整理成完整资料包。 点赞 ⭐ 关注评论区扣「1」挨个发你领取方式
一、痛点引入打开 SKILL.md 一脸懵你下载了一个 Skill打开 SKILL.md 一看---name:code-reviewdescription:自动审查代码质量version:1.0.0---# Code Review Skill...这些字段到底是什么意思哪些是必填的哪些是可选的写错了会怎样description写一个工具行不行这一篇我们把SKILL.md逐字段拆解让你彻底读懂这个文件的每一个部分。二、SKILL.md 的整体结构正文内容Frontmatter 内容SKILL.md 文件---YAML Frontmatter元数据区---Markdown 正文指令区name (必填)description (必填)version (可选)author (可选)tags (可选)使用时机能力列表详细指令工具依赖示例注意事项三、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 中最重要的字段。为什么最重要Skill 索引AI Agent用户任务Skill 索引AI Agent用户任务帮我处理这个 Excel 文件语义匹配 descriptionexcel-analyzer (0.95)csv-cleaner (0.82)y1="263" x2="339" y2="263" stroke-width="2" stroke="none" marker-end="url(#arrowhead)" style="stroke-dasharray: 3, 3; fill: none;">选择最匹配的 Skill加载完整 SKILL.mdAI 在启动时只读取namedescription通过语义匹配决定加载哪个 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、密钥泄露等安全漏洞 - **性能审查**识别 N1 查询、内存泄漏、阻塞操作等性能问题 - **质量审查**检查函数长度、嵌套深度、命名规范、代码重复 - **最佳实践**对照语言和框架的最佳实践进行检查4.3 详细指令核心部分作用这是 Skill 的核心——详细描述 AI 应该怎么执行任务。编写原则好的指令具体可执行有顺序有示例❌ 处理数据✅ 用 pandas 读取 CSV❌ 分析一下✅ 执行 git diff HEAD~1❌ 随意执行✅ 1. 先做这个 2. 再做那个❌ 只有文字✅ 附带代码示例指令结构示例## 指令 ### 步骤 1获取代码变更 使用以下命令获取最近的代码变更 bash git diff HEAD~1如果是单个文件直接读取文件内容。步骤 2安全检查按照以下规则逐项检查检查项模式风险等级SQL 注入fSELECT.*{ 高XSSinnerHTML 高密钥泄露api_key 高步骤 3生成报告按以下格式输出审查报告# 代码审查报告 ## 概览 - 审查文件X 个 - 发现问题Y 个### 4.4 工具依赖按需 **作用**列出 Skill 依赖的外部工具、库或 API。 markdown ## 工具 - Python 3.8 - pandas 1.5.0 - Git - grep 或 ripgrep4.5 示例强烈建议作用提供具体的使用示例帮助 AI 理解预期行为。## 示例 ### 输入 python def get_user(user_id): query fSELECT * FROM users WHERE id {user_id} return db.execute(query)输出 安全风险SQL 注入 - 文件app.py:15 - 问题使用 f-string 构建 SQL 查询 - 修复使用参数化查询### 4.6 注意事项建议 **作用**边界条件、安全提醒、常见错误。 markdown ## 注意事项 - 审查结果仅供参考安全相关问题必须人工确认 - 不要自动修改用户的代码只提供建议 - 敏感代码密钥、密码不要输出到报告中 - 大型 PR500 行建议分批审查五、完整示例---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,encodingencoding)步骤 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(methodffill)或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, chunksize10000)清洗前自动备份原文件变更报告必须记录所有修改便于用户审计敏感数据列身份证、手机号需标记为脱敏处理日期格式推断可能不准确需要用户确认六、常见错误清单错误后果修正方法缺少nameSkill 无法被索引添加唯一标识符name包含大写目录名不一致改为全小写description太模糊AI 无法正确匹配写清楚具体能力缺少---分隔符Frontmatter 解析失败添加---Tab 缩进YAML 解析错误改为空格缩进指令太笼统AI 执行结果不稳定细化每一步缺少示例AI 不理解预期行为添加输入/输出示例缺少注意事项边界情况处理不当添加限制条件七、最佳实践description 是生命线花 50% 的时间打磨这一行描述指令要具体不要写处理数据要写用 pandas 读取 CSV检测缺失值用均值填充提供示例一个好示例胜过十段描述标注边界明确说明 Skill 不能做什么保持更新随着使用反馈迭代优化测试验证写完后实际测试确保 AI 能正确理解和执行八、总结SKILL.md的设计哲学是极简而完整——一个文件包含了元数据、指令、工具、示例和注意事项。理解了这个结构你就掌握了 Skill 开发的基础。记住好的 SKILL.md 好的 description 具体的指令 清晰的示例。下一篇预告SK-05 将揭秘 Skill 的渐进式加载原理——为什么装 100 个 Skill 也不会爆上下文。我们会深入到代码层面看看 AI 是如何实现只加载需要的这个精妙设计的。本系列覆盖AI 大模型基础、Agent 开发、MCP 协议、Skill 开发、RAG、模型微调、部署推理七大方向从入门到实战的全栈内容持续更新中。所有文章的 Markdown 源文件、可运行代码、高清配图已整理成完整资料包。 点赞 ⭐ 关注评论区扣「1」挨个发你领取方式
