Agent Skills入门:用SKILL.md三步创建Calculator与Jira CLI可复用AI能力

原创2026-11-18 23:51:551,446 阅读

Agent Skills入门:用SKILL.md三步创建Calculator与Jira CLI可复用AI能力

本文带你从 awesome-copilot-agents 项目出发,认识 Agent Skills:一种让 GitHub Copilot 等 AI 助手"即插即用"的可复用 AI 能力。通过剖析 Calculator(任意精度计算器)和 Jira CLI(Jira 命令行管理)两个官方示例,你会发现创建自己的 SKILL.md 并不需要大量代码——只需"文件夹 + 一份说明文档",AI 就能在需要时自动发现并加载它。

1️⃣ 什么是 Agent Skills:AI 的"即装即用"技能包

Agent Skills 是可移植、版本可控的文件夹,里面装着指令、脚本和资源。与传统提示词不同,Skill 不会被"全量塞进上下文",而是由 AI 助手按需发现、按需加载——只有当你提出相关需求时,对应的 SKILL.md 才会被读取。

一个典型的 Skill 由三部分组成:

组成部分 作用 项目中的例子
SKILL.md 核心说明文档,定义技能何时用、怎么用 skills/jira-cli/SKILL.md
scripts/ 可执行脚本,扩展 AI 的动手能力 skills/calculator/scripts/src/calculator.ts
references/ 参考文档,供 AI 查阅细节 skills/cloud/az-cli/references/

它和 Instructions、自定义 Agent 的分工很简单:

2️⃣ 拆解 SKILL.md:前置元数据 + 正文说明书

打开任意一个 SKILL.md,结构都分两半:YAML 前置元数据(front matter)+ Markdown 正文。

前置元数据:告诉 AI"什么时候用我"

以 Calculator 为例(见 skills/calculator/SKILL.md):

name: calculator
description: Performs arbitrary-precision arithmetic calculations including
  addition, subtraction, multiplication, division, and exponents. Use when the
  user asks to calculate, compute, or evaluate math expressions...
compatibility: Requires Node.js and npm
metadata:
  author: Colby Timm
  version: "1.0"

其中 description 最关键——它不只是描述功能,还写明触发条件("Use when the user asks to calculate...")。AI 正是靠这句话判断该不该加载这个技能。

正文:一份完整的使用说明书

好的 SKILL.md 正文通常按这个骨架组织:

  1. When to Use:适用场景清单
  2. Prerequisites:前置条件(依赖什么工具、环境变量)
  3. Commands / Usage:具体命令和操作步骤
  4. Examples:输入输出对照表
  5. Edge Cases / Limitations:边界情况和能力边界

这个结构看似简单,却让 AI 能像"照着手册操作的老手"一样执行任务,而不用你每次重新解释。

3️⃣ 案例一:Calculator 技能——告别浮点误差的任意精度计算器

你大概率遇到过 0.1 + 0.2 = 0.30000000000000004 这种浮点误差。Calculator 技能用任意精度数学库解决了这个问题,支持加减乘除、乘方和括号,并正确处理运算符优先级(例如 2 ^ 3 ^ 2 = 512,乘方右结合)。

技能如何工作? AI 读取 SKILL.md 后,会进入 scripts/ 目录构建并执行计算:

cd scripts
npm run build
npm run calculate "1 + 4.5 * (3-6) / 5"   # 输出 -1.7

核心实现 calculator.ts 内部用"调度场算法"处理表达式解析,配合 big.js 保证精度。

这个技能还明确写清了边界:空表达式、括号不匹配、除零、非整数指数都会报错;不支持三角函数、变量和取模。把这些"做不到什么"写清楚,是 Skill 文档的专业细节——它能防止 AI 过度承诺。

4️⃣ 案例二:Jira CLI 技能——一个命令搞定工作项管理

Jira CLI 技能 展示了另一类 Skill 的写法:对接外部 CLI 工具。它教 AI 如何通过 jira 命令行完成完整的 Jira 工作流:

场景 典型命令
查看我名下的任务 jira issue list -a$(jira me)
创建高优先级 Bug jira issue create -tBug -s"App crashes on login" -yHigh --no-input
把工作项移入"进行中" jira issue move ISSUE-123 "In Progress"
查看当前冲刺进度 jira sprint list --current -a$(jira me)

上手只需三步前置准备:

  1. 安装 jira-cli 工具;
  2. 配置 API Token:export JIRA_API_TOKEN="your-token";
  3. 执行 jira init 完成初始化。

值得注意的是它的正文还整理了 Common Workflows(开始处理工作项、完成工作项、每日站会回顾)这类"组合拳"。AI 学会了单条命令还不够,教会它把命令串成工作流,才是 Skill 的真正价值。

5️⃣ 三步写出你自己的 SKILL.md(清单)

结合上面两个案例,创建新 Skill 只需三步:

第 1 步:建文件夹

在项目的 skills/ 目录下新建 skills/your-skill/,放入 SKILL.md;如果需要可执行能力,再建 scripts/ 子目录。

第 2 步:写前置元数据

name 取唯一短名;description 写清"做什么 + 何时触发",多列几种用户的问法;compatibility 声明依赖(如 Node.js、某 CLI 工具、环境变量)。

第 3 步:写正文说明书

按 When to Use → Prerequisites → Commands → Examples → Limitations 的顺序写。能用表格就用表格,能贴示例输出就贴示例输出——AI 读文档的效率和人一样,结构越清晰执行越准确。

写好之后,如果想分享给社区,可参考 CONTRIBUTING.md:把技能文件夹放入对应分类目录,并在 README.md 的 Agent Skills 章节登记链接,然后提交 Pull Request。

6️⃣ 常见问题

Q:Skill 和 Instructions 到底怎么选? Instructions 是"常驻上下文",适合编码规范;Skill 是"按需加载",适合封装完整能力。需要执行脚本、查询外部系统的任务,优先用 Skill。

Q:Skill 放在哪里才能生效? 按项目的 README.md "How to Use" 说明,工作区级 Skill 存放在包含 SKILL.md 的目录中,AI 助手会自动发现。

Q:除了这两个示例,还有哪些现成技能? 项目还收录了云方向的 Az CLI 技能(Azure 命令行操作)和 Azure Prices 技能(查询比较 Azure 服务定价),以及文档处理方向的 docx / pdf / pptx / xlsx 四件套(见 skills/documents/)。


小结:Agent Skills 的本质,是把"专家的操作手册"变成 AI 可以自主查阅加载的资产。从一个 SKILL.md 入手,用 Calculator 体会"技能 + 脚本"的组合,用 Jira CLI 体会"技能 + 外部工具"的组合,你就能把自己的团队经验封装成人人可用的可复用 AI 能力了。

如需获取完整项目,可执行:git clone https://gitcode.com/gh_mirrors/aw/awesome-copilot-agents

登录后查看全文
awesome-copilot-agents