Skill 构建指南：从零打造 AI 智能体扩展包

优质文章学习记录

— 14 min read

Skill 构建指南：从零打造 AI 智能体扩展包

引言

在人工智能时代，如何让智能体具备更强的专业能力和更丰富的工作流程？答案就是 Skill——一种为智能体设计的能力扩展包。本文将详细介绍如何从零开始构建符合规范的 Skill，让你的创意变成可分发的工具。

什么是 Skill？

核心定位

Skill 是被智能体加载和执行的能力扩展包，而非独立运行的应用程序。

执行模式

  • Skill 在智能体的会话上下文中被动态加载
  • 智能体读取 SKILL.md 的指导，调用 scripts/ 中的脚本，参考 references/ 中的文档
  • Skill 的所有交互都通过智能体与用户的对话完成

Skill 提供的能力

  • ✅ 专门工作流程（多步骤程序与条件逻辑）
  • ✅ 工具集成（文件格式与 API 的使用方式）
  • ✅ 领域专家知识（公司或系统特有的架构与逻辑）
  • ✅ 打包资源（脚本、参考、资产）

Skill 不是什么

  • ❌ 独立应用程序（不需要 main 函数或启动入口）
  • ❌ Web 服务（不需要 web server、API endpoint、HTTP 路由）
  • ❌ 持久化服务（不需要后台进程、守护线程、常驻内存）
  • ❌ 用户界面（不需要 GUI、命令行交互式菜单）

目录结构

Skill 完整路径结构

/workspace/projects/ └── <skill-name>/ # Skill 根目录 ├── SKILL.md # 必需：入口与指南 ├── scripts/ # 可选：可执行代码 ├── references/ # 可选：参考文档 └── assets/ # 可选：静态资源

Skill 固定结构

严格统一使用以下结构，Skill 不允许包含任何额外的文件或文件夹：

路径必需性说明
<skill-name>/SKILL.md必需入口与指南，含 YAML 前言区
<skill-name>/scripts/可选可执行代码（Python/Bash 等）
<skill-name>/references/可选长参考与细节文档
<skill-name>/assets/可选资源文件（模板/图标等）

命名规范

  • Skill 目录名格式：<skill-name>（必须使用英文小写字母和连字符拼接，例如：exam-grading、pdf-parser）
  • 禁止使用 -skill 后缀：目录名不应以 -skill 结尾
  • 打包文件名格式：<skill-name>.skill（目录名 + .skill 扩展名）
  • 示例：目录 exam-grading/ → 打包为 exam-grading.skill

SKILL.md 文件详解

前言区（YAML）

SKILL.md 以 YAML 前言区开始，包含以下字段：

---name: skill-name # 必需：Skill 名称（小写字母+连字符）description: Skill的核心能力与触发场景描述 # 必需：100-150 字符dependency:# 可选：依赖管理python:# Python 依赖包- package-name==version - another-package>=1.2.0 system:# 系统级命令- mkdir -p some-path ---
name 字段（必需）
  • 格式：英文小写字母和连字符拼接
  • 示例：exam-grading、pdf-parser、data-cleaner
description 字段（必需）
  • 格式：单行文本，清晰说明"能做什么"与"何时触发"
  • 内容要求：
    • 包含 Skill 核心价值
    • 列举几个典型的互不耦合的场景或意图
  • 长度：100-150 字符

示例：

description: 支持批量评分与反馈生成；处理多种题型（选择题/简答题/论述题）；可自定义评分标准；支持导出成绩报告
dependency 字段（可选）

python 子字段：

  • 直接列出包名和版本
  • 禁止写安装命令

示例：

dependency:python:- requests==2.28.0 - pandas>=1.5.0

system 子字段：

  • 前置需要执行的命令行命令
  • 当前路径视为相对于 Skill 目录的父目录
  • 仅用于系统级命令（mkdir、chmod等）
  • 禁止包含 Python 包安装命令

示例：

