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

Ne0inhk

— 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

【初阶数据结构08】——树的基本概念与堆的基本功能实现

【初阶数据结构08】——树的基本概念与堆的基本功能实现

文章目录 前言 一、树的概念 1.1 树的定义 1.2 树的相关术语 1.3 树的表示 1.4 树在实际中的应用 二、二叉树概念及结构 2.1 二叉树的定义 2.2 现实中的二叉树 2.3 特殊的二叉树 2.4 二叉树的性质 2.5 二叉树的存储结构 1. 顺序存储 2. 链式存储 三、堆的概念与结构 3.1 堆的定义 3.2 堆的存储结构 四、堆的基本功能实现 4.1 辅助函数：

By Ne0inhk
【递归，搜索与回溯算法 & floodfill 算法】深入理解 floodfill 算法：floodfill 算法小专题

【递归，搜索与回溯算法 & floodfill 算法】深入理解 floodfill 算法：floodfill 算法小专题

图像渲染     题目解析         算法原理         解法：暴搜          模拟过程          递归过程：        回溯过程：       处理细节问题     但是如果在上述矩阵的情况下，给我们的 color 不是 2 ，而是 1，也就是原始像素值和要修改像素值相同的情况，此时很有可能在递归的时候走重复路径： 我们不处理好这种特殊的情况，就很容易会写出 bug；所以在编写代码的时候，我们先判断一下，if (image[sr][sc]==color)，直接返回即可，因为无需修改；      编写代码      报错原因：没有修改 image[ sr ][ sc ] 为 color 优化：本题并不需要 vis 数组来标记走过的格子，因为走过的格子都会修改，修改后会被剪枝条件筛查掉，并且这道题也没有递归出口，也不需要恢复现场； 岛屿数量     题目解析         算法原理         解法：

By Ne0inhk
力扣校招算法通关：双指针技巧全场景拆解 —— 从数组操作到环检测的高效解题范式

力扣校招算法通关：双指针技巧全场景拆解 —— 从数组操作到环检测的高效解题范式

文章目录 * 前言 * 双指针 * 例题讲解 * 移动零 力扣 * 复写零 力扣 * 快乐数 力扣 * 盛最多水的容器 力扣 * 有效三角形的个数 力扣 * 查找总价格为目标值的两个商品 力扣 * 三数之和 力扣 前言 在力扣校招算法题中，双指针技巧是一类高频且实用的解题方法。它并非真正的 “指针”，而是通过两个数组下标（或迭代器）的协同移动，在数组划分、区间求解、环检测等场景中实现高效遍历与逻辑处理，往往能将时间复杂度从暴力法的 O(n平方)优化至O(n)，是校招笔试和面试中突破数组类难题的关键武器。 本专栏将围绕力扣校招高频的双指针题型展开，从 “移动零”“复写零” 的数组操作，到 “快乐数” 的环检测、“盛最多水的容器” 的区间优化，再到 “三数之和” 的多指针协同，逐一拆解双指针的核心逻辑、边界处理与去重技巧，

By Ne0inhk
【数据结构】二叉树初阶——超详解！！！（包含二叉树的实现）

【数据结构】二叉树初阶——超详解！！！（包含二叉树的实现）

【数据结构】二叉树初阶——超详解！！！（包含二叉树的实现） * 前言 * 一、树是什么？ * 1. 树的定义 * 2. 一些常见术语 * 二、二叉树 * 1. 二叉树是什么 ？ * 2. 二叉树的组成 * 2. 特殊的二叉树 * 3. 二叉树的顺序存储（完全二叉树） * 4. 二叉树的一些性质 * 三、二叉树的实现（重点！！！） * 1. 二叉树的链式存储（非完全二叉树） * 2. 实现思路 * 3. 代码实现 * （1）创建头文件&源文件 * （2）定义二叉树（定义） * （3）构建二叉树 * （4）二叉树遍历（前中后序） * （5）二叉树的层序遍历 * （6）二叉树节点个数的计算

By Ne0inhk