Agent Skills 实战指南：三步跑通脚本调用、依赖声明与结构验证

Agent Skills 实战指南三步跑通脚本调用、依赖声明与结构验证【免费下载链接】agentskillsSpecification and documentation for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/ag/agentskills写 AI Agent 时你是否希望它不只回答问题还能跑脚本、处理数据并且能自我检查agentskills 项目正是 Agent Skills 这一开放规范的官方规格与文档仓库它定义了轻量的技能格式——一个技能就是一个包含SKILL.md的文件夹可附带脚本、参考资料和模板被各类兼容的 AI 客户端加载使用。本文按调用脚本 → 声明依赖 → 验证结构的真实任务流带你写出一个真正能跑起来的技能。一个技能的三件套SKILL.md、脚本与资料技能的核心是一个文件夹结构长这样my-skill/ ├── SKILL.md # 必需元数据name、description 给 Agent 的指令 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选参考文档 └── assets/ # 可选模板、资源文件这套开放格式已被众多 AI 客户端采用比如 Goose 客户端假设你的技能里放了两个脚本先列出它们能干什么、怎么调脚本用途调用方式scripts/check_config.sh检查配置文件是否格式合法bash scripts/check_config.sh config.yamlscripts/build_report.py汇总原始数据并生成报告python3 scripts/build_report.py --format json --output report.json data.csv调用时有两个关键约定用相对路径所有路径都从技能根目录算起Agent 会自动解析不需要绝对路径。先在SKILL.md里登记把脚本清单和调用命令写进说明文档Agent 才知道这些东西存在。比如# 第一步检查配置文件参数是要检查的文件 bash scripts/check_config.sh $CONFIG_FILE # 第二步生成报告 # --format 指定输出格式json / csv / table # --output 报告写入的文件不指定则打印到终端 # 最后一个参数是输入的数据文件 python3 scripts/build_report.py --format json --output report.json data.csv快速上手三条命令跑通结构验证想确认自己写的技能结构没问题仓库自带的skills-ref参考库就是干这个的。三步跑起来# 第 1 步拿到仓库包含规范文档与 skills-ref 工具 git clone https://gitcode.com/gh_mirrors/ag/agentskills cd agentskills# 第 2 步安装验证工具 cd skills-ref uv sync # 创建虚拟环境并安装依赖 source .venv/bin/activate # 激活环境Windows 用 .venv\Scripts\Activate.ps1没有 uv 也没关系可以用pip install -e .替代。# 第 3 步验证你的技能 skills-ref validate ./my-skill它做了什么检查SKILL.md是否存在、frontmatter 是否合法、name是否与文件夹名一致、必填字段是否齐全。退出码 0 表示通过退出码 1 表示有问题并且会在终端逐条打印错误清单照着改即可。依赖声明把购物单贴在文件头部技能里的脚本要 import 第三方包怎么办最省事的做法不是另写一份清单文件而是把依赖清单直接写在脚本头部——就像给文件贴一张购物单运行器照着单子在隔离环境里装好再执行。Python 社区已有对应标准PEP 723 内联脚本元数据。# fetch_report.py —— 头部就是购物单 # /// script # dependencies [ # requests2.31.0, # HTTP 请求库钉住最低版本 # python-dateutil2.8.2, # 日期解析 # ] # requires-python 3.8 # 限定 Python 最低版本 # /// import requests resp requests.get(https://example.com/data.json) print(resp.json())运行只需一条命令uv run scripts/fetch_report.py # uv 会读取头部购物单 → 建隔离环境 → 自动装包 → 执行脚本补充两个技巧用 PEP 508 写法钉版本如beautifulsoup44.12,5保证行为稳定需要完全可复现时用uv lock --script生成锁文件。跨语言依赖管理各语言各有什么招不同语言的购物单写法不一样但思路一致让运行器自己解决依赖技能目录里不塞一堆清单文件。对照表如下语言依赖写在哪怎么跑Python文件头部 PEP 723 块标准写法uv run 脚本.pypipx run同样支持Python现成工具不写文件命令里带版本uvx ruff0.8.0 check .、pipx run black24.10.0Node.js无需清单按需下载npx eslint9 --fix .、bunx eslint9 --fix .Go命令里直接写包名版本go run 包路径v1.2.3Rubybundler/inline在脚本内声明 gemruby 脚本.rbDeno / Bunimport 里直接写npm:包名版本deno run/bun run缺包时运行时自动安装通用建议两条版本号钉死npx pkg9.0.0比pkglatest可复现把环境前提写进SKILL.md如需要 Node.js 18必要时用规范的compatibility字段声明别假设 Agent 的环境里有什么。自检确认脚本和技能结构都正确结构层面skills-ref还有两个命令配合使用# 以 JSON 输出技能的元数据方便排查 frontmatter 解析问题 skills-ref read-properties ./my-skill # 把多个技能转成 available_skills XML 块可直接粘进 Agent 的系统提示词 skills-ref to-prompt ./my-skill ./another-skill脚本层面Agent 靠读取标准输出和标准错误来决定下一步按下面几条自检脚本会好用很多不要有交互提示。Agent 运行在非交互 shell 里脚本弹出请输入目标环境会永久卡死参数一律走命令行参数、环境变量或 stdin。提供--help。这是 Agent 认识你脚本界面的第一入口把参数和示例写清楚、写短。结构化输出。stdout 输出 JSON / CSV诊断信息放 stderr这样输出既能被 Agent 解析也能接jq、awk等工具。错误信息给出路。别说输入无效要说清期望什么、收到什么、该怎么改。支持幂等与--dry-run。Agent 可能重试命令不存在则创建比重复即失败更安全危险操作先预览再执行。收尾交付前对照这张清单SKILL.md含name与description且name与文件夹同名skills-ref validate ./my-skill通过脚本用相对技能根目录的路径调用并已在SKILL.md登记依赖要么写在文件头部、要么由运行器按需拉取且版本已钉住脚本无交互提示、支持--help、输出结构化更多细节可参考仓库内的 脚本使用文档、快速入门教程 和 skills-ref 源码目录。【免费下载链接】agentskillsSpecification and documentation for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/ag/agentskills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考