项目标题听起来像是一个开源仓库或者某种工程实践的名字大概率是围绕 AI Agent 的能力封装与复用展开的。我在实际搭建智能体应用时踩过不少坑从“模型只会聊天”到“模型真正能干活”中间隔着的往往不是模型本身而是你给它配了什么工具、怎么描述这些工具、以及怎么组织这些工具的调用逻辑。agent-skills 这个概念本质上就是把“技能”这个抽象词落到工程上让 Agent 变得可扩展、可维护、可复用。这篇文章我想从工程实践的角度聊聊 agent-skills 是什么、它和 Function Calling 以及 MCP 有什么区别、技能仓库该怎么设计、从零实现一个技能需要做哪些事以及我实测下来容易翻车的几个地方。无论你是在做私人助理机器人还是在企业内部搞自动化流程这套思路都能直接参考。1. 从“会聊天”到“会干活”为什么需要技能化改造1.1 一句话看懂 agent-skills 是什么先说我自己的理解agent-skills 是一套“把 Agent 的能力切成一个个独立、可描述、可调用的技能单元”的工程规范。每个技能单元解决一类具体问题比如查天气、算工时、读网页、生成报表。Agent 本身不直接写死业务逻辑而是通过读取技能的描述信息判断当前用户请求应该调用哪个技能然后把控制权交给对应代码。这个思路和人类的工作方式很像。你让一个实习生“帮我整理一份本周的销售数据”他脑子里会自动把这个任务拆成几步找数据源、打开表格、筛选日期、汇总、生成报告。每一步他都知道该怎么做是因为他提前掌握了这些基础技能。Agent 也一样Skills 就是给它预装好的“能力包”让它不只会接话还会办事。1.2 和 Function Calling、MCP 到底有什么不一样很多人一看到 agent-skills就会联想到 Function Calling 和 MCP这三者确实有关系但定位完全不同。Function Calling 是模型层的能力它让模型在对话过程中输出一个结构化的“调用请求”比如“我要调用函数 get_weather参数 city北京”。这是一种交互协议解决的是“模型怎么表达意图”的问题。MCPModel Context Protocol是工具层的一种标准化接入方式它规定工具通过 JSON-RPC 暴露能力让不同的 Agent 框架能够统一发现和调用外部工具。它解决的是“工具怎么被连接”的问题。而 agent-skills 更像是应用层的组织方式它关注的不只是单个函数怎么定义还包括技能怎么描述让 Agent 理解这个技能什么时候用、怎么用技能代码怎么组织能不能跨项目复用多个技能怎么组合完成更复杂的任务技能怎么测试、怎么维护、怎么演进用一个不太严谨但容易理解的类比Function Calling 是“电话协议”MCP 是“电话线标准”agent-skills 则是“你的通讯录和工作手册”。通讯录里有名字、有号码、有备注Agent 翻一翻就知道该打给谁这就是技能描述的价值。提示如果你的 Agent 项目还停留在“把一堆函数塞进 prompt”的阶段换成 agent-skills 的做法会让你立刻感受到结构化的好处尤其是在技能数量超过 10 个以后。2. 技能仓库的核心设计先拆解一份标准技能长什么样2.1 一份技能的通用目录结构我在实战中尝试过多种技能组织方式最终沉淀下来一套比较通用的目录结构你可以直接照抄skills/ ├── web_search/ # 技能目录一个技能一个文件夹 │ ├── SKILL.md # 技能描述文件Agent 读这个来决定是否调用 │ ├── metadata.yaml # 元信息版本、作者、依赖、权限声明 │ ├── impl.py # 技能实现可以是 Python/JS/Shell │ ├── tests/ │ │ └── test_search.py │ └── assets/ # 技能自带的静态资源比如模板文件、参考数据 ├── time_calc/ │ ├── SKILL.md │ ├── metadata.yaml │ └── impl.js └── ...这个结构的核心原则有三个单一职责、自描述、可测试。单一职责指一个技能只做一件事自描述指 SKILL.md 写得足够清楚Agent 光看文字就知道怎么用可测试指每个技能都有独立的测试入口。2.2 技能描述文件Agent 的行动说明书SKILL.md 是整个技能仓库的灵魂。Agent 本身不读你的代码它只读描述文件。描述文件写得好不好直接决定模型能不能在正确的时候想起这个技能。我一般会在 SKILL.md 里固定几个段落--- name: time_calc description: 根据日期范围计算工作日天数、统计工时支持节假日排除 version: 1.2.0 author: team_ai permissions: - filesystem: temp_write --- # 技能使用说明 ## 这个技能解决什么问题 用户需要计算两个日期之间的工作日数量、按项目汇总工时、 判断某天是否为节假日时使用本技能。 ## 什么时候不要用 - 用户只是闲聊问“今天几号”不需要计算时不要调用 - 用户没有给出明确的日期范围时不要调用先追问 ## 输入参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | start_date | string | 是 | 开始日期格式 YYYY-MM-DD | | end_date | string | 是 | 结束日期格式 YYYY-MM-DD | | timezone | string | 否 | 时区默认 Asia/Shanghai | ## 输出格式 返回 JSON 对象包含 working_days、total_hours、holidays 列表别小看“什么时候不要用”这段。我在早期版本里只写了“什么时候用”结果模型经常在用户问“今天星期几”这种简单问题时也去调技能白白增加延迟。把否定场景写清楚能明显减少误调用。2.3 实现层代码是技能的肌肉描述文件是大脑代码就是手脚。实现层不需要多花哨但要注意接口规范。我建议每个技能暴露一个统一入口函数比如# impl.py def execute(params: dict, context: dict) - dict: ...execute 接收两个参数params 是 Agent 提取出来的结构化参数context 是运行上下文里面可以包含会话 ID、用户 ID、临时目录路径、日志回调等。返回统一结构{ status: success, data: {...}, message: 计算完成 }或者出错时{ status: error, error_code: INVALID_DATE_FORMAT, message: 日期格式不正确应为 YYYY-MM-DD }统一入口带来的好处是Agent 框架层只需要对接一种函数签名技能的注册、加载、超时控制、异常捕获都能用一个通用模板解决。这也是 agent-skills 和“随手在代码里写几个 def”最大的区别——用一套固定协议强制规范化后面要规模化扩展才不会乱。3. 从零实现一个可用的 Skill日期查询与工时统计实战3.1 定义场景与需求边界理论讲再多不如动手做一遍。我拿一个实际例子来演示做一个“工时统计”技能。需求场景是用户经常在群里问“我这个项目上周花了多少工时”“端午假期这几天怎么算加班”。这类问题直接让模型算日期不靠谱因为它对节假日规则和项目工时数据的掌握是零必须接一个技能。需求边界梳理出来就三条给定日期范围计算工作日天数排除周末和法定节假日给定每日工时记录按项目汇总总工时节假日数据从本地 JSON 读取不依赖外部接口注意我刻意把需求切得很小这符合 agent-skills 的“单一职责”原则。如果需求是“统计工时并生成 PPT”那就应该拆成两个技能一个算工时一个生成 PPT然后靠编排层去组合。3.2 写描述文件与参数协议按照 2.2 节的模板写工时统计技能的 SKILL.md。参数协议部分我考虑 Agent 的抽取能力尽量用简单明确的结构name: work_hours description: 计算日期范围内的工作日、汇总项目工时支持节假日排除 version: 1.0.0 inputs: - name: start_date type: string required: true description: 起始日期例如 2025-06-01 - name: end_date type: string required: true description: 结束日期例如 2025-06-30 - name: records type: array required: false description: 工时记录列表每个元素包含 project、date、hours参数类型不要用中文描述含糊地写比如不要写“日期类型”直接写 string 并明确格式因为模型对“YYYY-MM-DD”这种明确格式的处理成功率远高于“日期”这种模糊表达。3.3 写实现逻辑核心实现不复杂但要注意边界情况。以下是我实际用的实现骨架import json from datetime import date, datetime, timedelta # context 中会传入节假日数据路径 def execute(params: dict, context: dict): try: start_date datetime.strptime(params[start_date], %Y-%m-%d).date() end_date datetime.strptime(params[end_date], %Y-%m-%d).date() except KeyError: return {status: error, error_code: MISSING_PARAM, message: 缺少日期参数} except ValueError: return {status: error, error_code: INVALID_DATE, message: 日期格式错误} if start_date end_date: return {status: error, error_code: INVALID_RANGE, message: 开始日期不能晚于结束日期} holidays load_holidays(context.get(holiday_data_path)) working_days [] current start_date while current end_date: if current.weekday() 5 and current.isoformat() not in holidays: working_days.append(current.isoformat()) current timedelta(days1) result {working_days: len(working_days), day_list: working_days} if params.get(records): project_hours {} for r in params[records]: project r.get(project, 未分组) hours float(r.get(hours, 0)) project_hours[project] project_hours.get(project, 0) hours result[project_hours] project_hours return {status: success, data: result}这里有个小细节我在遍历日期时用 current.isoformat() 来和节假日 JSON 中的日期字符串比较而不是用 date 对象因为节假日数据的格式通常就是“2025-06-02”这种字符串保持两边一致可以省掉类型转换的坑。3.4 挂进 Agent 并验证一次完整调用实现写好之后需要让 Agent 框架认识它。不同的框架接入方式不同但核心逻辑一致从技能仓库加载 SKILL.md注册 execute 入口。假设我用的是一个支持技能插件的轻量 Agent 框架配置项大概长这样agent: model: gpt-4o skills: - path: ./skills/work_hours enabled: true验证时我会模拟用户输入“从6月1日到6月30日项目A每天投入5小时项目B每天投入3小时统计总工时。”模型应该输出一个调用请求。基于技能的抓取它会从描述文件中理解输入参数结构然后跑出结果。我实测下来只要 description 里的字段名清晰模型提取参数的准确率非常高。4. 一次技能调用的完整生命周期数据是怎么流转的4.1 触发判断模型怎么知道该用哪个技能Agent 收到用户消息后不是直接执行代码而是经过一轮“路由决策”。模型会同时看到系统提示词、技能描述列表、历史对话然后判断当前请求和哪个技能相关。这个决策过程有个关键点技能描述不能太长。如果把每个 SKILL.md 都完整塞给模型上下文会被大量无关文字挤占轻则响应变慢重则模型注意力分散、选错技能。我通常会在系统提示词里放一份极简的“技能索引”类似可用技能 - work_hours: 工时统计/日期计算参数最少需要 start_date、end_date - web_search: 联网搜索当用户需要最新信息时使用完整 SKILL.md 只在使用该技能时才加载到上下文里这种“按需加载”模式是 agent-skills 框架常见的优化手段。4.2 参数填充从用户语言到结构化输入路由决策完成后模型需要从用户原话里提取参数。这一步能不能做对取决于描述文件里的参数说明是否给足例子。给例子非常关键。我实测过两种情况没有例子时模型面对“帮我算一下这周工时”可能会填出来 start_date“这周”然后我的代码解析直接报错。加了一行示例之后examples: - input: 从6月1日到6月30日有多少工作日法定假日不算 params: start_date: 2025-06-01 end_date: 2025-06-30模型就会先尝试把“6月1日”映射成“2025-06-01”——虽然年份判断不一定对但出现格式错误的概率大幅降低。我建议每个必填参数都配至少一个例子。4.3 执行与结果返回安全边界在哪里参数提取完成后Agent 框架调用 execute然后把输出拼回对话。这里的重点是权限控制。让技能写文件可以但不能让它写系统关键目录让它发网络请求可以但不能让它访问内网元数据接口。我在 metadata.yaml 里加了一个 permissions 字段声明技能需要的资源权限permissions: - type: fs scope: temp reason: 需要写入临时文件以输出工时报表 - type: network scope: none这样做的好处是当多个来自不同来源的技能放在同一个 Agent 里时你可以用一套统一的权限审计机制去控制它们而不是让每个技能自己“自觉”。5. 进阶技巧技能编排与跨 Agent 共享5.1 技能链一个 Agent 怎么组合多个技能单技能解决单任务但真实场景往往是复合任务。例如“帮我查一下最近三个月的项目工时并生成一份周报”。这种需求我不会写一个“super_skill”而是让 Agent 先调 work_hours 算出工时再调 report_generator 生成文档。两个技能之间如何衔接答案是通过 Agent 自己的工作记忆上下文来传递中间结果。框架层的支持大概是这样workflow: - skill: work_hours outputs: - name: project_hours - skill: report_generator inputs: - source: project_hours你可以把技能链理解为流水线上一步的输出结构作为下一步的输入结构。为了确保两段之间数据格式兼容我强烈建议在设计技能时先定义好输出 schema就像前面定义输入参数一样。不要在第一个技能里返回一个嵌套列表第二个技能却期望扁平字典——这种问题排查起来特别费时间。5.2 跨 Agent 共享把技能做成团队包单个项目用技能是自嗨多个项目复用才是资产。agent-skills 做得好的一点就是把技能做成目录包可以像 npm 包一样分发。我会在团队内部维护一个 skills 仓库每个技能更新时打 tag。按版本引用dependencies: - skill: work_hours version: ^1.2.0 source: gitinternal:agent-skills/work_hours.git不同 Agent 项目可以引用不同版本的技能互不干扰。技能作者更新时跑一遍测试用例通过之后发版使用方自行升级。这其实就是把微服务的思路复制到 AI 应用层收益非常直接你不再需要为每个项目重复实现同一套工具逻辑。6. 常见问题与避坑实录6.1 上下文爆炸技能描述太多模型反而变笨这是我最开始踩的坑。为了让 Agent“见多识广”我把几十份技能描述全部塞进了系统提示词结果模型响应变慢而且经常用错技能因为描述之间的边界在模型眼里模糊了。解决办法就是 4.1 节提到的按需加载平时只给模型技能名称和一两句话摘要确定命中后再加载完整描述。如果框架不支持动态注入那也要把系统提示词里的描述压缩到极限只保留“关键触发词 参数个数”。6.2 描述和实现不一致模型说能用代码做不到这种情况通常发生在技能迭代之后SKILL.md 忘记更新。模型按照旧描述调用参数新代码却改了字段名直接报错。我的经验是把“描述文件变更”和“代码变更”绑在同一个提交里并且在 CI 流程中加一个校验提取 SKILL.md 里的参数名和实现代码里的参数名做一致性比对不一致就阻止合并。如果没有 CI 条件至少要在技能自测用例里覆盖全参调用的场景。6.3 并发与资源竞争Agent 并行处理多个用户请求时同一个技能可能被同时调用。如果技能代码里有共享状态比如一个全局变量缓存就可能出现数据错乱。我在技能实现规范里会写明不允许使用模块级全局变量存储用户相关状态。需要缓存时用 context 里的会话 ID 做 key并且设置过期时间。涉及文件写入时文件名必须带上 session_id 或者任务 ID避免互相覆盖。下面是我整理的一份排查速查表症状可能原因排查方法解决方案技能没有被调用描述文件触发器不一致查看模型输出日志确认路由决策结果调整 SKILL.md 中的触发词和示例参数提取错误缺少示例用测试样例跑一遍模型抽取在参数定义里补充 examples执行超时技能内部阻塞 IO用观测工具查看调用耗时增加超时重试机制状态错乱全局变量或文件冲突检查代码中的全局状态按会话 ID 隔离资源结果被截断返回内容太大查看最终生成 token 数拆分技能或压缩输出格式6.4 安全控制不能省最后必须认真强调安全。技能本质上是一段可以执行的代码如果 Agent 可以访问外部数据源那你的技能体系就成了潜在的攻击面。我在实际部署时至少做了这几层控制技能来源一律走内部仓库不直接加载网上下载的未知技能技能声明的权限必须和自己的功能对得上比如“查询天气”不需要访问文件系统涉及真实写入操作的技能一律加人工确认步骤不搞静默执行。注意如果你要做 Agent 公开技能市场类的产品技能沙箱隔离和权限审计不是可选项是必须项。宁可功能少一点也不能让用户数据暴露给不可控的代码。7. 写在最后的一点体会做了几个项目之后我对 agent-skills 的最大感受是它看似只是代码组织方式的调整实际改变的是整个 Agent 的扩展模式。以前我增加一个能力要改代码、改提示词、重新调试现在只需要往技能仓库丢一个文件夹写清楚描述和实现Agent 就能自动学会调用它。这种“人写逻辑、模型做路由”的协作方式确实比手动维护大 prompt 优雅得多。如果你正在做 Agent 相关的东西我的建议是从一个小而实用的技能开始尝试不用一上来就搞整套框架。先让 Agent 学会一个技能摸清描述文件怎么写、参数怎么定、模型调用准不准再逐步扩大技能库。这套东西的价值会在技能数量变多、复用变频繁之后逐步体现出来的。
agent-skills实战：AI Agent技能化设计与工程落地指南
项目标题听起来像是一个开源仓库或者某种工程实践的名字大概率是围绕 AI Agent 的能力封装与复用展开的。我在实际搭建智能体应用时踩过不少坑从“模型只会聊天”到“模型真正能干活”中间隔着的往往不是模型本身而是你给它配了什么工具、怎么描述这些工具、以及怎么组织这些工具的调用逻辑。agent-skills 这个概念本质上就是把“技能”这个抽象词落到工程上让 Agent 变得可扩展、可维护、可复用。这篇文章我想从工程实践的角度聊聊 agent-skills 是什么、它和 Function Calling 以及 MCP 有什么区别、技能仓库该怎么设计、从零实现一个技能需要做哪些事以及我实测下来容易翻车的几个地方。无论你是在做私人助理机器人还是在企业内部搞自动化流程这套思路都能直接参考。1. 从“会聊天”到“会干活”为什么需要技能化改造1.1 一句话看懂 agent-skills 是什么先说我自己的理解agent-skills 是一套“把 Agent 的能力切成一个个独立、可描述、可调用的技能单元”的工程规范。每个技能单元解决一类具体问题比如查天气、算工时、读网页、生成报表。Agent 本身不直接写死业务逻辑而是通过读取技能的描述信息判断当前用户请求应该调用哪个技能然后把控制权交给对应代码。这个思路和人类的工作方式很像。你让一个实习生“帮我整理一份本周的销售数据”他脑子里会自动把这个任务拆成几步找数据源、打开表格、筛选日期、汇总、生成报告。每一步他都知道该怎么做是因为他提前掌握了这些基础技能。Agent 也一样Skills 就是给它预装好的“能力包”让它不只会接话还会办事。1.2 和 Function Calling、MCP 到底有什么不一样很多人一看到 agent-skills就会联想到 Function Calling 和 MCP这三者确实有关系但定位完全不同。Function Calling 是模型层的能力它让模型在对话过程中输出一个结构化的“调用请求”比如“我要调用函数 get_weather参数 city北京”。这是一种交互协议解决的是“模型怎么表达意图”的问题。MCPModel Context Protocol是工具层的一种标准化接入方式它规定工具通过 JSON-RPC 暴露能力让不同的 Agent 框架能够统一发现和调用外部工具。它解决的是“工具怎么被连接”的问题。而 agent-skills 更像是应用层的组织方式它关注的不只是单个函数怎么定义还包括技能怎么描述让 Agent 理解这个技能什么时候用、怎么用技能代码怎么组织能不能跨项目复用多个技能怎么组合完成更复杂的任务技能怎么测试、怎么维护、怎么演进用一个不太严谨但容易理解的类比Function Calling 是“电话协议”MCP 是“电话线标准”agent-skills 则是“你的通讯录和工作手册”。通讯录里有名字、有号码、有备注Agent 翻一翻就知道该打给谁这就是技能描述的价值。提示如果你的 Agent 项目还停留在“把一堆函数塞进 prompt”的阶段换成 agent-skills 的做法会让你立刻感受到结构化的好处尤其是在技能数量超过 10 个以后。2. 技能仓库的核心设计先拆解一份标准技能长什么样2.1 一份技能的通用目录结构我在实战中尝试过多种技能组织方式最终沉淀下来一套比较通用的目录结构你可以直接照抄skills/ ├── web_search/ # 技能目录一个技能一个文件夹 │ ├── SKILL.md # 技能描述文件Agent 读这个来决定是否调用 │ ├── metadata.yaml # 元信息版本、作者、依赖、权限声明 │ ├── impl.py # 技能实现可以是 Python/JS/Shell │ ├── tests/ │ │ └── test_search.py │ └── assets/ # 技能自带的静态资源比如模板文件、参考数据 ├── time_calc/ │ ├── SKILL.md │ ├── metadata.yaml │ └── impl.js └── ...这个结构的核心原则有三个单一职责、自描述、可测试。单一职责指一个技能只做一件事自描述指 SKILL.md 写得足够清楚Agent 光看文字就知道怎么用可测试指每个技能都有独立的测试入口。2.2 技能描述文件Agent 的行动说明书SKILL.md 是整个技能仓库的灵魂。Agent 本身不读你的代码它只读描述文件。描述文件写得好不好直接决定模型能不能在正确的时候想起这个技能。我一般会在 SKILL.md 里固定几个段落--- name: time_calc description: 根据日期范围计算工作日天数、统计工时支持节假日排除 version: 1.2.0 author: team_ai permissions: - filesystem: temp_write --- # 技能使用说明 ## 这个技能解决什么问题 用户需要计算两个日期之间的工作日数量、按项目汇总工时、 判断某天是否为节假日时使用本技能。 ## 什么时候不要用 - 用户只是闲聊问“今天几号”不需要计算时不要调用 - 用户没有给出明确的日期范围时不要调用先追问 ## 输入参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | start_date | string | 是 | 开始日期格式 YYYY-MM-DD | | end_date | string | 是 | 结束日期格式 YYYY-MM-DD | | timezone | string | 否 | 时区默认 Asia/Shanghai | ## 输出格式 返回 JSON 对象包含 working_days、total_hours、holidays 列表别小看“什么时候不要用”这段。我在早期版本里只写了“什么时候用”结果模型经常在用户问“今天星期几”这种简单问题时也去调技能白白增加延迟。把否定场景写清楚能明显减少误调用。2.3 实现层代码是技能的肌肉描述文件是大脑代码就是手脚。实现层不需要多花哨但要注意接口规范。我建议每个技能暴露一个统一入口函数比如# impl.py def execute(params: dict, context: dict) - dict: ...execute 接收两个参数params 是 Agent 提取出来的结构化参数context 是运行上下文里面可以包含会话 ID、用户 ID、临时目录路径、日志回调等。返回统一结构{ status: success, data: {...}, message: 计算完成 }或者出错时{ status: error, error_code: INVALID_DATE_FORMAT, message: 日期格式不正确应为 YYYY-MM-DD }统一入口带来的好处是Agent 框架层只需要对接一种函数签名技能的注册、加载、超时控制、异常捕获都能用一个通用模板解决。这也是 agent-skills 和“随手在代码里写几个 def”最大的区别——用一套固定协议强制规范化后面要规模化扩展才不会乱。3. 从零实现一个可用的 Skill日期查询与工时统计实战3.1 定义场景与需求边界理论讲再多不如动手做一遍。我拿一个实际例子来演示做一个“工时统计”技能。需求场景是用户经常在群里问“我这个项目上周花了多少工时”“端午假期这几天怎么算加班”。这类问题直接让模型算日期不靠谱因为它对节假日规则和项目工时数据的掌握是零必须接一个技能。需求边界梳理出来就三条给定日期范围计算工作日天数排除周末和法定节假日给定每日工时记录按项目汇总总工时节假日数据从本地 JSON 读取不依赖外部接口注意我刻意把需求切得很小这符合 agent-skills 的“单一职责”原则。如果需求是“统计工时并生成 PPT”那就应该拆成两个技能一个算工时一个生成 PPT然后靠编排层去组合。3.2 写描述文件与参数协议按照 2.2 节的模板写工时统计技能的 SKILL.md。参数协议部分我考虑 Agent 的抽取能力尽量用简单明确的结构name: work_hours description: 计算日期范围内的工作日、汇总项目工时支持节假日排除 version: 1.0.0 inputs: - name: start_date type: string required: true description: 起始日期例如 2025-06-01 - name: end_date type: string required: true description: 结束日期例如 2025-06-30 - name: records type: array required: false description: 工时记录列表每个元素包含 project、date、hours参数类型不要用中文描述含糊地写比如不要写“日期类型”直接写 string 并明确格式因为模型对“YYYY-MM-DD”这种明确格式的处理成功率远高于“日期”这种模糊表达。3.3 写实现逻辑核心实现不复杂但要注意边界情况。以下是我实际用的实现骨架import json from datetime import date, datetime, timedelta # context 中会传入节假日数据路径 def execute(params: dict, context: dict): try: start_date datetime.strptime(params[start_date], %Y-%m-%d).date() end_date datetime.strptime(params[end_date], %Y-%m-%d).date() except KeyError: return {status: error, error_code: MISSING_PARAM, message: 缺少日期参数} except ValueError: return {status: error, error_code: INVALID_DATE, message: 日期格式错误} if start_date end_date: return {status: error, error_code: INVALID_RANGE, message: 开始日期不能晚于结束日期} holidays load_holidays(context.get(holiday_data_path)) working_days [] current start_date while current end_date: if current.weekday() 5 and current.isoformat() not in holidays: working_days.append(current.isoformat()) current timedelta(days1) result {working_days: len(working_days), day_list: working_days} if params.get(records): project_hours {} for r in params[records]: project r.get(project, 未分组) hours float(r.get(hours, 0)) project_hours[project] project_hours.get(project, 0) hours result[project_hours] project_hours return {status: success, data: result}这里有个小细节我在遍历日期时用 current.isoformat() 来和节假日 JSON 中的日期字符串比较而不是用 date 对象因为节假日数据的格式通常就是“2025-06-02”这种字符串保持两边一致可以省掉类型转换的坑。3.4 挂进 Agent 并验证一次完整调用实现写好之后需要让 Agent 框架认识它。不同的框架接入方式不同但核心逻辑一致从技能仓库加载 SKILL.md注册 execute 入口。假设我用的是一个支持技能插件的轻量 Agent 框架配置项大概长这样agent: model: gpt-4o skills: - path: ./skills/work_hours enabled: true验证时我会模拟用户输入“从6月1日到6月30日项目A每天投入5小时项目B每天投入3小时统计总工时。”模型应该输出一个调用请求。基于技能的抓取它会从描述文件中理解输入参数结构然后跑出结果。我实测下来只要 description 里的字段名清晰模型提取参数的准确率非常高。4. 一次技能调用的完整生命周期数据是怎么流转的4.1 触发判断模型怎么知道该用哪个技能Agent 收到用户消息后不是直接执行代码而是经过一轮“路由决策”。模型会同时看到系统提示词、技能描述列表、历史对话然后判断当前请求和哪个技能相关。这个决策过程有个关键点技能描述不能太长。如果把每个 SKILL.md 都完整塞给模型上下文会被大量无关文字挤占轻则响应变慢重则模型注意力分散、选错技能。我通常会在系统提示词里放一份极简的“技能索引”类似可用技能 - work_hours: 工时统计/日期计算参数最少需要 start_date、end_date - web_search: 联网搜索当用户需要最新信息时使用完整 SKILL.md 只在使用该技能时才加载到上下文里这种“按需加载”模式是 agent-skills 框架常见的优化手段。4.2 参数填充从用户语言到结构化输入路由决策完成后模型需要从用户原话里提取参数。这一步能不能做对取决于描述文件里的参数说明是否给足例子。给例子非常关键。我实测过两种情况没有例子时模型面对“帮我算一下这周工时”可能会填出来 start_date“这周”然后我的代码解析直接报错。加了一行示例之后examples: - input: 从6月1日到6月30日有多少工作日法定假日不算 params: start_date: 2025-06-01 end_date: 2025-06-30模型就会先尝试把“6月1日”映射成“2025-06-01”——虽然年份判断不一定对但出现格式错误的概率大幅降低。我建议每个必填参数都配至少一个例子。4.3 执行与结果返回安全边界在哪里参数提取完成后Agent 框架调用 execute然后把输出拼回对话。这里的重点是权限控制。让技能写文件可以但不能让它写系统关键目录让它发网络请求可以但不能让它访问内网元数据接口。我在 metadata.yaml 里加了一个 permissions 字段声明技能需要的资源权限permissions: - type: fs scope: temp reason: 需要写入临时文件以输出工时报表 - type: network scope: none这样做的好处是当多个来自不同来源的技能放在同一个 Agent 里时你可以用一套统一的权限审计机制去控制它们而不是让每个技能自己“自觉”。5. 进阶技巧技能编排与跨 Agent 共享5.1 技能链一个 Agent 怎么组合多个技能单技能解决单任务但真实场景往往是复合任务。例如“帮我查一下最近三个月的项目工时并生成一份周报”。这种需求我不会写一个“super_skill”而是让 Agent 先调 work_hours 算出工时再调 report_generator 生成文档。两个技能之间如何衔接答案是通过 Agent 自己的工作记忆上下文来传递中间结果。框架层的支持大概是这样workflow: - skill: work_hours outputs: - name: project_hours - skill: report_generator inputs: - source: project_hours你可以把技能链理解为流水线上一步的输出结构作为下一步的输入结构。为了确保两段之间数据格式兼容我强烈建议在设计技能时先定义好输出 schema就像前面定义输入参数一样。不要在第一个技能里返回一个嵌套列表第二个技能却期望扁平字典——这种问题排查起来特别费时间。5.2 跨 Agent 共享把技能做成团队包单个项目用技能是自嗨多个项目复用才是资产。agent-skills 做得好的一点就是把技能做成目录包可以像 npm 包一样分发。我会在团队内部维护一个 skills 仓库每个技能更新时打 tag。按版本引用dependencies: - skill: work_hours version: ^1.2.0 source: gitinternal:agent-skills/work_hours.git不同 Agent 项目可以引用不同版本的技能互不干扰。技能作者更新时跑一遍测试用例通过之后发版使用方自行升级。这其实就是把微服务的思路复制到 AI 应用层收益非常直接你不再需要为每个项目重复实现同一套工具逻辑。6. 常见问题与避坑实录6.1 上下文爆炸技能描述太多模型反而变笨这是我最开始踩的坑。为了让 Agent“见多识广”我把几十份技能描述全部塞进了系统提示词结果模型响应变慢而且经常用错技能因为描述之间的边界在模型眼里模糊了。解决办法就是 4.1 节提到的按需加载平时只给模型技能名称和一两句话摘要确定命中后再加载完整描述。如果框架不支持动态注入那也要把系统提示词里的描述压缩到极限只保留“关键触发词 参数个数”。6.2 描述和实现不一致模型说能用代码做不到这种情况通常发生在技能迭代之后SKILL.md 忘记更新。模型按照旧描述调用参数新代码却改了字段名直接报错。我的经验是把“描述文件变更”和“代码变更”绑在同一个提交里并且在 CI 流程中加一个校验提取 SKILL.md 里的参数名和实现代码里的参数名做一致性比对不一致就阻止合并。如果没有 CI 条件至少要在技能自测用例里覆盖全参调用的场景。6.3 并发与资源竞争Agent 并行处理多个用户请求时同一个技能可能被同时调用。如果技能代码里有共享状态比如一个全局变量缓存就可能出现数据错乱。我在技能实现规范里会写明不允许使用模块级全局变量存储用户相关状态。需要缓存时用 context 里的会话 ID 做 key并且设置过期时间。涉及文件写入时文件名必须带上 session_id 或者任务 ID避免互相覆盖。下面是我整理的一份排查速查表症状可能原因排查方法解决方案技能没有被调用描述文件触发器不一致查看模型输出日志确认路由决策结果调整 SKILL.md 中的触发词和示例参数提取错误缺少示例用测试样例跑一遍模型抽取在参数定义里补充 examples执行超时技能内部阻塞 IO用观测工具查看调用耗时增加超时重试机制状态错乱全局变量或文件冲突检查代码中的全局状态按会话 ID 隔离资源结果被截断返回内容太大查看最终生成 token 数拆分技能或压缩输出格式6.4 安全控制不能省最后必须认真强调安全。技能本质上是一段可以执行的代码如果 Agent 可以访问外部数据源那你的技能体系就成了潜在的攻击面。我在实际部署时至少做了这几层控制技能来源一律走内部仓库不直接加载网上下载的未知技能技能声明的权限必须和自己的功能对得上比如“查询天气”不需要访问文件系统涉及真实写入操作的技能一律加人工确认步骤不搞静默执行。注意如果你要做 Agent 公开技能市场类的产品技能沙箱隔离和权限审计不是可选项是必须项。宁可功能少一点也不能让用户数据暴露给不可控的代码。7. 写在最后的一点体会做了几个项目之后我对 agent-skills 的最大感受是它看似只是代码组织方式的调整实际改变的是整个 Agent 的扩展模式。以前我增加一个能力要改代码、改提示词、重新调试现在只需要往技能仓库丢一个文件夹写清楚描述和实现Agent 就能自动学会调用它。这种“人写逻辑、模型做路由”的协作方式确实比手动维护大 prompt 优雅得多。如果你正在做 Agent 相关的东西我的建议是从一个小而实用的技能开始尝试不用一上来就搞整套框架。先让 Agent 学会一个技能摸清描述文件怎么写、参数怎么定、模型调用准不准再逐步扩大技能库。这套东西的价值会在技能数量变多、复用变频繁之后逐步体现出来的。