Agent Skills 实战：用 SKILL.md 与 CLI 给 AI Agent 装上可复用超能力

1. 为什么你的 AI Agent 总是“失忆”从重复提示词到技能包如果你正在用 Claude Code、Cursor 或者自己搭的 AI Agent 写代码大概率遇到过这个场景每次开新会话都要把同一套代码规范、同一份部署流程、同一个审查清单重新贴一遍。贴完还要解释“这个项目用 pnpm 不用 npm”“提交信息要遵循 Conventional Commits”“测试文件放在tests目录下”。一次两次还行项目一多、会话一长提示词越堆越厚Agent 的注意力反而被稀释真正关键的约束被淹没在噪音里。Agent Skills 想解决的就是这个问题。它是一套面向 AI Coding Agent 的模块化技能管理系统核心思路很直接把那些反复出现的提示词、脚本、检查清单封装成一个个自包含的技能单元每个单元用一个 SKILL.md 文件定义再通过 CLI 注册、加载、同步。你可以把它理解成给 AI Agent 装“插件”——装一次跨项目、跨机器都能用。这套东西适合谁三类人最受益一是同时维护多个项目的开发者需要统一编码规范二是团队技术负责人想让所有人和所有 Agent 遵循同一套流程三是喜欢折腾 Agent 工作流的玩家想把零散提示词沉淀成可版本管理的资产。下面我从 SKILL.md 的结构设计讲起一路走到 CLI 加载调用最后用 TaoToken 统一 Key 通道完成一次真实的技能注册与调用验证。2. TaoToken 前置统一 Key 与 API 通道让技能调用不迷路在动手写 SKILL.md 之前先把“通道”理清楚。Agent Skills 本身管的是技能的定义与分发但技能里如果包含需要调用大模型的动作——比如让 Agent 执行一次代码审查、生成一段迁移脚本——你就得有一个稳定的 API 入口。否则每个技能各自配置 Key、各自处理 base_url技能包一多密钥管理就成了灾难。我的做法是用 TaoToken 作为统一的 Key 与 API 通道。它提供一个兼容 OpenAI 风格的接口你只需要在环境变量里配一次所有技能脚本都能复用。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后到控制台创建 API Key 即可。具体来说你需要拿到两样东西一个是 API Key在控制台的 API Keys 页面生成另一个是 API 基地址固定为 https://taotoken.net/api 。拿到之后在 shell 里这样配置export TAOTOKEN_API_KEYsk-你的实际key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类工具它支持通过环境变量指定 Anthropic 兼容端点配置方式类似export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY$TAOTOKEN_API_KEY这样配的好处是技能脚本里不需要硬编码任何密钥换机器、换项目只要带上环境变量就行。后面我们写的 SKILL.md 里脚本会直接读取这两个变量保持技能包的可移植性。注意API Key 不要写进 SKILL.md 或任何会提交到 Git 的文件里。用环境变量或本地 .env并加入 .gitignore是底线。3. 可复制配置SKILL.md 骨架与 CLI 目录约定现在进入正题。一个 Agent Skill 的最小单元就是一个目录里面至少有一个 SKILL.md可选一个 scripts/ 目录放可执行脚本。目录结构长这样my-skills/ ├── skills-registry.json └── skills/ └── code-reviewer/ ├── SKILL.md └── scripts/ └── review.shskills-registry.json 是注册表记录你从哪些仓库添加了哪些技能。SKILL.md 是技能定义分两部分YAML frontmatter 给机器读Markdown 正文给人读。下面是一个可直接复制的 SKILL.md 骨架我以“代码审查助手”为例--- name: code-reviewer description: | 对指定文件或目录执行代码审查输出问题清单与改进建议。 触发词代码审查、review、检查代码 version: 1.0.0 license: MIT --- # Code Reviewer ## 用途 当用户要求对代码进行审查时本技能会读取目标文件 调用大模型 API 生成审查意见并按严重程度分类输出。 ## 使用方式 bash bash scripts/review.sh 目标文件或目录审查维度命名规范与可读性潜在的空指针与边界问题错误处理是否完整是否有明显的性能隐患输出格式按 [严重] / [建议] / [提示] 三级分类每条附带行号与修改建议。frontmatter 里的 name 是技能唯一标识description 里的“触发词”很关键——Agent 会根据这些词判断什么时候该加载这个技能。version 和 license 用于注册表管理和共享。 scripts/review.sh 的内容可以这样写注意它从环境变量读取 TaoToken 配置 bash #!/usr/bin/env bash set -euo pipefail TARGET${1:?请指定要审查的文件或目录} API_KEY${TAOTOKEN_API_KEY:?请先设置 TAOTOKEN_API_KEY} BASE_URL${TAOTOKEN_BASE_URL:-https://taotoken.net/api} CONTENT$(cat $TARGET) PAYLOAD$(jq -n \ --arg model claude-sonnet-4-20250514 \ --arg content $CONTENT \ {model: $model, max_tokens: 2048, messages: [{role: user, content: (请审查以下代码按[严重]/[建议]/[提示]分类输出\n $content)}]}) curl -sS $BASE_URL/v1/messages \ -H x-api-key: $API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d $PAYLOAD | jq -r .content[0].text这段脚本做了三件事读取目标文件内容、构造请求体、调用 TaoToken 的 messages 接口并提取返回文本。模型名你可以按需替换TaoToken 支持多种模型具体以控制台可用列表为准。CLI 的目录约定很简单所有技能放在 skills/ 下每个技能一个子目录目录名建议与 frontmatter 的 name 一致。注册表 skills-registry.json 由 CLI 自动维护你不需要手写。4. 验证请求一次技能注册与调用的完整动作配置写好了接下来做一次真实的注册加调用验证。我用 npx 方式安装技能管理器这样不污染全局环境npx skills add nicmeriano/agent-skills这条命令会把仓库里的技能包括 skills-manager 本身克隆到本地 skills/ 目录并写入注册表。执行完后你可以查看npx skills list输出会列出已安装技能及其来源。接下来把我自己写的 code-reviewer 技能注册进去。假设它已经在本地 skills/code-reviewer/ 目录下我需要把它保存到注册表npx skills save ./skills/code-reviewer保存成功后skills-registry.json 里会多一条记录包含来源路径和保存时间。然后做一次调用验证——直接运行技能脚本bash skills/code-reviewer/scripts/review.sh ./src/utils/parse.ts如果一切正常你会看到终端输出一段结构化的审查意见类似[严重] 第 23 行JSON.parse 未包裹 try-catch非法输入会直接抛异常导致进程退出。 [建议] 第 41 行变量名 data 过于宽泛建议改为 parsedConfig 以表达意图。 [提示] 第 58 行循环内重复调用 getConfig()可提到循环外减少开销。这说明技能定义、脚本执行、TaoToken API 通道三者已经打通。换一台机器时只要把仓库克隆下来执行npx skills sync所有注册过的技能会自动安装到位环境变量配好就能直接用。这就是“配置一次处处可用”的实际效果。如果你更习惯用 Claude Code 的交互方式也可以在配置好 ANTHROPIC_BASE_URL 后直接在会话里说“用 code-reviewer 审查 src/utils/parse.ts”Agent 会根据 SKILL.md 的触发词自动加载对应技能。想先验证模型通道是否通畅可以到模型对话页面发一条测试消息https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。5. 本篇常见错排查SKILL.md 不生效、CLI 找不到技能、API 报 401实际操作中下面几个坑我踩过你大概率也会遇到。SKILL.md 写了但 Agent 不加载。最常见的原因是 frontmatter 格式不对。YAML 对缩进和冒号后的空格很敏感description 如果用了多行写法必须用|或开头且后续行缩进一致。另一个原因是触发词没写进 descriptionAgent 匹配不到。检查方法用npx skills list确认技能在列表里再手动跑一次脚本确认功能正常。CLI 报 “skill not found”。多半是目录名和 frontmatter 的 name 不一致或者技能没执行 save 就调用了 sync。目录约定是 skills//SKILL.mdname 必须完全匹配。另外注意 save 时传的是路径不是技能名。API 返回 401 或 403。先确认 TAOTOKEN_API_KEY 是否导出到了当前 shell用echo $TAOTOKEN_API_KEY检查。如果是在脚本里用注意子进程是否继承了环境变量。还有一种情况是 Key 复制时带了空格或换行重新生成一个再试。401 基本就是 Key 问题403 则可能是模型名不在可用列表里到控制台确认一下。curl 返回空或超时。检查 BASE_URL 是否写成了https://taotoken.net/api注意末尾不要多加/v1路径拼接由脚本里的/v1/messages负责。如果公司网络有出口限制确认能正常访问该域名。sync 后技能丢失。skills-registry.json 如果被手动改坏sync 会失败。建议把它纳入 Git 管理但不要提交任何包含密钥的文件。恢复方法是重新 add 一次来源仓库。排障时如果拿不准是通道问题还是技能问题可以先用模型对话页面单独发一条请求确认 Key 和网络没问题再回到技能脚本层面排查。API Keys 管理入口在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。6. 把技能包当成代码资产来管理Agent Skills 真正有意思的地方不是它省了几次复制粘贴而是它把“AI 的能力配置”变成了可版本管理、可审查、可共享的代码资产。你可以给技能包建一个 Git 仓库用 PR 流程审查新增技能用 tag 标记版本用 CI 跑一遍脚本的冒烟测试。团队里谁改了审查规则diff 一目了然而不是散落在某个人的聊天记录里。如果你打算长期维护多个 Agent 工作流建议把 Coding Plan 也用起来它适合需要持续调用、频繁迭代编码任务的场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。配合技能包你可以做到技能定义在本地版本管理模型调用走统一通道换工具、换机器、换项目整套能力跟着走。最后留一个实用习惯每当你发现自己第三次复制同一段提示词时就停下来把它抽成一个 SKILL.md。三个月后你会感谢自己。