指南：三步跑通腳本調(diào)用、依賴聲明與結(jié)構(gòu)驗證)
Agent Skills 實戰(zhàn)指南三步跑通腳本調(diào)用、依賴聲明與結(jié)構(gòu)驗證【免費下載鏈接】agentskillsSpecification and documentation for Agent Skills項目地址: https://gitcode.com/GitHub_Trending/ag/agentskills寫 AI Agent 時你是否希望它不只回答問題還能跑腳本、處理數(shù)據(jù)并且能自我檢查agentskills 項目正是 Agent Skills 這一開放規(guī)范的官方規(guī)格與文檔倉庫它定義了輕量的技能格式——一個技能就是一個包含SKILL.md的文件夾可附帶腳本、參考資料和模板被各類兼容的 AI 客戶端加載使用。本文按調(diào)用腳本 → 聲明依賴 → 驗證結(jié)構(gòu)的真實任務(wù)流帶你寫出一個真正能跑起來的技能。一個技能的三件套SKILL.md、腳本與資料技能的核心是一個文件夾結(jié)構(gòu)長這樣my-skill/ ├── SKILL.md # 必需元數(shù)據(jù)name、description 給 Agent 的指令 ├── scripts/ # 可選可執(zhí)行腳本 ├── references/ # 可選參考文檔 └── assets/ # 可選模板、資源文件這套開放格式已被眾多 AI 客戶端采用比如 Goose 客戶端假設(shè)你的技能里放了兩個腳本先列出它們能干什么、怎么調(diào)腳本用途調(diào)用方式scripts/check_config.sh檢查配置文件是否格式合法bash scripts/check_config.sh config.yamlscripts/build_report.py匯總原始數(shù)據(jù)并生成報告python3 scripts/build_report.py --format json --output report.json data.csv調(diào)用時有兩個關(guān)鍵約定用相對路徑所有路徑都從技能根目錄算起Agent 會自動解析不需要絕對路徑。先在SKILL.md里登記把腳本清單和調(diào)用命令寫進(jìn)說明文檔Agent 才知道這些東西存在。比如# 第一步檢查配置文件參數(shù)是要檢查的文件 bash scripts/check_config.sh $CONFIG_FILE # 第二步生成報告 # --format 指定輸出格式j(luò)son / csv / table # --output 報告寫入的文件不指定則打印到終端 # 最后一個參數(shù)是輸入的數(shù)據(jù)文件 python3 scripts/build_report.py --format json --output report.json data.csv快速上手三條命令跑通結(jié)構(gòu)驗證想確認(rèn)自己寫的技能結(jié)構(gòu)沒問題倉庫自帶的skills-ref參考庫就是干這個的。三步跑起來# 第 1 步拿到倉庫包含規(guī)范文檔與 skills-ref 工具 git clone https://gitcode.com/gh_mirrors/ag/agentskills cd agentskills# 第 2 步安裝驗證工具 cd skills-ref uv sync # 創(chuàng)建虛擬環(huán)境并安裝依賴 source .venv/bin/activate # 激活環(huán)境Windows 用 .venv\Scripts\Activate.ps1沒有 uv 也沒關(guān)系可以用pip install -e .替代。# 第 3 步驗證你的技能 skills-ref validate ./my-skill它做了什么檢查SKILL.md是否存在、frontmatter 是否合法、name是否與文件夾名一致、必填字段是否齊全。退出碼 0 表示通過退出碼 1 表示有問題并且會在終端逐條打印錯誤清單照著改即可。依賴聲明把購物單貼在文件頭部技能里的腳本要 import 第三方包怎么辦最省事的做法不是另寫一份清單文件而是把依賴清單直接寫在腳本頭部——就像給文件貼一張購物單運(yùn)行器照著單子在隔離環(huán)境里裝好再執(zhí)行。Python 社區(qū)已有對應(yīng)標(biāo)準(zhǔn)PEP 723 內(nèi)聯(lián)腳本元數(shù)據(jù)。# 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())運(yùn)行只需一條命令uv run scripts/fetch_report.py # uv 會讀取頭部購物單 → 建隔離環(huán)境 → 自動裝包 → 執(zhí)行腳本補(bǔ)充兩個技巧用 PEP 508 寫法釘版本如beautifulsoup44.12,5保證行為穩(wěn)定需要完全可復(fù)現(xiàn)時用uv lock --script生成鎖文件?？缯Z言依賴管理各語言各有什么招不同語言的購物單寫法不一樣但思路一致讓運(yùn)行器自己解決依賴技能目錄里不塞一堆清單文件。對照表如下語言依賴寫在哪怎么跑Python文件頭部 PEP 723 塊標(biāo)準(zhǔn)寫法uv run 腳本.pypipx run同樣支持Python現(xiàn)成工具不寫文件命令里帶版本uvx ruff0.8.0 check .、pipx run black24.10.0Node.js無需清單按需下載npx eslint9 --fix .、bunx eslint9 --fix .Go命令里直接寫包名版本go run 包路徑v1.2.3Rubybundler/inline在腳本內(nèi)聲明 gemruby 腳本.rbDeno / Bunimport 里直接寫npm:包名版本deno run/bun run缺包時運(yùn)行時自動安裝通用建議兩條版本號釘死npx pkg9.0.0比pkglatest可復(fù)現(xiàn)把環(huán)境前提寫進(jìn)SKILL.md如需要 Node.js 18必要時用規(guī)范的compatibility字段聲明別假設(shè) Agent 的環(huán)境里有什么。自檢確認(rèn)腳本和技能結(jié)構(gòu)都正確結(jié)構(gòu)層面skills-ref還有兩個命令配合使用# 以 JSON 輸出技能的元數(shù)據(jù)方便排查 frontmatter 解析問題 skills-ref read-properties ./my-skill # 把多個技能轉(zhuǎn)成 available_skills XML 塊可直接粘進(jìn) Agent 的系統(tǒng)提示詞 skills-ref to-prompt ./my-skill ./another-skill腳本層面Agent 靠讀取標(biāo)準(zhǔn)輸出和標(biāo)準(zhǔn)錯誤來決定下一步按下面幾條自檢腳本會好用很多不要有交互提示。Agent 運(yùn)行在非交互 shell 里腳本彈出請輸入目標(biāo)環(huán)境會永久卡死參數(shù)一律走命令行參數(shù)、環(huán)境變量或 stdin。提供--help。這是 Agent 認(rèn)識你腳本界面的第一入口把參數(shù)和示例寫清楚、寫短。結(jié)構(gòu)化輸出。stdout 輸出 JSON / CSV診斷信息放 stderr這樣輸出既能被 Agent 解析也能接jq、awk等工具。錯誤信息給出路。別說輸入無效要說清期望什么、收到什么、該怎么改。支持冪等與--dry-run。Agent 可能重試命令不存在則創(chuàng)建比重復(fù)即失敗更安全危險操作先預(yù)覽再執(zhí)行。收尾交付前對照這張清單SKILL.md含name與description且name與文件夾同名skills-ref validate ./my-skill通過腳本用相對技能根目錄的路徑調(diào)用并已在SKILL.md登記依賴要么寫在文件頭部、要么由運(yùn)行器按需拉取且版本已釘住腳本無交互提示、支持--help、輸出結(jié)構(gòu)化更多細(xì)節(jié)可參考倉庫內(nèi)的 腳本使用文檔、快速入門教程 和 skills-ref 源碼目錄?！久赓M下載鏈接】agentskillsSpecification and documentation for Agent Skills項目地址: https://gitcode.com/GitHub_Trending/ag/agentskills創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Agent Skills 實戰(zhàn)指南：三步跑通腳本調(diào)用、依賴聲明與結(jié)構(gòu)驗證
Agent Skills 實戰(zhàn)指南三步跑通腳本調(diào)用、依賴聲明與結(jié)構(gòu)驗證【免費下載鏈接】agentskillsSpecification and documentation for Agent Skills項目地址: https://gitcode.com/GitHub_Trending/ag/agentskills寫 AI Agent 時你是否希望它不只回答問題還能跑腳本、處理數(shù)據(jù)并且能自我檢查agentskills 項目正是 Agent Skills 這一開放規(guī)范的官方規(guī)格與文檔倉庫它定義了輕量的技能格式——一個技能就是一個包含SKILL.md的文件夾可附帶腳本、參考資料和模板被各類兼容的 AI 客戶端加載使用。本文按調(diào)用腳本 → 聲明依賴 → 驗證結(jié)構(gòu)的真實任務(wù)流帶你寫出一個真正能跑起來的技能。一個技能的三件套SKILL.md、腳本與資料技能的核心是一個文件夾結(jié)構(gòu)長這樣my-skill/ ├── SKILL.md # 必需元數(shù)據(jù)name、description 給 Agent 的指令 ├── scripts/ # 可選可執(zhí)行腳本 ├── references/ # 可選參考文檔 └── assets/ # 可選模板、資源文件這套開放格式已被眾多 AI 客戶端采用比如 Goose 客戶端假設(shè)你的技能里放了兩個腳本先列出它們能干什么、怎么調(diào)腳本用途調(diào)用方式scripts/check_config.sh檢查配置文件是否格式合法bash scripts/check_config.sh config.yamlscripts/build_report.py匯總原始數(shù)據(jù)并生成報告python3 scripts/build_report.py --format json --output report.json data.csv調(diào)用時有兩個關(guān)鍵約定用相對路徑所有路徑都從技能根目錄算起Agent 會自動解析不需要絕對路徑。先在SKILL.md里登記把腳本清單和調(diào)用命令寫進(jìn)說明文檔Agent 才知道這些東西存在。比如# 第一步檢查配置文件參數(shù)是要檢查的文件 bash scripts/check_config.sh $CONFIG_FILE # 第二步生成報告 # --format 指定輸出格式j(luò)son / csv / table # --output 報告寫入的文件不指定則打印到終端 # 最后一個參數(shù)是輸入的數(shù)據(jù)文件 python3 scripts/build_report.py --format json --output report.json data.csv快速上手三條命令跑通結(jié)構(gòu)驗證想確認(rèn)自己寫的技能結(jié)構(gòu)沒問題倉庫自帶的skills-ref參考庫就是干這個的。三步跑起來# 第 1 步拿到倉庫包含規(guī)范文檔與 skills-ref 工具 git clone https://gitcode.com/gh_mirrors/ag/agentskills cd agentskills# 第 2 步安裝驗證工具 cd skills-ref uv sync # 創(chuàng)建虛擬環(huán)境并安裝依賴 source .venv/bin/activate # 激活環(huán)境Windows 用 .venv\Scripts\Activate.ps1沒有 uv 也沒關(guān)系可以用pip install -e .替代。# 第 3 步驗證你的技能 skills-ref validate ./my-skill它做了什么檢查SKILL.md是否存在、frontmatter 是否合法、name是否與文件夾名一致、必填字段是否齊全。退出碼 0 表示通過退出碼 1 表示有問題并且會在終端逐條打印錯誤清單照著改即可。依賴聲明把購物單貼在文件頭部技能里的腳本要 import 第三方包怎么辦最省事的做法不是另寫一份清單文件而是把依賴清單直接寫在腳本頭部——就像給文件貼一張購物單運(yùn)行器照著單子在隔離環(huán)境里裝好再執(zhí)行。Python 社區(qū)已有對應(yīng)標(biāo)準(zhǔn)PEP 723 內(nèi)聯(lián)腳本元數(shù)據(jù)。# 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())運(yùn)行只需一條命令uv run scripts/fetch_report.py # uv 會讀取頭部購物單 → 建隔離環(huán)境 → 自動裝包 → 執(zhí)行腳本補(bǔ)充兩個技巧用 PEP 508 寫法釘版本如beautifulsoup44.12,5保證行為穩(wěn)定需要完全可復(fù)現(xiàn)時用uv lock --script生成鎖文件?？缯Z言依賴管理各語言各有什么招不同語言的購物單寫法不一樣但思路一致讓運(yùn)行器自己解決依賴技能目錄里不塞一堆清單文件。對照表如下語言依賴寫在哪怎么跑Python文件頭部 PEP 723 塊標(biāo)準(zhǔn)寫法uv run 腳本.pypipx run同樣支持Python現(xiàn)成工具不寫文件命令里帶版本uvx ruff0.8.0 check .、pipx run black24.10.0Node.js無需清單按需下載npx eslint9 --fix .、bunx eslint9 --fix .Go命令里直接寫包名版本go run 包路徑v1.2.3Rubybundler/inline在腳本內(nèi)聲明 gemruby 腳本.rbDeno / Bunimport 里直接寫npm:包名版本deno run/bun run缺包時運(yùn)行時自動安裝通用建議兩條版本號釘死npx pkg9.0.0比pkglatest可復(fù)現(xiàn)把環(huán)境前提寫進(jìn)SKILL.md如需要 Node.js 18必要時用規(guī)范的compatibility字段聲明別假設(shè) Agent 的環(huán)境里有什么。自檢確認(rèn)腳本和技能結(jié)構(gòu)都正確結(jié)構(gòu)層面skills-ref還有兩個命令配合使用# 以 JSON 輸出技能的元數(shù)據(jù)方便排查 frontmatter 解析問題 skills-ref read-properties ./my-skill # 把多個技能轉(zhuǎn)成 available_skills XML 塊可直接粘進(jìn) Agent 的系統(tǒng)提示詞 skills-ref to-prompt ./my-skill ./another-skill腳本層面Agent 靠讀取標(biāo)準(zhǔn)輸出和標(biāo)準(zhǔn)錯誤來決定下一步按下面幾條自檢腳本會好用很多不要有交互提示。Agent 運(yùn)行在非交互 shell 里腳本彈出請輸入目標(biāo)環(huán)境會永久卡死參數(shù)一律走命令行參數(shù)、環(huán)境變量或 stdin。提供--help。這是 Agent 認(rèn)識你腳本界面的第一入口把參數(shù)和示例寫清楚、寫短。結(jié)構(gòu)化輸出。stdout 輸出 JSON / CSV診斷信息放 stderr這樣輸出既能被 Agent 解析也能接jq、awk等工具。錯誤信息給出路。別說輸入無效要說清期望什么、收到什么、該怎么改。支持冪等與--dry-run。Agent 可能重試命令不存在則創(chuàng)建比重復(fù)即失敗更安全危險操作先預(yù)覽再執(zhí)行。收尾交付前對照這張清單SKILL.md含name與description且name與文件夾同名skills-ref validate ./my-skill通過腳本用相對技能根目錄的路徑調(diào)用并已在SKILL.md登記依賴要么寫在文件頭部、要么由運(yùn)行器按需拉取且版本已釘住腳本無交互提示、支持--help、輸出結(jié)構(gòu)化更多細(xì)節(jié)可參考倉庫內(nèi)的 腳本使用文檔、快速入門教程 和 skills-ref 源碼目錄?！久赓M下載鏈接】agentskillsSpecification and documentation for Agent Skills項目地址: https://gitcode.com/GitHub_Trending/ag/agentskills創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考