Skill的格式 & 开发语言和工具
文章目录
- [Skill的格式 & 开发语言和工具](#Skill的格式 & 开发语言和工具)
- [1. Skill格式介绍](#1. Skill格式介绍)
- [2. 开发语言与工具](#2. 开发语言与工具)
- [3. Codex 的安装](#3. Codex 的安装)
- [4. Skill 的实战：](#4. Skill 的实战：)
推荐看这篇博客之前，把 VS Code 和 Codex 安装一下。
Skill 的开发和使用，需要使用这两个软件。
1. Skill格式介绍
什么是 Skill ，关于 Skill 的基础认知介绍，你可以看我这篇博客：什么是Skill
1.1 目录结构规范
Skill本质上是一个文件夹，核心是包含一个 SKILL.md 文件。这个文件包含元数据（name 和 description 是必须的）以及指导 Agent执行特定任务的指令。
目录结构的规范，更详细的介绍，可以看这个网站上的。
参考: What are skills? - Agent Skills
my‑skill/
├── SKILL.md # 必需：指令 + 元数据
├── scripts/ # 可选：可执行代码
├── references/ # 可选：参考文档
└── assets/ # 可选：模板、资源文件一个 Skill.md 的完整内容，可以看看这个：
至于这个 SKill 是干什么的，你可以先不用管。
各目录说明
| 目录 | 必需性 | 用途 |
|---|---|---|
| SKILL.md | 必需 | 包含YAML元数据（名称、描述等）和Markdown格式的详细指令 |
| scripts/ | 可选 | 存放可执行的脚本代码，Skill可以调用这些脚本完成任务 |
| references/ | 可选 | 存放参考文档、补充说明材料 |
| assets/ | 可选 | 存放模板、图片、配置等资源文件 |
所以，如果要开发一个 Skill ，你不会编程语言，也是可以的 ，只需要你能够使用 markdown语法，编写必须的 Skill.md文件就可以。
只不过，如果你要编写一个功能更加强大，更加丰富的 Skill，就需要结合编程语言去写脚本了。
这种目录结构的优势：
-
文档化 ：直接阅读
SKILL.md就能理解 Skill 的功能 -
可扩展性：从简单的文本指令到复杂的可执行代码都能支持
比如你想实现的 Skill，写好了 Skill.md 这个文件，但是没有达到效果，然后你就添加脚本代码，完善 SKill 的功能
开始是纯文本，后续可以添加脚本代码，这就是可扩展性的体现
-
可移植性：纯文件形式，易于编辑、版本控制和分享
1.2 SKILL.md 文件规范
这是每个 Skill 唯一必需的文件，必须放在技能文件夹的根目录下。它采用 YAML 前置元数据 + Markdown 指令 的格式。
markdown
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
---
# PDF Processing
## When to use this skill
Use this skill when the user needs to work with PDF files...
## How to extract text
1. Use pdfplumber for text extraction...
## How to fill forms
...必需元数据：文件开头必须包含以下两个字段
name：技能的简短标识符。description：描述技能的功能及使用场景。Agent 在启动时只加载这个描述，用于判断何时调用该技能。
指令正文
- 元数据之后，使用 Markdown 编写详细的步骤、指南或提示，告诉 Agent 如何完成任务。这部分内容仅在技能被激活时加载。
- 无严格的结构限制，可以包含任意 Markdown 内容。
- 建议包含清晰的任务分解、步骤说明、代码示例等。
这一段就是指令正文：
markdown
# PDF Processing
## When to use this skill
Use this skill when the user needs to work with PDF files...
## How to extract text
1. Use pdfplumber for text extraction...
## How to fill forms
...1.3 可选目录
可以回顾一下，一个 Skill 需要的文件和目录：
| 目录 | 必需性 | 用途 |
|---|---|---|
| SKILL.md | 必需 | 包含YAML元数据（名称、描述等）和Markdown格式的详细指令 |
| scripts/ | 可选 | 存放可执行的脚本代码，Skill可以调用这些脚本完成任务 |
| references/ | 可选 | 存放参考文档、补充说明材料 |
| assets/ | 可选 | 存放模板、图片、配置等资源文件 |
为了保持结构清晰，扩展资源应放在以下子目录中：
-
scripts/：存放可执行的脚本（如 Python、Bash 文件）。Agent 可在执行任务时运行它们。 -
references/：存放参考文档或额外信息（如 API 文档、详细说明），供 Agent 按需读取。假如你要设计一个问答（Q&A）的 SKill，这里存放的就是 一个知识库，这个 Skill 在回答问题的时候，可以读取这个知识库中的文档，匹配对应的文档
-
assets/：存放模板、图片、样式文件等静态资源，用于生成输出或辅助工作流。假如你要设计一个bug分析报告一键生成的 Skill，你可以写一个报告的模板存放在这个文件夹，后续 Agent调用这个Skill 输出结果的时候，就会按照你设计好的报告模板，进行输出。
1.4 设计原则
这个规范遵循渐进式披露机制，以高效管理上下文：
下面的设计原则，我会使用 图书馆找书 这么个例子，让你结合着进行理解。
-
发现阶段 ：启动时，Agent 只加载所有 Skill 的
name和description，用于判断是否可能相关进入图书馆，你不会盲目的招书，比如，你想学 Agent 相关的，你就会看书名或者书架上的分类，是计算机的且是关于 Agent 的书，你才拿走这本书，进行观看
-
激活阶段 ：当任务匹配某个技能描述时，Agent 加载完整的
SKILL.md指令。找到你符合的书之后，你打开书本，翻看目录，检查是否是符合你的要求的
-
执行阶段：Agent 按照指令执行任务，按需引用其他文件或执行打包的代码。
查看目录之后，确定有你想要学习的内容，你就打开这本书对应的目录所在页数，进行详细的学习。
1.5 Agent Skills 是如何工作的
Agent 并不会一次性把所有 Skill 的全部内容都加载进上下文，而是采用逐步披露（progressive disclosure） 的三阶段机制来加载和使用技能，兼顾多技能储备与上下文开销。
三阶段工作流程
- 发现（Discovery） Agent 启动时，仅读取每个 Skill 的
name和description元数据。 只拿到最精简的基础信息，用来判断：当前用户的问题，是否有可能命中该技能。完整的指令、脚本、参考文档此时并不会载入上下文。 - 激活（Activation） 当用户任务和某个 Skill 的描述匹配上 ，Agent 判定该技能需要参与处理，才会把完整的
SKILL.md全部指令读取，注入会话上下文。 - 执行（Execution） Agent 按照
SKILL.md中的指令开展工作；按需调用scripts/下的可执行代码，读取references/参考文档、assets/资源模板，完成业务任务。
这里指的Agent，不仅仅指代 OpenClaw，还可以是 Codex 等这类 Agent工具。
2. 开发语言与工具
开发一个 Skill，本质上就是写一个说明书（SKILL.md）+ 准备一套工具 (scripts, 可选脚本)，所以对编程语言没有硬性限制。
目前最常用的开发语言有三类：
| 语言 | 适用场景 | 典型 Skill 示例 | 开发工具推荐 |
|---|---|---|---|
| Python | 数据处理、AI 模型调用、文件处理、自动化脚本 | PDF 处理、数据分析、图像识别 | VS Code / PyCharm |
| JavaScriptNode.js | 网页操作、浏览器自动化、Web API 调用 | Playwright 网页抓取、API 集成 | VS Code / WebStorm |
| Bash / Shell | 系统命令、文件操作、环境配置 | 系统管理、批量处理、部署脚本 | Terminal / iTerm2 |
核心原则：Skill 的 SKILL.md 是用 Markdown 写的（纯文本），而 scripts/ 文件夹里的代码才涉及具体编程语言。
所以即使你不会编程，也能写 Skill------ 你可以只写 Markdown 指令，让 Agent 自己去执行。
开发步骤
-
写 SKILL.md ：用 VS Code 打开文件夹，新建
SKILL.md，填写元数据和指令 -
写脚本 ：在
scripts/下写compress.py，实现压缩逻辑 -
本地测试 ：在 VS Code终端 运行
python scripts/XXX.py确保脚本没问题 -
运行 Skill：Skill 的运行，我使用 Codex 来运行
当然，其他的 Agent 工具，例如 OpenClaw 也是可以运行 Skill，只不过我没有安装 OpenClaw 。
VS Code 的安装，网上有很多教程，这个的安装很容易，难的是 Codex。
3. Codex 的安装
至于 Codex 的下载和配置，网上有教程，这里我就不演示了。
我给你我使用的安装教程：复制下面的链接，打开抖音（抖音极速版）
6.15 03/03 b@N.wF :4pm pQK:/ 复制打开抖音极速版，看看【林粒粒呀的作品】小白速通 Codex 安装 + 国产大模型接入 #... https://v.douyin.com/64MU263FjHc/如果是需要魔法上网的话，可以上 Github 找教程。
4. Skill 的实战：
关于 Skill 的实战，我有三个例子：
- 天气的获取：Skill实战：天气的获取
- 二维码生成：Skill实战：二维码生成
- 每日日报：Skill实战：需求文档自动生成测试点