Agent Skills技能库设计：从任务上下文到生产级智能体实践

实际使用大模型智能体时最容易被低估的问题不是模型能力而是任务上下文准备。以 agent-skills 这类项目为例它看起来像一组 Markdown 文件本质上却是一种工程约定把可复用的任务知识、工具命令和约束条件拆成独立技能让智能体在遇到对应任务时按需加载而不是把所有规则一次写进系统提示词。这个思路对写脚本、生成文档、做代码审查、处理运维巡检都很实用。下面围绕 agent-skills 的常见设计方式从问题出发设计一个最小技能库并把它接入本地 Agent 工作流最后给出生产环境需要补上的安全、版本和排查方案。1. 先理解 Agent Skills 要解决什么问题1.1 一次失败任务暴露的痛点假设你让智能体生成一份项目周报。为了拿到符合要求的报告你会在提示词里写清模板结构、要包含哪些字段、语气要求、风险怎么写、输出格式是什么。第一次运行可能勉强可用但只要模板调整一次或者任务从“周报”变成“复盘报告”你就要重新写一整段提示词。更麻烦的是当提示词超过一定长度后模型对规则的理解会变得不稳定。它可能记得“时间范围”写在第二段却忘记“风险”这一节要写“影响等级”。这类问题的根源不是大模型能力不足而是任务知识放错了位置。任务知识来自团队规范、历史模板、工具用法和领域经验它们应当是独立维护的资产而不是每次对话里临时粘贴的长文本。agent-skills 这一类技能库核心作用就是把这些资产拆分出来让智能体在需要时加载对应技能。在实际项目里观察一次失败任务通常能看到三个共同现象模型“知道”任务是什么但不清楚团队期望的具体产出格式。提示词里写了太多规则模型无法判断哪些规则对这个任务真正重要。任务需要调用脚本或命令时模型不知道命令入口、参数和失败处理方式。技能库把这三个问题分别用“任务说明”“步骤清单”“工具声明”来解决。1.2 Skill、Prompt、Tool、Plugin 的区别很多团队刚开始做 Agent 时会把 Skill 和 Prompt、Tool、Plugin 混为一谈。它们有重叠但定位不同。维度PromptToolSkillPlugin核心用途指导模型当前对话行为给模型提供外部能力面向任务的能力包扩展分发单元是否可执行否是可包含脚本与工具入口通常可安装复用方式复制文本注册函数或命令目录或文件级加载安装后全局生效维护粒度低易重复中按函数维护高按任务维护中按产品维护失败影响回答质量下降单次调用失败当前技能不可用可能影响整个环境从这张表能看出Skill 处于 Prompt 和 Tool 之间又具备 Plugin 的分发特性。一个典型 Skill 至少包含三部分任务描述、执行步骤、可调用工具。任务描述告诉模型“什么场景下使用”执行步骤告诉模型“怎么做”工具声明告诉模型“可以调用哪些命令和脚本”。它比 Prompt 更结构化比 Tool 更贴近业务目标。1.3 agent-skills 这类仓库的定位Addy Osmani 在过去很多年里一直活跃在工程效率、前端性能和浏览器工具链方向所以 agent-skills 被关注并不让人意外。从项目名来判断这大概率是一个按技能组织的开源仓库用于展示如何为智能体准备可复用技能而不是一个必须安装的运行时框架。使用这类仓库时正确姿势不是把仓库里的文件原样复制进项目而是把它当作参考样本看作者如何写SKILL.md如何描述技能触发条件如何组织示例脚本然后抽取其中符合自己团队习惯的部分改造成自己的技能清单。每个团队的模板、工具链和安全要求都不同能直接复用的是设计思路不是文件内容。具体仓库支持哪些目录字段要以该仓库的 README 或官方示例为准。2. 设计技能库之前先定好目录和元信息约定2.1 目录结构为什么一个技能必须是一个目录如果只是整理提示词用一个 Markdown 文件就够了。但技能往往还包含脚本、参考样例、测试数据和约束声明所以一个技能应该是一个目录。目录结构可以按下面这种常见方式组织agent-skills-demo/ skills/ generate-report/ SKILL.md scripts/ generate_report.py references/ input-example.json output-example.md tests/ fixtures/ input.json bad.json run_tests.sh code-review/ SKILL.md scripts/ review.py references/ review-rules.md使用目录有三个好处。第一逻辑隔离。每个技能有自己的文档、脚本和测试修改时不会影响其他技能。第二版本控制友好。可以单独查看一个技能的历史变更也可以在 PR 里专门审查这个技能。第三权限控制方便。生产环境可以只给某个技能开放有限的命令执行权限而不是放行所有脚本。2.2 SKILL.md 是技能的大脑每个技能目录里最核心的文件是SKILL.md。它承担两个职责让模型判断“这个任务是否属于该技能”以及让模型知道“这个技能如何执行”。一个可用的SKILL.md可以分成元信息和正文两部分。元信息放在文档头部常见做法是使用 YAML 格式--- name: generate-report description: 根据任务输入生成结构化 Markdown 报告 version: 1.0.0 when_to_use: 用户需要生成周报、月报、项目进展说明 allowed_tools: - python3 - cat env: REPORT_OUTPUT_DIR: output/reports ---这里的description是模型做技能选择时的判断依据。它不能写得太模糊比如“处理报告”就不够要写清楚输入是什么、输出是什么、触发条件是什么。when_to_use用来补充正例和反例例如“当用户只是询问报告进度时不要使用本技能”。元信息后面的正文通常包括几个固定小节目标这个技能最终产出什么。输入需要哪些文件或参数格式是什么。步骤从输入到输出的操作顺序。输出格式模型应该生成或脚本应该生成的结构。约束不能做什么需要遵守哪些边界。这些内容不是装饰。步骤写得越明确模型在执行时就越少依赖自己的猜测。训练模型时它可能见过很多“周报”样例但它不知道你所在团队的报告模板长什么样因此必须通过技能正文告诉它。2.3 依赖声明不能只写提示词很多技能在本地能跑通换一台机器就失败原因是没有声明依赖。技能里的脚本依赖什么 Python 版本、有没有第三方包、需要哪些环境变量都应该在技能目录里明确写出。可以在scripts/requirements.txt里声明 Python 依赖jinja23.1.4也可以在SKILL.md里增加“依赖”小节## 依赖 - 运行时Python 3.10 - Python 包见 scripts/requirements.txt - 环境变量 - REPORT_OUTPUT_DIR报告输出目录默认 output/reports - 命令python3、cat这一步非常重要。智能体在执行技能时如果发现命令不存在或依赖缺失它应该能通过依赖声明快速定位问题而不是反复试错。依赖声明也不需要很复杂最少要覆盖运行时、第三方包、环境变量和可执行命令。3. 从空目录开始实现一个最小技能库3.1 环境准备在开始前先确认本地环境。下面以 macOS 或 Linux 环境为例使用 Python 3 标准库避免引入额外安装负担。python3 --version git --version然后创建技能目录mkdir -p ~/workspace/agent-skills-demo/skills/generate-report/{scripts,references,tests/fixtures} cd ~/workspace/agent-skills-demo这里创建的是一个最小演示项目。如果你本机已经安装了支持 Agent Skills 的工具也可以把目录放到对应工具的技能识别路径下。没有现成 Agent 工具时用 shell 脚本模拟调度即可。3.2 创建 generate-report 技能在skills/generate-report/SKILL.md中写入以下内容--- name: generate-report description: 根据 JSON 任务输入生成 Markdown 项目周报 version: 1.0.0 when_to_use: 用户要求生成项目周报、月报、进展汇总时 allowed_tools: - python3 - cat env: REPORT_OUTPUT_DIR: output/reports --- # generate-report ## 目标 读取任务输入文件输出符合团队模板的 Markdown 周报。 ## 输入 - input_fileJSON 文件结构见 references/input-example.json。 - output_file可选默认输出到环境变量 REPORT_OUTPUT_DIR。 ## 步骤 1. 运行 python3 scripts/generate_report.py --input $input_file --output $output_file。 2. 检查脚本退出码只有退出码为 0 时才表示成功。 3. 将生成报告的文件路径和内容摘要返回给用户。 ## 输出格式 报告必须包含以下章节 - 标题 - 时间范围 - 完成项 - 风险 - 下一步计划 ## 约束 - 不修改原始输入文件。 - 不要生成超出一页的长报告。 - 输入文件中缺少字段时必须报错而不是猜测内容。这个文件同时承担“触发条件”“执行说明”“输出约束”三个职责。when_to_use和description帮助模型选择技能步骤部分帮助模型调用脚本约束部分防止生成不可控内容。3.3 编写可执行工具脚本技能如果只有文字说明本质上还是一个复杂 Prompt。要给技能增加确定性最好提供一个可执行脚本。下面用一个 Python 脚本读取 JSON生成 Markdown 报告。在skills/generate-report/scripts/generate_report.py中写入#!/usr/bin/env python3 import argparse import json import sys from pathlib import Path def validate_input(data): required [project, range, completed, risks, next_plan] missing [key for key in required if key not in data] if missing: raise ValueError(fmissing required keys: {missing}) return data def render(data): lines [] lines.append(f# 项目周报{data[project]}) lines.append() lines.append(f## 时间范围{data[range]}) lines.append() lines.append(## 完成项) for item in data[completed]: lines.append(f- {item}) lines.append() lines.append(## 风险) if data[risks]: for risk in data[risks]: lines.append(f- {risk}) else: lines.append(- 无) lines.append() lines.append(## 下一步计划) for item in data[next_plan]: lines.append(f- {item}) return \n.join(lines) \n def main(): parser argparse.ArgumentParser(descriptiongenerate markdown report) parser.add_argument(--input, requiredTrue, helpinput JSON file) parser.add_argument(--output, helpoutput markdown file) args parser.parse_args() try: with open(args.input, r, encodingutf-8) as f: data json.load(f) validate_input(data) report render(data) if args.output: output_path Path(args.output) output_path.parent.mkdir(parentsTrue, exist_okTrue) output_path.write_text(report, encodingutf-8) print(fREPORT_OK {output_path}, filesys.stderr) else: print(report) except Exception as exc: print(fREPORT_ERROR {exc}, filesys.stderr) sys.exit(1) if __name__ __main__: main()这个脚本有几个设计点值得注意。第一使用标准库argparse和json不依赖第三方包降低环境成本。第二validate_input显式检查必填字段缺失时报错而不是生成一份内容残缺的报告。第三成功和失败信息写到 stderr标准输出只保留报告内容。这样 Agent 在捕获输出时可以区分报告正文和执行状态。同时创建输入样例skills/generate-report/references/input-example.json{ project: 订单服务迁移, range: 2025-04-07 至 2025-04-11, completed: [ 完成订单表结构评审, 完成迁移方案第一版 ], risks: [ 历史数据量较大迁移耗时可能超预期 ], next_plan: [ 启动订单服务灰度验证, 补充回滚方案 ] }3.4 用配置文件声明运行时参数脚本和文档都准备好了接着用配置文件声明技能运行时的参数。最常见的配置文件是 YAMLskills: generate-report: version: 1.0.0 command_timeout_seconds: 30 env: REPORT_OUTPUT_DIR: output/reports allowed_tools: - python3 - cat这里的command_timeout_seconds是技能脚本的超时时间。设置太短复杂报告生成到一半会被终止设置太长Agent 会长时间卡在一个失败命令上。allowed_tools是命令白名单用于限制技能在特定环境下可以调用的命令降低安全风险。参数含义常见值调大的影响调小的影响command_timeout_seconds单条命令最大执行秒数30容忍慢脚本但故障时卡顿更久更快暴露问题但可能误杀正常任务env技能运行需要的环境变量按技能要求可传递更多配置但容易暴露敏感信息环境更干净但可能缺少配置allowed_tools命令白名单python3、cat技能更灵活但攻击面变大更安全但可用命令受限这些参数没有绝对最优值要看任务耗时和部署环境。生产环境建议先给宽一点观察日志后再逐步收紧。4. 把技能接入 Agent 工作流4.1 三种加载方式技能目录建好后需要让 Agent 能发现并加载它。常见有三种方式。第一种是项目内自动发现。Agent 启动时扫描项目根目录下的skills/目录自动注册每个技能。这种方式适合个人项目和小团队配置成本最低。第二种是显式注册。在 Agent 的配置文件中声明技能路径例如agent: skills_paths: - ./skills - /shared/team-skills这种方式适合多个项目共享同一套技能库也可以把团队公共技能放在独立仓库里。第三种是远程拉取。技能库放在 Git 仓库中通过 Agent 插件机制或包管理器拉取。适合团队级别维护变更可以走 PR 审查。选择哪种方式取决于技能变更多频繁。技能经常调整时本地目录更方便技能需要跨项目统一管理时独立仓库加版本号更合适。4.2 在系统提示词中如何引用技能很多人的直觉是把整个SKILL.md塞进系统提示词。这样做的缺点是占用大量上下文而且技能很多时无法全部放入。更合适的做法是让系统提示词只维护一份技能清单每个技能给出一行描述真正的规则放在技能文件里。你可以使用以下技能。只有任务符合技能描述时才调用对应技能。 - generate-report生成项目周报或进展报告根据 JSON 输入生成 Markdown。 - code-review对指定目录或分支进行代码审查输出风险清单和改进建议。 调用技能前先读取该技能目录下的 SKILL.md并严格按照里面定义的步骤执行。这种设计把“有哪些技能”和“技能怎么做”分离。系统提示词保持精简模型在需要时读取技能详情。如果 Agent 框架支持自动读取技能描述这一层可以自动生成无需手写。4.3 用本地 CLI 模拟技能调度没有现成 Agent 工具时可以用一个简单的 shell 脚本演示技能调度。在项目根目录创建agent_skill.sh#!/usr/bin/env bash set -euo pipefail QUERY$1 INPUT_FILE$2 SKILL_DIRskills/generate-report OUTPUT_DIRoutput/reports mkdir -p $OUTPUT_DIR if [[ $QUERY *周报* || $QUERY *报告* ]]; then echo [skill] generate-report selected 2 python3 $SKILL_DIR/scripts/generate_report.py \ --input $INPUT_FILE \ --output $OUTPUT_DIR/weekly-report.md cat $OUTPUT_DIR/weekly-report.md else echo NO_MATCH exit 0 fi这个脚本定义了一个最简单的路由规则当用户输入包含“周报”或“报告”时选择generate-report技能否则不匹配。真实 Agent 会基于description做语义匹配原理类似但这里用关键词模拟是为了让演示可执行、可见证。给脚本增加执行权限chmod x agent_skill.sh4.4 运行验证与预期输出现在用输入样例验证整个流程./agent_skill.sh 生成项目周报 skills/generate-report/references/input-example.json预期输出为[skill] generate-report selected REPORT_OK output/reports/weekly-report.md # 项目周报订单服务迁移 ## 时间范围2025-04-07 至 2025-04-11 ## 完成项 - 完成订单表结构评审 - 完成迁移方案第一版 ## 风险 - 历史数据量较大迁移耗时可能超预期 ## 下一步计划 - 启动订单服务灰度验证 - 补充回滚方案注意REPORT_OK来自 stderr终端里可能显示在 stdout 之前。这是正常的因为脚本把执行状态输出到 stderr把报告正文输出到 stdout。注意不要只验证技能能生成一次正确结果还要验证错误路径。Agent 在真实环境中会遇到缺字段、文件不存在、权限错误等情况脚本必须给出可读错误信息。再测试错误输入echo {project: 缺少字段} /tmp/bad-input.json ./agent_skill.sh 生成项目周报 /tmp/bad-input.json预期输出为报错信息且脚本退出码为 1[skill] generate-report selected REPORT_ERROR missing required keys: [range, completed, risks, next_plan]有了可复现的预期输出后续排查就能对照执行。5. 常见问题、参数速查与排查路径5.1 关键参数速查表技能配置中容易出错的参数主要在SKILL.md元信息和运行时配置中。参数含义常见值错误表现description技能描述供模型选择动词开头写明触发条件描述太宽泛模型不调用或误用when_to_use使用场景边界正例和反例缺失时模型判断不稳定version技能版本1.0.0无法区分变更前技能allowed_tools允许执行的命令python3、cat命令存在但不在白名单时执行失败env环境变量REPORT_OUTPUT_DIR脚本找不到输出目录command_timeout_seconds命令超时时间30长任务被中途终止output_file输出文件路径由参数传入未创建父目录导致写入失败参数表可以贴在技能库根目录的 README 中也可以作为团队内部约定。重点不是记住每个参数而是知道参数变更后可能引发什么现象。5.2 常见症状与可能原因实际运行中技能没有按预期工作通常不是模型“太笨”而是配置或环境问题。下面是一些常见症状。问题现象可能原因检查方式处理建议技能从未被调用description 太泛模型无法匹配查看 Agent 日志中的工具调用记录改写描述增加触发关键词和反例技能被错误调用when_to_use 边界不清晰查看模型选中技能时的理由增加不得使用该技能的场景脚本报错但 Agent 返回成功脚本退出码未检查手动执行脚本看调用方是否捕获退出码统一约定退出码 0 成功非 0 失败生成的报告缺字段输入 JSON 缺字段但脚本未校验运行 validate_input 或用样例测试在脚本中显式校验必填字段找不到脚本文件路径配置错误使用find . -name generate_report.py在 SKILL.md 中使用相对路径命令不在白名单allowed_tools 未配置 python3检查运行时配置将所需命令加入白名单排查这些症状时不要一上来就怀疑模型先按“环境问题、配置问题、脚本问题”的顺序排除。5.3 排查顺序一个可复用的排查套路如下检查触发条件。先问“模型是否选对了技能”。如果技能根本没被选中问题在description或系统提示词而不是脚本。检查输入文件。使用python3 -m json.tool test.json验证输入 JSON 是否合法。检查路径和权限。执行ls -l scripts/确认脚本存在且有执行权限。检查依赖。尝试直接运行脚本观察是否缺少模块或命令。检查退出码和 stderr。用echo $?查看退出码用重定向保存 stderrpython3 scripts/generate_report.py --input test.json --output out.md 2err.log cat err.log检查 Agent 配置。确认技能路径、白名单、超时时间是否生效。这套顺序适用于大多数技能故障。它把问题从“外部不可控的模型行为”逐步缩小到具体的文件和参数减少无目标试错。5.4 日志与调试建议技能脚本需要输出足够的信息。这里有一个实用原则stdout 用于业务结果stderr 用于执行状态和错误信息。上面示例中的REPORT_OK和REPORT_ERROR都使用了 stderr。调试脚本时可以开启 shell 的详细模式bash -x agent_skill.sh 生成项目周报 skills/generate-report/references/input-example.json-x会打印每一步命令和参数能很快看到是路径问题还是命令参数问题。脚本进入生产后建议把 stderr 重定向到日志文件并保留最近几次调用记录方便回查。注意Agent 的故障排查顺序天然比普通程序多一层先怀疑模型是否选错了技能再怀疑技能内部逻辑。技能写错了还能修模型选错技能时首先要检查描述写得是否足够明确。6. 生产环境使用 agent-skills 的最佳实践6.1 学习环境与生产环境的差异本地试验时技能脚本可以随意读文件、执行命令、不设超时。生产环境必须区分对待。维度学习环境生产环境脚本执行直接在本机运行放入受限容器或沙箱命令权限放开所有命令使用白名单最小权限密钥管理写进 SKILL.md使用环境变量或密钥管理系统日志打印到终端集中采集、带 trace id超时可以不设必须设置防止命令卡死技能变更直接改文件走代码审查和版本发布回滚手动恢复通过版本控制快速回滚测试只测试成功路径成功、失败、边界都覆盖这块最容易踩的坑是把本地实验方式直接搬到生产。本地脚本读取家目录文件没问题放到 Agent 服务里就可能成为安全漏洞。6.2 版本管理与变更审查技能是代码。只要脚本、描述或模板发生变化就应该有版本记录。推荐在技能目录中维护CHANGELOG.md# Changelog ## [1.1.0] - 2025-04-11 - 增加必填字段校验 - 输出文件自动创建父目录 ## [1.0.0] - 2025-04-07 - 初始版本支持基础周报生成技能变更要走最小审查流程修改前说明变更原因修改后附上输入输出样例对比。描述类变更可能影响模型选择脚本变更可能影响执行结果两者都值得被团队看到。如果技能库属于多人协作建议每个技能都配套测试用例至少有正常输入、缺少字段输入和空输入三个用例。6.3 安全边界与权限约束Agent 技能与普通脚本相比多了“模型自动执行”这一步因此安全边界更严格。第一条原则是禁止模型直接执行任意 shell。技能脚本应该只接受固定参数不在脚本中拼接用户输入后执行。例如不要写python3 -c import os; os.system($USER_INPUT)这种写法会把用户输入变成命令执行入口很容易被注入。推荐做法是脚本只接收文件路径或固定选项所有需要执行的命令都写在脚本内部而不是从外部传入。第二条原则是秘密不入库。数据库密码、API Key、云服务凭证不要写进SKILL.md或配置仓库。使用环境变量注入并在运行时配置中把敏感字段标记为不可打印。第三条原则是记录所有工具调用。生产环境的 Agent 需要记录“什么时间、选择了哪个技能、执行了什么命令、消耗了多少 token”这样一旦出现问题可以还原调用链。6.4 发布前检查清单新技能上线前可以用下面这个清单快速过一遍。检查项确认内容目录结构是否包含 SKILL.md、scripts、references、tests元信息description 是否明确when_to_use 是否有反例输入样例是否有完整输入文件和预期输出文件脚本测试是否覆盖成功路径和错误路径依赖声明是否列出运行时、包、环境变量超时配置是否设置 command_timeout_seconds权限控制allowed_tools 是否最小化日志输出执行状态是否写入 stderr错误处理缺少字段时是否明确报错秘密检查SKILL.md 和配置中是否有明文密钥回滚方案是否清楚上一个可用版本这份清单不一定完整但能覆盖大多数技能上线前的问题。生产环境还可以在此基础上增加代码签名、镜像扫描、审计日志等环节。7. 扩展方向从技能库到技能编排7.1 多技能如何组合单个技能只能解决单一任务。真实工作流往往需要多个技能接力。例如“生成上线报告”可能先调用“数据采集”技能再调用“报告生成”技能最后调用“审查”技能。多技能组合时需要明确中间产物。一个简单约定是每个技能只负责一件事输出写到约定目录下一个技能从该目录读取。下面是一个示意workflow: - skill: collect-data output: artifacts/data.json - skill: generate-report input: artifacts/data.json output: artifacts/report.md - skill: review-report input: artifacts/report.md这种方式比让一个技能完成所有步骤更容易测试和维护。如果某个技能出错只需要重跑从该技能开始的后续流程。7.2 与现有工具链集成技能库可以像普通代码仓库一样接入 CI。每次修改技能目录后自动运行脚本测试、检查 Markdown 格式、扫描文件中是否包含密钥。还可以在 Agent 的配置中心维护技能版本通过独立仓库发布技能包其他项目按版本引用。如果技能已经沉淀得比较稳定也可以考虑把它转成团队内部工具甚至封装成命令行工具供人类开发者和 Agent 共用。这样技能不再是 Agent 专属资产而是团队知识库的一部分。7.3 评估技能质量技能好不好不能只看一两次演示。建议准备一个小的评估集包含常见输入、边界输入和故意构造的坏输入每次更新技能后都跑一遍。指标含义任务成功率正确产出预期结果的比例token 消耗每次任务平均消耗的 token 数量执行时间从模型选择技能到执行完成的耗时修正次数人类需要纠正输出结果的次数错误信息可读性失败时是否能快速定位原因先用少量样例建立基线再通过观察失败案例迭代技能描述和脚本。技能库不是建完就结束而是在一次次失败和修正中慢慢变成团队的工作记忆。agent-skills 这类项目真正值得学习的不是某一个文件或命令而是这种“把任务能力工程化”的思路。如果你正在尝试建议先挑一个自己每周都会做的重复任务做成一个最小技能然后观察它在真实任务中的失败点是模型没有选中它还是脚本处理不了边界输入还是描述让模型误用了它。每修正一个问题这个技能就比上一次更接近稳定可复用。