1. 这不是“技能列表”而是一套可执行、可组合、可调试的智能体能力单元体系你点开 GitHub 搜索 “skills”刷出来几百个仓库标题里带着skills.sh、SKILL.md、superpower-skills、typesafe-ai-skills……第一反应可能是“又一个前端技能树可视化项目”或者“是不是某个新出的简历生成器”——错了。这背后根本不是静态知识图谱也不是求职话术包装而是一套正在快速演进的智能体Agent能力工程化实践范式。我从 2023 年底开始系统性地跟踪、测试、重构并落地了超过 47 个开源 skills 仓库覆盖数学建模、AI 漫剧生成、CodeX 辅助编程、Clade API 集成、前端自动化诊断等 6 类高频场景。实测下来真正能“跑起来、调得动、嵌得进、改得了”的 skills全部具备三个硬特征有明确输入/输出契约IO Contract、带可复现的本地执行入口如 skills.sh、内置最小化依赖声明通常在 SKILL.md 或 .skillrc 中。它不是文档不是教程更不是“学习清单”——它是可被调度器Scheduler、编排引擎Orchestrator或 LLM Agent Runtime 直接加载执行的原子能力模块。比如你在华为杯数学建模赛题中遇到“多目标非线性规划求解结果可视化报告段落生成”三步串联任务传统做法是写一个 300 行 Python 脚本而用 skills 思路你只需调用optimize-nlp-skills→plot-pareto-frontier→gen-report-section三个独立模块每个模块都自带参数校验、错误兜底和日志标记。它们之间不耦合可单独升级、灰度发布、AB 测试。这才是 skills 的真实价值锚点把 AI 工作流里的“功能”降维成“能力”再把“能力”升维成“可交付软件资产”。适合谁看如果你正卡在这些节点上这篇就是为你写的写完一个 Codex 插件但不知道怎么封装成通用能力别人没法复用在 Clade API 上调试半天发现每次都要重写请求构造逻辑看到tibo 清理 skills 方法这类搜索词却找不到具体操作路径下载了opencode-skills但skills.sh执行报错提示missing python3.11或no module named typer想给团队建一个内部 skills 库但纠结该用 YAML 还是 JSON Schema 定义能力契约。这不是概念科普而是我踩过坑、修过 bug、压测过并发、上线过生产环境的真实操作手册。下面所有内容都来自我本地~/skills/目录下 217 个已验证通过的 skills 实例以及与 12 位一线 Agent 开发者深度对齐后的共识实践。2. skills 的本质一种轻量级能力契约协议而非技能集合名词2.1 为什么叫 skills而不是 functions 或 plugins这是最容易误解的第一层。很多人看到skills就自动映射到“前端开发 skills”这类求职关键词或“superpower skills”这种营销话术——但技术语境下的skills其命名直接继承自LangChain 的 Tool 接口设计哲学并在 2024 年经由 Clade、Opencode、Codex Nature 等项目强化为事实标准。它的核心不是“你会什么”而是“你能被谁、以什么方式、安全可靠地调用”。举个最直白的例子一个curl -X POST https://api.example.com/v1/translate命令只是 HTTP 请求把它包装成translate-skills就必须定义输入{text: hello, src_lang: en, tgt_lang: zh}JSON Schema 校验输出{result: 你好, confidence: 0.92, model_used: nmt-v4.2}结构化返回元数据{timeout: 8000, retries: 2, auth_required: true}运行时约束执行入口skills.sh --text hello --src en --tgt zhCLI 可达提示真正的 skills 一定提供--help输出且 help 文本必须与 SKILL.md 中的 usage 示例完全一致。我见过 3 个高星仓库因 help 文本漏掉--dry-run参数说明导致下游 Agent 调用时静默失败。这个契约模型让 skills 天然适配三种主流调用方式CLI 直接执行./skills.sh ...适合本地调试、CI/CD 集成、运维脚本HTTP Server 模式skills.sh --serve启动 FastAPI 微服务适合跨语言调用、权限隔离、流量控制LLM Agent Runtime 注册如 Clade SDK 的clade.register_skill()由大模型根据 prompt 自动选择并填充参数。三者底层共享同一套 IO 定义只是暴露形态不同。这才是skills区别于普通脚本的核心——它不是“能做什么”而是“如何被安全、稳定、可审计地使用”。2.2 SKILL.md 不是 README而是能力说明书几乎所有高质量 skills 仓库都包含SKILL.md但它绝不是 GitHub 项目的常规 README。它的结构是强约定的我统计了 Top 50 skills 仓库92% 采用以下五段式Section必填说明实测典型错误Overview✓一句话定义能力边界如“本 skill 仅处理 ISO 8601 格式时间字符串的时区转换不支持自然语言时间解析”写成“强大、高效、智能的时间处理工具”——无法用于自动化校验Input Schema✓JSON Schema 片段含$schema,type,required,properties必须能被jsonschema.validate()直接加载用文字描述“输入为字典含 date 和 tz 字段”导致 Clade SDK 加载失败Output Schema✓同上且properties中必须声明error_code字段即使默认为 0用于统一错误路由忽略 error_codeAgent 收到{}时无法判断是成功还是异常Usage Examples✓至少 2 个 CLI 调用示例含成功与失败 case参数必须与 Input Schema 完全匹配示例用--date 2024-01-01Schema 却要求date_string字段名造成调用方困惑Dependencies✓列出python3.9,requests2.31.0,pydantic2.0等精确版本禁用*或~用pandas1.0导致在 M1 Mac 上因 numpy ABI 不兼容崩溃注意SKILL.md中的Input Schema不是装饰性内容。Clade API 在注册 skill 时会自动解析该 section 并生成 OpenAPI specOpencode CLI 在skills install时会校验 schema 是否合法Codex Nature 的 type-safe generator 更是直接据此生成 TypeScript 类型定义。没写对 SKILL.md等于没写 skills。我曾帮一个数学建模团队重构solve-lp-skills原版 SKILL.md 只有 Overview 和 Usage结果他们用 Clade 编排时LLM 经常传入{constraints: xy10}字符串而非{constraints: [{lhs: [x,y], rhs: 10, op: }]}结构化数组导致 solver 直接 panic。补全 Input Schema 后Clade 自动注入参数校验中间件错误率下降 98%。2.3 skills.sh统一执行入口不是可选脚本skills.sh是 skills 生态的“门面担当”99% 的高活跃仓库都提供它。但它不是简单的 shell wrapper而是承担四大职责参数标准化将--input-file data.json、--text hello、--config ./conf.yaml等不同来源参数统一归一化为 Python 可消费的dict依赖沙箱化检测当前环境是否满足 Dependencies 要求不满足则自动创建venv并安装skills.sh --install-deps执行模式路由支持skills.sh --run单次执行、skills.sh --serve启动 HTTP 服务、skills.sh --test运行内置单元测试可观测性注入自动记录start_time,end_time,input_hash,output_size,exit_code到 stdout供 Prometheus 或 ELK 采集。一个典型的skills.sh结构如下已脱敏#!/bin/bash # SPDX-License-Identifier: MIT # skills.sh for plot-pareto-frontier v1.2.0 set -e # 关键任何命令失败立即退出 # 1. 参数解析 INPUT_FILE OUTPUT_DIR./output CONFIG_FILE MODErun while [[ $# -gt 0 ]]; do case $1 in --input-file) INPUT_FILE$2 shift 2 ;; --output-dir) OUTPUT_DIR$2 shift 2 ;; --config) CONFIG_FILE$2 shift 2 ;; --serve) MODEserve shift ;; --help) echo Usage: $0 [--input-file FILE] [--output-dir DIR] [--config FILE] [--serve] exit 0 ;; *) echo Unknown option: $1 2 exit 1 ;; esac done # 2. 环境检查与沙箱准备 if ! command -v python3.11 /dev/null; then echo ERROR: python3.11 not found. Please install Python 3.11 2 exit 1 fi VENV_DIR.venv if [[ ! -d $VENV_DIR ]]; then python3.11 -m venv $VENV_DIR source $VENV_DIR/bin/activate pip install --upgrade pip pip install -r requirements.txt # 此处 requirements.txt 由 SKILL.md 生成 else source $VENV_DIR/bin/activate fi # 3. 模式分发 case $MODE in run) python -m main --input-file $INPUT_FILE --output-dir $OUTPUT_DIR --config $CONFIG_FILE ;; serve) python -m server --host 0.0.0.0 --port 8000 ;; *) echo Unknown mode: $MODE 2 exit 1 ;; esac注意skills.sh必须用set -e且所有路径使用相对路径如.venv而非/tmp/venv。我见过某cola-skills仓库因未加set -e当pip install失败后仍继续执行python -m main导致报错信息被掩盖排查耗时 3 小时。3. 四类主流 skills 架构解析从 CLI 工具到可编排微服务3.1 CLI-First Skills最简可行适合单机调试与 CI/CD这是入门门槛最低、部署成本最小的一类代表项目tibo/clean-skills、opencode/skills-cli。核心特征无网络依赖、无状态、输入输出均为文件或 STDIN/STDOUT。以tibo/clean-skills为例它解决的是“清理 Jupyter Notebook 中的 output 和 metadata保留可执行代码”的刚需。原始做法是手动打开 nbconvert 命令参数易错而它的 skills 实现是# skills.sh 内部调用 jupyter nbconvert --ClearOutputPreprocessor.enabledTrue \ --NoExecutePreprocessor.enabledTrue \ --to notebook $INPUT_FILE \ --output $OUTPUT_FILE但关键升级在于SKILL.md明确定义input_format: ipynboutput_format: ipynbskills.sh --dry-run会打印出完整命令但不执行方便审计skills.sh --validate会用nbformat.read()校验输入文件合法性这类 skills 的实操要点输入必须可溯源--input-file路径需支持file://和https://后者自动下载到临时目录输出必须可验证生成文件后自动运行sha256sum output.ipynb output.sha256错误必须可分类exit code 101表示 input format error102表示 execution timeout103表示 output validation failed。我在华为杯建模中大量使用此类 skills例如gen-latex-table-skills输入 CSV输出 LaTeX 表格代码直接cat result.csv | ./skills.sh --format latex table.tex无缝接入论文生成 pipeline。3.2 HTTP-Server Skills面向服务化支撑多语言调用当 skills 需被 Java、Go 或前端 JS 调用时CLI 模式就力不从心了。此时skills.sh --serve启动的 HTTP 服务成为标配。代表项目clade/api-skills、codex-nature/http-skills。其架构本质是在 skills.sh 内部启动一个轻量 Web 框架通常是 FastAPI将 CLI 的 main 函数包装为 endpoint。关键设计点路径即能力标识POST /v1/translate对应translate-skillsPOST /v1/optimize对应optimize-skills请求体严格遵循 Input SchemaFastAPI 自动生成 Pydantic Model并做 runtime 校验响应体强制包含 metadata除业务字段外必含{request_id: ..., timestamp: ..., skill_version: 1.2.0}一个典型 endpoint 实现FastAPIfrom fastapi import FastAPI, HTTPException from pydantic import BaseModel import json app FastAPI(titleTranslate Skill, version1.2.0) class TranslateRequest(BaseModel): text: str src_lang: str auto tgt_lang: str zh class TranslateResponse(BaseModel): result: str confidence: float model_used: str request_id: str timestamp: str app.post(/v1/translate, response_modelTranslateResponse) def translate(req: TranslateRequest): try: # 调用底层翻译函数 result _do_translate(req.text, req.src_lang, req.tgt_lang) return { result: result[text], confidence: result[score], model_used: result[model], request_id: generate_request_id(), timestamp: datetime.now().isoformat() } except Exception as e: raise HTTPException(status_code400, detailfTranslation failed: {str(e)})实操心得HTTP-Server Skills 的最大陷阱是CORS 和鉴权裸奔。我最初部署plot-pareto-frontier时前端直接跨域调用结果被恶意请求打满 CPU。后来强制加入--auth-token TOKEN参数skills.sh 启动时读取环境变量SKILL_AUTH_TOKEN并在 FastAPI middleware 中校验问题解决。3.3 LLM-Agent-Integrated Skills与大模型深度协同实现动态能力调度这是 skills 最前沿的应用形态代表项目clade/agent-skills、opencode/llm-skills。它不再由人显式调用而是由 LLM 根据用户 query 自动选择、参数填充、执行并解析结果。其技术栈关键组件Skill Registry一个 JSON 文件如skills-registry.json记录所有已注册 skills 的 name、description、input_schema、output_schemaTool Calling ParserLLM 输出 JSON-like text如{name: solve-lp, parameters: {A: [[1,2],[3,4]], b: [5,6]}}Parser 提取并校验Execution Bridge将 parsed parameters 转为skills.sh --run --A [[1,2],[3,4]] --b [5,6]并捕获 stdout难点在于LLM 的 hallucination 控制。我测试过 7 个主流模型Claude 3.5、GPT-4o、Qwen2.5发现它们在 skills 调用中存在三类高频错误参数类型错乱把b: [5,6]写成b: 5,6字符串 vs 数组字段名拼写错误constraint_matrix写成constraints_matrix必填字段遗漏maximize字段未传导致 solver 使用默认最小化。解决方案是在skills.sh --run中增加--strict-mode启用 Pydantic 的strictTrue校验并返回结构化 error message{ error_code: 400, error_type: validation_error, field_errors: [ {field: b, expected: list[float], received: str}, {field: maximize, reason: required field missing} ], suggestion: Please provide b as a JSON array and include maximizetrue/false }Clade SDK 会自动解析此 error并 prompt LLM 修正后重试。实测将单次调用成功率从 63% 提升至 91%。3.4 Hybrid SkillsCLI HTTP Agent 三位一体面向生产环境顶级 skills 项目必然支持三种模式如math-modeling-skills华为杯官方推荐库。它不是一个单一脚本而是一个可插拔架构math-modeling-skills/ ├── skills.sh # 统一入口分发到 cli/ http/ agent/ ├── cli/ │ └── main.py # CLI 模式主逻辑 ├── http/ │ └── server.py # FastAPI 服务 ├── agent/ │ └── clade_register.py # Clade SDK 注册逻辑 ├── SKILL.md # 全局能力契约 └── requirements.txt # 三模式共享依赖skills.sh的核心逻辑是case $MODE in run) python -m cli.main $ ;; serve) python -m http.server $ ;; register) python -m agent.clade_register $ ;; esac这种设计带来三大优势开发阶段用skills.sh --run快速验证逻辑测试阶段用skills.sh --serve启动本地服务Postman 调试上线阶段用skills.sh --register将 skill 注册到 Clade 控制台供 LLM Agent 调度我在数学建模比赛中部署solve-mip-skills时先用 CLI 模式跑通小规模数据再用 HTTP 模式压测并发100 QPS最后注册到 Clade让 LLM 根据题目描述自动选择 solver 并传参——整个 pipeline 从需求到上线不到 2 小时。4. 从零构建一个 production-ready skills以gen-matlab-code-skills为例4.1 需求拆解为什么需要这个 skills华为杯建模中常需将 Python 的优化结果如scipy.optimize输出转为 MATLAB 可执行的.m脚本供队友在 Simulink 中仿真。手动转换易错、难维护、无法版本化。目标输入 JSON 格式的优化结果输出结构清晰、带注释、可直接run的 MATLAB 代码。核心需求输入{x_opt: [1.2, 3.4], fval: -5.6, success: true, message: Optimization terminated successfully.}输出MATLAB 脚本含变量声明、注释、disp()输出约束不依赖 MATLAB 运行时纯文本生成支持中文注释4.2 SKILL.md 编写契约先行# gen-matlab-code-skills ## Overview Generate executable MATLAB script from optimization result JSON. Outputs .m file with variable assignment, comments, and result display. ## Input Schema json { $schema: https://json-schema.org/draft/2020-12/schema, type: object, required: [x_opt, fval, success], properties: { x_opt: { type: array, items: {type: number}, minItems: 1 }, fval: {type: number}, success: {type: boolean}, message: {type: string, default: }, solver: {type: string, default: scipy.optimize} } }Output Schema{ type: object, required: [matlab_code, file_size_bytes], properties: { matlab_code: {type: string}, file_size_bytes: {type: integer, minimum: 0}, generated_at: {type: string, format: date-time} } }Usage Examples# Success case echo {x_opt: [1.2, 3.4], fval: -5.6, success: true} | ./skills.sh --input-stdin # Failure case (missing x_opt) echo {fval: -5.6, success: true} | ./skills.sh --input-stdin # Returns exit code 101Dependenciespython3.9pydantic2.0jinja23.0 注意Input Schema 中 x_opt 的 minItems: 1 是硬约束防止空数组导致 MATLAB 语法错误Output Schema 的 file_size_bytes 用于后续 pipeline 校验生成质量。 ### 4.3 skills.sh 实现兼顾健壮性与可观测性 bash #!/bin/bash set -e INPUT_STDINfalse OUTPUT_FILE MODErun while [[ $# -gt 0 ]]; do case $1 in --input-stdin) INPUT_STDINtrue shift ;; --output-file) OUTPUT_FILE$2 shift 2 ;; --help) echo Usage: $0 [--input-stdin] [--output-file FILE] exit 0 ;; *) echo Unknown option: $1 2 exit 1 ;; esac done # 检查依赖 if ! command -v python3.9 /dev/null; then echo ERROR: python3.9 not found 2 exit 1 fi # 创建沙箱 VENV_DIR.venv if [[ ! -d $VENV_DIR ]]; then python3.9 -m venv $VENV_DIR source $VENV_DIR/bin/activate pip install --upgrade pip pip install pydantic jinja2 else source $VENV_DIR/bin/activate fi # 读取输入 if [[ $INPUT_STDIN true ]]; then INPUT_JSON$(cat) else echo ERROR: --input-stdin is required 2 exit 1 fi # 执行核心逻辑 RESULT$(python -c import sys, json, jinja2 from pydantic import BaseModel, ValidationError class InputModel(BaseModel): x_opt: list[float] fval: float success: bool message: str solver: str scipy.optimize try: data json.loads($INPUT_JSON) inp InputModel(**data) except ValidationError as e: print(json.dumps({error_code: 101, error: str(e)})) sys.exit(101) # 渲染 MATLAB 模板 template_str %% Generated by gen-matlab-code-skills v1.0.0 %% Solver: {{ solver }} %% Success: {{ success }} %% Optimal value: {{ fval }} %% Optimal point: [{{ x_opt|join(, ) }}] x_opt [{{ x_opt|join(, ) }}]; fval {{ fval }}; success {{ true if success else false }}; if success disp([Optimization succeeded. fval , num2str(fval)]); disp([x_opt , mat2str(x_opt)]); else disp([Optimization failed: , message]); end env jinja2.Environment() template env.from_string(template_str) output template.render( solverinp.solver, successinp.success, fvalinp.fval, x_optinp.x_opt, messageinp.message ) print(json.dumps({ matlab_code: output, file_size_bytes: len(output), generated_at: __import__(datetime).datetime.now().isoformat() })) ) # 解析结果并输出 if echo $RESULT | jq -e .error_code /dev/null; then echo $RESULT 2 exit $(echo $RESULT | jq .error_code) else if [[ -n $OUTPUT_FILE ]]; then echo $RESULT | jq -r .matlab_code $OUTPUT_FILE echo Wrote to $OUTPUT_FILE ($(echo $RESULT | jq .file_size_bytes) bytes) else echo $RESULT | jq -r .matlab_code fi fi实操细节使用jq解析 JSON避免 Bash 原生字符串处理的脆弱性Jinja2 模板直接内联在-c中避免外部文件依赖--input-stdin强制要求因输入数据通常来自上游 pipeline 的|管道错误码101对应 schema validation error与 SKILL.md 定义一致4.4 本地验证与 CI 集成编写test.sh进行三重验证#!/bin/bash # test.sh # Test 1: Valid input echo {x_opt: [1.2, 3.4], fval: -5.6, success: true} | ./skills.sh --input-stdin | jq -e .matlab_code /dev/null echo ✓ Valid input test passed # Test 2: Invalid input (missing x_opt) if ! echo {fval: -5.6, success: true} | ./skills.sh --input-stdin 21 | grep -q error_code.*101; then echo ✗ Invalid input test failed exit 1 fi echo ✓ Invalid input test passed # Test 3: Output size sanity check SIZE$(echo {x_opt: [1,2,3], fval: 0, success: true} | ./skills.sh --input-stdin | jq .file_size_bytes) if [[ $SIZE -lt 200 || $SIZE -gt 1000 ]]; then echo ✗ Output size out of range: $SIZE exit 1 fi echo ✓ Output size test passedCI 配置.github/workflows/test.ymlname: Test skills on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Python uses: actions/setup-pythonv5 with: python-version: 3.9 - name: Install dependencies run: | python -m pip install --upgrade pip pip install pytest jq - name: Run tests run: chmod x test.sh ./test.sh4.5 发布与注册从本地到 Clade 生产环境发布流程git tag v1.0.0并 pushskills.sh --register --clade-url https://clade.example.com --token $CLADE_TOKEN此命令由agent/clade_register.py实现Clade 控制台自动拉取SKILL.md生成 OpenAPI spec并分配skill_id: gen-matlab-code-12345注册后LLM Agent 即可调用{ name: gen-matlab-code-12345, parameters: { x_opt: [1.2, 3.4], fval: -5.6, success: true } }Clade 会自动校验 parameters 符合 Input Schema启动 sandboxed container 执行skills.sh --run捕获 stdout 并解析为 JSON返回结构化结果给 LLM整个过程对 LLM 完全透明它只关心“能不能解决问题”不关心“怎么解决”。5. 常见问题与实战排错指南那些文档里不会写的坑5.1 “skills.sh: command not found” —— 权限与路径的双重陷阱现象克隆仓库后cd skills-repo ./skills.sh报错command not found。原因分析权限缺失Linux/macOS 默认不赋予新文件执行权限chmod x skills.sh是必须步骤换行符污染Windows 编辑器保存的skills.sh含\r\nLinux bash 会报bad interpreter: /bin/bash^M解决方案# 一键修复macOS/Linux dos2unix skills.sh # 若未安装用 sed -i s/\r$// skills.sh chmod x skills.sh # 预防措施Git 配置自动转换 git config --global core.autocrlf input实操心得我在团队内部推行pre-commit hook每次 commit 前自动运行shfmt -w skills.sh格式化和shellcheck skills.sh静态检查杜绝低级错误。5.2 “ModuleNotFoundError: No module named xxx” —— 依赖隔离失效现象skills.sh --run报错找不到包但pip list显示已安装。根因skills.sh中的source .venv/bin/activate失败导致使用了系统 Python 而非虚拟环境。常见于.venv目录被.gitignore忽略CI 环境中未重建python3.9在系统 PATH 中不可见如 Ubuntu 22.04 默认只有python3.10排查步骤./skills.sh --install-deps强制重建 venv./skills.sh --debug在 skills.sh 开头加set -x查看实际执行路径检查which python输出是否指向.venv/bin/python终极方案在skills.sh中加入环境探测# 替代简单 source if [[ -f $VENV_DIR/bin/activate ]]; then source $VENV_DIR/bin/activate PYTHON_EXECUTABLE$VENV_DIR/bin/python else PYTHON_EXECUTABLEpython3.9 fi # 执行时显式指定解释器 $PYTHON_EXECUTABLE -m main $5.3 “HTTP 500 Internal Server Error” —— FastAPI 服务静默崩溃现象skills.sh --serve启动成功但curl http://localhost:8000/docs返回 500。调试方法查看skills.sh --serve的 stdout/stderr通常有pydantic.ValidationError堆栈检查SKILL.md的 Input Schema 是否与 FastAPI Model 完全一致字段名、类型、默认值用curl -X POST http://localhost:8000/v1/endpoint -H Content-Type: application/json -d {}触发最小化请求观察错误详情高频错误Schema 中{type: number}但 FastAPI Model 写成float应为Union[int, float]required字段在 Model 中设了 None导致校验跳过修复模板# 正确写法 class MyRequest(BaseModel): param_a: int param_b: Union[int, float] # 匹配 JSON Schema 的 number param_c: str Field(..., min_length1) # ... 表示 required5.4 “LLM never calls my skill” —— Registry 与 Discovery 失效现象Clade 控制台显示 skill 已注册但 LLM 始终不调用