Skill 的核心结构SKILL.md 脚本 参考材料一个完整的 Agent Skill 由三部分组成SKILL.md认知层、脚本执行层、参考材料知识层。这个 “三件套” 结构看似简单却蕴含着深刻的设计哲学——它将 “是什么”、“怎么做” 和 “知道什么” 分离为三个独立的关注点使 Skill 既易于理解、又易于维护、还易于扩展。本文深入剖析每一层的设计原理、最佳实践和常见陷阱。一、前言为什么是三层在设计 Agent Skill 的文件结构时我们面临一个根本性的选择是把所有信息放在一个文件里还是拆分成多个文件一个极端是 “大一统” 模式——所有描述、代码、知识都塞进一个文件。这在简单场景下可行但随着 Skill 复杂度增长文件会变得难以维护。另一个极端是 “极度分散” 模式——每个小功能一个文件。这会导致 Skill 的结构过于碎片化Agent 难以形成完整的认知。三件套结构SKILL.md 脚本 参考材料是经过实践验证的中间方案。它的设计灵感来自人类专家的工作方式SKILL.md ≈ 专家的自我介绍告诉别人 “我是谁、我能做什么、我的边界在哪里”。脚本 ≈ 专家的工具箱实际执行任务的工具和方法。参考材料 ≈ 专家的知识库支撑决策的领域知识和经验。这三层分别对应认知科学中的三种知识类型元认知Metacognition、程序性知识Procedural Knowledge和陈述性知识Declarative Knowledge。二、SKILL.md 的设计哲学认知层2.1 SKILL.md 是什么SKILL.md 是 Skill 的 “大脑”——它不包含可执行代码也不包含详细的数据它包含的是让 Agent 理解这个 Skill 所需的一切元信息。一个好的 SKILL.md 应该回答以下问题这是什么身份定义什么时候用适用场景什么时候不用能力边界怎么用使用方式需要什么依赖声明有什么限制约束条件2.2 设计原则原则一为 Agent 写不是为人写SKILL.md 的主要读者是 AI Agent不是人类开发者。这意味着使用清晰、无歧义的语言避免隐含假设和文化背景依赖结构化信息要与自然语言描述并行提供关键决策点要显式声明!-- 不好的写法假设读者知道什么是 EDA -- # 数据分析 Skill 用于执行 EDA。 !-- 好的写法显式定义 -- # 数据分析 Skill 用于执行探索性数据分析Exploratory Data Analysis, EDA 即在不假设数据分布的情况下通过统计摘要和可视化来理解数据特征。原则二边界比能力更重要很多 Skill 设计者把大部分篇幅用于描述 “能做什么”却对 “不能做什么” 一笔带过。这是一个严重的错误。Agent 在选择 Skill 时最需要的信息是什么时候不应该使用这个 Skill。清晰的边界描述可以防止 Agent 在不恰当的场景下误用能力这比功能描述更能提升系统的可靠性。原则三场景驱动不是功能驱动SKILL.md 的组织方式应该围绕 “使用场景”而不是 “功能列表”。!-- 功能驱动不推荐 -- ## 功能  - 读取 CSV 文件 - 计算统计量 - 生成图表 !-- 场景驱动推荐 -- ## 适用场景  - **数据探索**用户拿到一份新数据想快速了解其分布和特征 - **异常检测**用户想发现数据中的异常值或离群点 - **趋势分析**用户想了解数据随时间的变化趋势2.3 SKILL.md 的标准结构# Skill 名称 ## 一句话描述 [用一句话说明这个 Skill 是什么] ## 适用场景 [什么时候应该使用这个 Skill] ## 不适用场景 [什么时候不应该使用这个 Skill] ## 使用方式 [如何使用这个 Skill包括前置条件和步骤] ## 依赖 [运行这个 Skill 需要的环境、工具、权限等] ## 脚本说明 [列出 Skill 包含的脚本及其用途] ## 参考材料说明 [列出 Skill 包含的参考材料及其用途] ## 注意事项 [使用这个 Skill 需要注意的特殊事项]三、脚本层可执行能力3.1 脚本的角色脚本是 Skill 的 “手”——它们是实际执行任务的可执行代码。SKILL.md 告诉 Agent “这个 Skill 能做什么”脚本则负责 “实际去做”。脚本层的设计目标是可执行性脚本必须能直接运行不需要额外的手动配置。独立性每个脚本应该是一个独立的功能单元可以单独调用。可观测性脚本的输入、输出和执行过程应该是可观察的。容错性脚本应该优雅地处理错误而不是崩溃。3.2 脚本设计原则原则一单一职责每个脚本只做一件事。如果一个脚本需要做多件事说明 Skill 的粒度可能需要调整。# 好的设计每个脚本职责清晰scripts/ ├── read_data.py# 只负责读取和解析数据├── statistics.py# 只负责计算统计量├── visualize.py# 只负责生成图表└── export.py# 只负责导出结果原则二标准化输入输出脚本的输入输出应该遵循统一的约定便于 Agent 理解和组合。#!/usr/bin/env python3 统计分析脚本 输入 --input file 数据文件路径CSV/Excel --columns cols 要分析的列名逗号分隔 --method method 分析方法describe/correlation/distribution --output file 输出文件路径可选默认输出到 stdout 输出 JSON 格式的统计结果 退出码 0 - 成功 1 - 输入错误 2 - 分析错误 importargparseimportjsonimportsysimportpandasaspddefmain():parserargparse.ArgumentParser(description统计分析)parser.add_argument(--input,requiredTrue,help数据文件路径)parser.add_argument(--columns,help要分析的列名逗号分隔)parser.add_argument(--method,defaultdescribe,choices[describe,correlation,distribution])parser.add_argument(--output,help输出文件路径)argsparser.parse_args()try:dfpd.read_csv(args.input)exceptExceptionase:print(json.dumps({error:f读取文件失败:{e}}),filesys.stderr)sys.exit(1)columnsargs.columns.split(,)ifargs.columnselsedf.columns.tolist()try:ifargs.methoddescribe:resultdf[columns].describe().to_dict()elifargs.methodcorrelation:resultdf[columns].corr().to_dict()elifargs.methoddistribution:result{col:{mean:float(df[col].mean()),std:float(df[col].std()),skew:float(df[col].skew()),kurtosis:float(df[col].kurtosis())}forcolincolumnsifdf[col].dtypein[int64,float64]}exceptExceptionase:print(json.dumps({error:f分析失败:{e}}),filesys.stderr)sys.exit(2)outputjson.dumps(result,ensure_asciiFalse,indent2)ifargs.output:withopen(args.output,w)asf:f.write(output)else:print(output)if__name____main__:main()原则三错误信息要有指导性当脚本出错时错误信息不仅要说 “出了什么错”还要说 “怎么修”。# 不好的错误处理raiseFileNotFoundError(File not found)# 好的错误处理raiseFileNotFoundError(f数据文件不存在:{file_path}\nf请检查\nf1. 文件路径是否正确\nf2. 文件是否在工作区目录下\nf3. 文件名是否包含特殊字符)四、参考材料层领域知识4.1 参考材料的角色参考材料是 Skill 的 “记忆”——它们存储了支撑 Skill 运行的领域知识、最佳实践和示例。与脚本不同参考材料不是用来执行的而是用来指导决策的。参考材料的典型内容包括领域知识文档特定领域的概念、规则和约束最佳实践指南经过验证的方法和模式示例库典型场景的输入输出示例模板常用格式和结构的模板常见问题典型错误和解决方案4.2 为什么需要参考材料一个自然的问题是这些知识不能直接写在 SKILL.md 里吗答案是在简单场景下可以但在复杂场景下不行。原因有三信息量领域知识可能非常庞大全部放在 SKILL.md 里会稀释核心信息。独立性领域知识可能被多个 Skill 共享放在参考材料中便于复用。可维护性领域知识更新频率可能与 Skill 定义不同分离存放便于独立维护。4.3 参考材料的组织方式references/ ├── concepts/ # 概念定义 │ ├── statistical-tests.md # 统计检验方法说明 │ └──>4.4 参考材料的引用机制SKILL.md 通过引用机制指向参考材料而不是将内容内联## 分析方法选择 根据数据类型和分析目标选择合适的分析方法 - **数值型数据的分布分析** → 参见 references/patterns/exploratory.md - **两组数据的差异比较** → 参见 references/concepts/statistical-tests.md - **时间序列趋势分析** → 参见 references/patterns/temporal.md ## 示例 - 销售数据分析references/examples/sales-analysis/walkthrough.md - 用户行为分析references/examples/user-behavior/walkthrough.mdAgent 在执行任务时可以根据需要动态加载相关参考材料而不是一次性加载所有知识。五、代码示例完整 Skill 结构5.1 文件结构skills/data-analysis/ ├── SKILL.md # 认知层Skill 定义和使用指南 ├── scripts/ # 执行层可执行脚本 │ ├── read_data.py # 数据读取和预处理 │ ├── statistics.py # 统计分析 │ ├── visualize.py # 可视化生成 │ └── export.py # 结果导出 ├── references/ # 知识层领域知识 │ ├── concepts/ │ │ ├── statistical-tests.md │ │ └──>5.2 SKILL.md 完整示例# 数据分析 Skill ## 一句话描述 对结构化数据CSV/Excel进行探索性分析、统计推断和可视化的能力。 ## 适用场景 - 用户拿到一份新数据想快速了解其整体特征 - 需要对数据进行统计检验如 t 检验、卡方检验 - 需要生成数据可视化图表分布图、相关性热图等 - 需要从数据中发现趋势、模式或异常值 ## 不适用场景 - 数据量超过 1GB请使用 大数据分析 Skill - 需要实时处理数据流请使用 流处理 Skill - 非结构化数据文本、图片、音视频分析请使用对应的 NLP/CV Skill - 需要因果推断的场景本 Skill 仅提供描述性统计和相关性分析 ## 使用方式 ### 前置条件 1. 数据文件为 CSV 或 Excel 格式 2. 数据文件已放置在工作区目录下 3. 已安装 Python 3.10 及依赖包 ### 使用步骤 1. 描述你的分析需求自然语言即可 2. Skill 会自动选择合适的分析方法 3. 查看生成的分析报告和图表 ### 示例 - 分析 sales.csv 的销售趋势 - 看看 user_data.csv 中各年龄段的消费差异 - 检查 data.csv 中有没有异常值 ## 依赖 - Python 3.10 - pandas 2.0 - matplotlib 3.7 - scipy 1.10 - openpyxl 3.1 (Excel 支持) ## 脚本说明 | 脚本 | 用途 | 典型输入 | 典型输出 | |------|------|---------|---------| | read_data.py | 读取和预处理数据 | 数据文件路径 | JSON 格式的数据摘要 | | statistics.py | 统计分析 | 数据文件 分析方法 | JSON 格式统计结果 | | visualize.py | 生成可视化图表 | 数据文件 图表类型 | PNG/SVG 图表文件 | | export.py | 导出分析结果 | 分析结果 格式 | 格式化的报告文件 | ## 参考材料说明 - references/concepts/ — 统计学概念和数据类型说明 - references/patterns/ — 常见分析模式和方法选择指南 - references/examples/ — 典型分析场景的完整示例 - references/troubleshooting.md — 常见问题和解决方案 ## 注意事项 - 大文件处理超过 100MB 的文件建议先用 read_data.py 的 --sample 参数采样 - 缺失值默认会自动处理缺失值但会在结果中标注缺失比例 - 敏感数据包含个人信息的列默认排除分析除非显式指定5.3 配置文件示例# config/defaults.yaml# Skill 运行时的默认配置data:max_file_size_mb:1024# 最大文件大小default_encoding:utf-8# 默认编码missing_value_strategy:auto# 缺失值处理策略sample_size:10000# 采样大小大文件时analysis:default_method:describe# 默认分析方法confidence_level:0.95# 置信水平outlier_method:iqr# 异常值检测方法visualization:default_style:seaborn-v0_8-whitegrid# 图表风格figure_size:[10,6]# 默认图表尺寸dpi:150# 分辨率color_palette:husl# 调色板font_family:sans-serif# 字体六、结构设计的最佳实践6.1 SKILL.md 的最佳实践使用 “适用/不适用” 对称结构每列一个适用场景就应该对应一个不适用场景。这种对称结构帮助 Agent 建立精确的能力边界认知。提供具体示例不要只说 “用于数据分析”要说 “分析 sales.csv 的月度销售趋势”。具体的示例比抽象的描述更有助于 Agent 理解。声明依赖关系明确列出 Skill 需要的环境、工具和权限。这有助于 Agent 在使用前检查前置条件。6.2 脚本的最佳实践幂等性相同输入应产生相同输出。这使得脚本可以安全地重试。渐进式输出对于长时间运行的脚本提供进度信息而不是让用户等待最终结果。向后兼容脚本的接口输入输出格式应该保持稳定变更时通过版本号管理。6.3 参考材料的最佳实践模块化组织按主题组织参考材料而不是按时间或来源。交叉引用在参考材料之间建立清晰的引用关系帮助 Agent 在不同知识之间导航。示例驱动每个概念或模式都应该配有具体的示例。抽象描述 具体示例的组合比单独使用任何一种都更有效。6.4 三层之间的协作理解需求需要领域知识是否用户请求SKILL.md 认知层选择合适的脚本加载参考材料执行脚本返回结果结果是否合理?输出给用户参考 troubleshooting认知层SKILL.md负责理解和决策执行层脚本负责操作知识层参考材料负责支撑。三者协同工作形成完整的 Skill 能力。七、总结Skill 的三件套结构SKILL.md 脚本 参考材料是一种经过实践验证的设计模式它的核心优势在于关注点分离认知、执行、知识三个关注点清晰分离便于独立开发和维护。渐进式复杂度简单 Skill 可以只有 SKILL.md 一个脚本复杂 Skill 可以扩展到完整的三层结构。可复用性参考材料可以跨 Skill 共享脚本可以独立调用。Agent 友好SKILL.md 的设计以 Agent 的理解方式为中心支持语义发现和自主决策。设计 Skill 时记住这三个问题SKILL.mdAgent 需要知道什么才能正确使用这个能力脚本Agent 需要执行什么操作才能完成任务参考材料Agent 需要什么知识才能做出正确决策回答好这三个问题你就能设计出高质量的 Agent Skill。参考文献Anderson, J. R. (2007).How Can the Human Mind Occur in the Physical Universe?Oxford University Press. — ACT-R 理论中关于陈述性知识与程序性知识的区分。Brooks, F. P. (1987). “No Silver Bullet: Essence and Accidents of Software Engineering.”IEEE Computer, 20(4), 10-19. — 软件复杂度的本质和模块化的局限。Fowler, M. (2002).Patterns of Enterprise Application Architecture. Addison-Wesley. — 分层架构和关注点分离的经典参考。Anthropic. (2024). “Model Context Protocol (MCP) Specification.” https://modelcontextprotocol.io/ — 工具与能力的标准化接入协议。OpenAI. (2025). “Agents SDK Documentation.” https://openai.github.io/openai-agents-python/ — Agent 能力封装和工具定义的最新实践。本系列覆盖AI 大模型基础、Agent 开发、MCP 协议、Skill 开发、RAG、模型微调、部署推理七大方向从入门到实战的全栈内容持续更新中。所有文章的 Markdown 源文件、可运行代码、高清配图已整理成完整资料包。 点赞 ⭐ 关注评论区扣「1」挨个发你领取方式