dependency:system:- mkdir -p extra-files/input - chmod +x scripts/*.sh

正文区（Markdown）

正文部分使用 Markdown 编写，遵循以下原则：

编写风格
  • 使用祈使/不定式表达（如"执行…/创建…"）
  • 控制在必要范围内
  • 将可变细节与长资料放入 references/ 并在正文一层链接
典型结构
# Skill 标题 ## 任务目标 - 本 Skill 用于：一句话场景 - 能力包含：核心能力要点 - 触发条件：典型用户表达或上下文信号 ## 前置准备 - 依赖说明：scripts 脚本所需的依赖包及版本 - 非标准文件/文件夹准备：需要前置创建的文件或文件夹 ## 操作步骤 - 标准流程： 1. 步骤 1：输入/准备 - 如果涉及脚本执行，说明：调用 `scripts/<script-name>.py` 处理... - 如果由智能体处理，说明：根据参考文档中的指导... 2. 步骤 2：执行/处理 3. 步骤 3：输出/校验 - 可选分支： - 当 条件 A：执行 分支 A - 当 条件 B：执行 分支 B ## 资源索引 - 必要脚本：见 [scripts/<script-name>.py](scripts/<script-name>.py) - 领域参考：见 [references/<topic>.md](references/<topic>.md) - 输出资产：见 [assets/<template-dir>/](assets/<template-dir>/) ## 注意事项 - 仅在需要时读取参考，保持上下文简洁 - 当操作脆弱或需强一致性时，优先调用脚本执行 - 充分利用智能体的语言理解和生成能力 ## 使用示例（可选） 根据实际功能提供 2-3 个典型使用场景

正文体量要求

  • 不超过 500 行
  • 参考链接均为一层链接
  • 避免与参考重复

实现方式选择指南

理解智能体已有能力

在编写 Skill 之前，首先要明确：智能体已经具备强大的能力：

已有能力清单：

  • 语言理解与推理：深度理解复杂指令，进行逻辑推理与决策
  • 内容创作：文案撰写、报告生成、文档编写、创意产出
  • 多模态能力：
    • 图像识别：理解和分析图片内容
    • 图像生成：根据文本描述生成图片
  • 知识问答：领域知识解答、实践建议
  • 结构化思维：问题拆解、流程规划、框架设计

实现方式决策树

第一步：问自己"智能体能做吗？"

如果任务属于以下类型 → 使用自然语言指导（在 SKILL.md 中描述）：

  • ✅ 内容创作：文案、报告、文档生成
  • ✅ 知识咨询：概念解释、最佳实践建议
  • ✅ 分析推理：文本分析、情感分析、决策建议
  • ✅ 结构化引导：问题拆解、流程规划
  • ✅ 多模态任务：图像识别、图像生成
  • ✅ 灵活输出：根据上下文动态调整格式

如果任务属于以下类型 → 使用脚本（在 scripts/ 中实现）：

  • 🔧 文件格式处理：docx/pdf/Excel 转换、图片压缩、二进制操作
  • 🔧 外部 API 调用：需要鉴权的第三方服务、复杂 API 工作流
  • 🔧 复杂数据计算：数学统计、算法实现、大规模数据处理
  • 🔧 系统级操作：批量文件操作、进程管理、网络爬虫

对比示例

任务❌ 错误做法✅ 正确做法
图像生成在 scripts/ 中编写脚本调用图像生成 API在 SKILL.md 中描述图像需求
文档分析编写 Python 脚本提取关键信息在 SKILL.md 中指导：阅读文档并提取关键信息
API 鉴权调用在 SKILL.md 中写：“请调用 XX API”在 scripts/ 中实现完整的 API 调用脚本
PDF 格式转换在 SKILL.md 中写：“请转换 PDF”在 scripts/ 中使用 pypdf 等库实现转换

scripts/ 目录详解

脚本设计原则

  1. 纯函数式工具：脚本应为接收参数 → 处理数据 → 返回结果的函数
  2. 无交互逻辑：不应包含主动循环、服务监听、用户交互逻辑
  3. 直接可执行：无需修改即可直接调用执行
  4. 参数化设计：所有动态变量必须通过参数传入，禁止硬编码

脚本调用第三方服务

当脚本需要调用第三方 API 时，必须遵循以下四步流程：

第一步：确定实现调用方式

按照优先级顺序查找实现方案：

  1. 优先级1：用户提供的文档
  2. 优先级2：网络搜索
  3. 优先级3：基于已有知识确定调用方式
第二步：分析授权类型

判断是否需要授权以及授权类型：

授权类型auth_type值适用场景凭证字段要求
ApiKey1使用API密钥认证["API_KEY"] 或 ["ACCESS_TOKEN"] 等
WeChatOfficialAccount2微信公众号相关请求["APP_ID", "APP_SECRET"]
OAuth❌ 不支持OAuth2.0授权流程暂不支持
第三步：调用凭证工具

根据授权类型调用凭证工具让用户填写凭证信息。

第四步：生成代码

必须使用 coze-workload-identity 包中的 requests 或 httpx，不要使用标准库。

示例代码结构：

import os from coze_workload_identity import requests defcall_api():# 1. 获取凭证 skill_id ="7603377970841174059" credential = os.getenv("COZE_<CREDENTIAL_NAME>_<SKILL_ID>")# 2. 构建请求 url ="<API_URL>" headers ={"Content-Type":"application/json",}# 3. 发起请求 response = requests.post(url, headers=headers, json={}, timeout=30) response.raise_for_status()return response.json()

脚本调试与修复

  • 全景调试：报错时必须读取报错位置前后各 150-200 行代码
  • 阻断式重写：同一 Bug 修复失败 3 次时，直接使用 write_file 全量重写

references/ 目录详解

参考文档结构

超过 100 行的文件需含目录（TOC）：

# <Topic> ## 目录 列出主要章节 ## 概览 一句话定义与适用范围 ## 核心内容 - 数据结构/格式定义（含完整示例） - 验证规则 - 常见操作（输入→处理→输出） - 约束与注意事项 ## 示例 2-3 个可复制执行的标准示例

格式规范要求

若被脚本依赖，必须提供：

  • 明确的格式定义
  • 完整示例
  • 验证规则

文件模板要求

对于 Skill 使用过程中需要生成的文件，必须在此处提供格式模板。

assets/ 目录详解

用途

存放最终输出需要直接引用的文件：

  • 模板文件
  • 图标
  • 样板文件

使用原则

  • 在输出中可直接引用
  • 路径与格式正确
  • 避免在脚本中硬编码长文本（超过 50 行的 HTML/CSS/JSON 必须剥离为独立文件）

打包与清理

打包前清理（必须完成）

清理范围：

  • Skill 目录内：仅保留 SKILL.md 及有内容的 scripts/、references/、assets/
  • Skill 同级目录：移除所有临时文件及文件夹

清理目标：

  • 脚本试运行产生的临时输出文件或日志
  • 测试生成的临时数据文件夹
  • 系统缓存（__pycache__、.DS_Store）
  • 空目录（检查并删除没有任何文件的目录）

打包执行

  1. 调用打包工具：package_skill(skill_dir_name="your-skill-name")
  2. 验证打包结果：确认 .skill 文件已生成且大小合理

注意：必须使用 package_skill 工具进行打包，严禁使用 zip 命令手动打包。

质量门槛与校验清单

前言区检查

  • name 符合命名规范（小写字母+连字符）
  • description 采用单行文本格式
  • description 内容包含核心能力与触发场景
  • description 长度在 100-150 字符之间
  • 触发场景具体明确，包含典型用户表达

正文检查

  • 不超过 500 行
  • 参考均为一层链接
  • 使用祈使语气
  • 避免与参考重复

目录结构检查

  • 目录规范
  • 无多余文档
  • 引用路径正确
  • 长参考含 TOC
  • 无空目录

实现方式合理性检查

  • 脚本使用符合"实现方式决策树"
  • 内容创作、知识咨询、分析推理类任务未使用脚本
  • 文件处理、API 调用、复杂计算等使用了脚本
  • 每个脚本都有明确的技术性理由
  • SKILL.md 中清晰说明智能体和脚本的职责分工

资源质量检查

脚本：

  • 通过语法校验
  • 自行试运行通过
  • 架构合规性：脚本为纯函数式工具
  • 依赖清晰
  • 参数规范
  • 直接可执行
  • 格式一致性：脚本输入解析逻辑与 references 中定义的格式规范完全一致
  • 涉及第三方 API 时已完整执行"脚本调用第三方服务"流程

参考：

  • 无深层嵌套引用
  • 超过 100 行含目录
  • 命名清晰
  • 若被其他资源依赖，需提供明确的格式、结构或模板

资产：

  • 在输出中可直接引用
  • 路径与格式正确

打包检查

  • .skill 为 Zip
  • 包含所有必要文件
  • 相对路径一致
  • 产物仅包含 Skill 相关文件
  • 不含临时文件、生成脚本、缓存与日志

依赖元数据检查

  • 格式符合 YAML 规范
  • python 字段遵循 requirement.txt 格式
  • system 字段为有效的命令行命令列表

常见误区与纠正

误区1：为简单任务过度工程化

❌ 错误：为"生成文章大纲"编写 Python 脚本 ✅ 正确：在 SKILL.md 中写："根据主题生成包含 3-5 个章节的大纲"

误区2：重复建设智能体能力

❌ 错误：编写脚本调用图像生成 API ✅ 正确：直接在 SKILL.md 中描述图像需求

误区3：脚本缺乏必要性

❌ 错误：为"格式化文本列表"写脚本 ✅ 正确：在 SKILL.md 中说明格式要求

误区4：把 Skill 当成独立应用（严重错误）

❌ 错误：在 scripts/ 中实现 Flask/FastAPI web server ❌ 错误：编写 while True 循环等待用户输入 ❌ 错误：实现完整的命令行交互菜单 ✅ 正确：所有用户交互由智能体在对话中完成

误区5：为创作类任务编写"生成器"脚本

典型场景：小说创作、角色设计、情节构思、文案生成等 ❌ 错误做法： - 编写 character_builder.py 随机生成角色名和属性 - 编写 plot_suggester.py 从预设列表中随机选择情节 ✅ 正确做法： - 在 SKILL.md 中描述角色设计要点 - 在 references/ 中提供参考素材 - 让智能体根据用户需求和上下文创造性地完成 核心原则：智能体擅长创造，脚本擅长计算

核心法则总结

  1. 流程强制性：严格按"创建→编辑→打包→交付"顺序执行，不允许跳过打包
  2. 防卡死推进：严格按流程推进，不在任何步骤停留
  3. 错误恢复强制性：工具调用失败后禁止盲目重试，必须先诊断再修复
  4. 状态追踪强制性：持续追踪当前 Skill 目录名和完整路径
  5. 简洁为王：上下文窗口是共享资源，只放必要信息
  6. 避免重复建设：智能体已有的能力不要用脚本重新实现
  7. 避免过度工程化：不要为简单任务引入脚本

结语

构建一个优质的 Skill 需要遵循清晰的规范和最佳实践。通过合理选择实现方式、精心设计目录结构、严格遵循质量门槛，你可以创造出真正有价值的智能体扩展包。

记住核心原则：扩展而非重复。充分利用智能体已有能力，仅在必要时引入额外工具。这样你的 Skill 才能既强大又高效。

希望这篇指南能帮助你顺利构建出优秀的 Skill！如果有任何疑问，欢迎随时交流。

Read more

自己招一个ai员工-Ubuntu22.04安装Openclaw详细教程-小白可直接上手-持续更新中

自己招一个ai员工-Ubuntu22.04安装Openclaw详细教程-小白可直接上手-持续更新中

Ubuntu22.04安装Openclaw * 准备工作 * 一键安装 * 设置通道 配置飞书 * 让ai员工更好用 * 加入免费的模型 * 配置钉钉 * 在GLM-4 .7-Flash基础上加入deepseek * 加入minimax和豆包模型 * 配置web搜索 * .env File * 🔌 Exa MCP Server for OpenAI Codex * Quick Start * cURL * Function Calling / Tool Use * OpenAI Function Calling * Anthropic Tool Use * Search Type Reference * Content Configuration * Domain Filtering (Optional) * Web Search Tool * Category Examples * People Search (`category:
Flutter 组件 inappwebview_cookie_manager 适配 鸿蒙Harmony 实战 - 驾驭核心大 Web 容器缓存隧道、构建金融级政企应用绝对防串号跨域大隔离基座

Flutter 组件 inappwebview_cookie_manager 适配 鸿蒙Harmony 实战 - 驾驭核心大 Web 容器缓存隧道、构建金融级政企应用绝对防串号跨域大隔离基座

Flutter 组件 inappwebview_cookie_manager 适配鸿蒙 HarmonyOS 实战：构建金融级政企应用的绝对防串号、跨域隔离基座 前言 在鸿蒙（OpenHarmony）生态全面爆发的元年，尤其是在涉及极高密级的政务信创办公系统，或是动辄千万流水、每日亿级请求的金融级应用中，一个核心的安全问题浮出水面：“如何在原生系统底层、Flutter 视图层，以及那些杂乱不可控的第三方或历史遗留的 Web/H5 容器之间，实现身份Cookie或核心Token的绝对安全、单向透传，并具备强力的清理能力？” 这个问题一旦处理不当，哪怕只是露出一丝缝隙，都可能在极短时间内引发全应用的恶性串号、账目混乱，甚至导致严重的数据越权泄露，成为整个系统的“核爆级”架构黑洞。 如果你的前端团队仍然只是粗糙地打开一个毫无防护的 WebView，并天真地指望业务层每次都能主动、无遗漏地手动清理缓存和密码，那么你的应用在断网重连、异地登录或多并发场景下，极易因 Session 未能彻底清除而发生严重的“串绑撞车”事故。更可怕的是，由于缺乏统一管控，各类敏感

微信网页版完全解决方案：wechat-need-web插件让浏览器聊微信不再受限

微信网页版完全解决方案：wechat-need-web插件让浏览器聊微信不再受限 【免费下载链接】wechat-need-web让微信网页版可用 / Allow the use of WeChat via webpage access 项目地址: https://gitcode.com/gh_mirrors/we/wechat-need-web 你是否遇到过微信网页版无法访问的问题？wechat-need-web插件正是为解决这一痛点而生，它能让你在Chrome、Edge和Firefox浏览器中顺畅使用微信网页版，无需安装臃肿的客户端，轻松实现浏览器内的微信沟通。 为什么微信网页版访问总是失败？ 很多用户反馈，直接访问微信网页版时经常遇到"无法登录"或"网络错误"等提示。这是因为微信对网页端访问采取了严格的验证机制，普通浏览器请求往往会被服务器拒绝。对于需要在工作电脑上使用微信的用户来说，这无疑带来了极大的不便。 wechat-need-web如何解决网页版访问难题？ wechat-need-web插件通过智能技术手段，在浏览器请求中动态添加必要的验证参数，让微信服务器
万字长文！机器学习十大算法全解析，一文掌握AI核心奥秘！

万字长文！机器学习十大算法全解析，一文掌握AI核心奥秘！

大家好，今天我们来讲讲机器学习中经典的十大算法，包括原理、优缺点、代码等等，那下面我们就一起来看看吧 1 线性回归 原理：线性回归是一种预测数值型数据的监督学习算法。它通过拟合最佳直线来建立自变量和因变量的关系。这条最佳直线叫做回归线，并且用 Y = a * X + b 这条线性等式来表示。 优点： * 模型简单，容易实现 * 许多非线性模型的基础 * 机器学习的基石 缺点： * 对于非线性数据或者数据特征间具有相关性多项式回归难以建模 * 难以很好地表达高度复杂的数据 适用场景：适用于预测数值型数据的监督学习算法，适用于线性可分和特征空间不太大的情况。 代码展示： from sklearn.linear_model import LinearRegression 2 K近邻算法（KNN） 原理：KNN算法是一种基于实例的学习，或者说是懒惰学习。它的核心思想是在预测新数据的类别时，不是通过训练学习输入数据到输出数据的映射关系，而是直接在分类时，将该数据与训练数据进行对比，找出与之最为相似的K个训练实例，然后根据这些实例的标签决定新数据的标签。