一、为什么 Agent 需要 Skill1.1 什么是Skill Skill 是预先封装好、可以重复调用的能力模块它的作用就是给 AI Agent 补齐落地执行任务的手段。AI Agent 负责判断 “要做什么”而 Skill 负责真正动手 “怎么做”。像天气查询、邮件发送、数据库检索这类具体操作都可以封装成独立 Skill。新增业务能力时只需要开发对应的 Skill不用改动 Agent 的主体逻辑实现能力的灵活扩展与复用。1.2 Skill 的核心价值Skill 是 Anthropic 提出的声明式能力封装方案核心设计理念是不用代码用自然语言Markdown定义能力。它不是一段可执行代码而是一份 “操作手册” 权限配置本质是Skill 提示词模板 权限管控 资源引用 工作流指引对比 ToolSkill 具备四大核心优势低代码化纯 Markdown 编写无需 Java 代码非开发人员也能配置动态注入无需重启 Agent修改 Skill 即可生效支持热更新流程化引导内置完整工作流引导 Agent 按步骤完成复杂任务精细化权限可精准管控工具使用权限降低安全风险高复用性独立文件封装跨项目、跨 Agent 直接复用。1.3 Tool 与 Skill 核心区别对比维度传统 ToolToolSkill技能本质代码级可执行逻辑自然语言操作手册 权限配置编写方式Java 代码 注解MarkdownSKILL.md部署方式与 Agent 同进程需编译独立文件动态加载能力范围单一原子操作复杂多步骤工作流权限管控统一授权粒度粗精细化授权按需开放复用性项目内复用跨项目、跨 Agent 复用简单原子操作适合采用 Tool 实现具备轻量高效的特点而多步骤业务流程、需要跨项目复用以及频繁迭代的场景则更推荐使用 Skill它支持流程化编排、独立封装无需改造业务还可实现热更新便于维护与快速上线。Skill 看似是智能能力模块但其底层逻辑非常简洁无复杂算法完全依托大模型阅读理解能力驱动。核心优势是通过渐进式加载、按需指令注入解决传统 Prompt 一次性全量注入导致的上下文溢出、指令失效问题精准驱动 AI Agent 完成用户任务。二、Skill 的底层原理2.1 Skill 本质轻量化文档能力而非代码框架Skill 无需服务部署、无需编写业务代码本质是独立的文档化能力单元。每个 Skill 对应一个独立文件夹以 SKILL.md 为核心载体搭配少量可选资源文件即可实现完整能力定义真正做到一份文档、一项可复用技能。2.2 核心机制渐进式加载按需加载Skill 采用分步加载、按需披露的核心设计大幅节省上下文资源启动轻量扫描服务启动仅读取 SKILL.md 头部元数据名称、描述、权限快速生成技能清单不加载全文保证启动高效命中再加载全文用户请求触发语义匹配、命中对应技能后才加载完整文档内容执行按需引用任务执行阶段再按需调用配套资源、脚本全程避免上下文冗余溢出。Skill 不直接执行业务操作核心价值是标准化、轻量化地给 AI Agent 植入专业工作流程用文档驱动智能执行实现能力可插拔、无需改代码即可扩展 Agent 功能。三、Skill 的执行流程Skill 的整体执行逻辑简洁清晰可通过用户提问「今天热搜有哪些」这一场景完整拆解其运行流程核心分为发现、匹配、激活、执行、响应五个阶段。以你对 AI 说 “今天热搜有哪些” 为例发现DiscoverAI 启动时扫描所有 Skill 目录只读取每个 SKILL.md 的 name 和 description。匹配Match用户输入后AI 判断“这句话是否匹配某个 Skill 的描述”→ 比如 Skill 描述写了 “用户说‘今日简报’‘今天热点’时触发”。激活Activate匹配成功AI 加载该 Skill 的完整 SKILL.md 内容作为上下文。执行ExecuteAI 按照 Workflow工作流 一步步操作 调用 curl 获取天气 调用 API 拉取 V2EX 热帖 运行脚本处理数据如有 整理成指定格式响应Respond把结果返回给用户核心运行机制说明AI 运行 Skill 的核心逻辑并非自主编译、运行代码而是通过读取配置文件中的指令规则完成模拟执行与自动化调度。在此过程中AI 可正常调用系统命令、读取本地文件、执行自定义脚本实现多元化的自动化业务能力。四、Skill 资源目录目前OpenClaw、Claude Code、GitHub Copilot 等主流 AI 工具均遵循AgentSkills 开放规范。核心为SKILL.md 、存放脚本的script目录、存放参考文档的references目录 以及 assets模版目录。具体如下trip-planner/ ├── SKILL.md # 核心指令文件 ├── scripts/ # 可执行脚本如行程计算逻辑 │ └── calculate.py ├── references/ # 参考文档景点数据库、交通指南 │ └── attractions.md └── assets/ # 静态模板行程输出模板 └── template.mdscripts/ 脚本目录用于存放 Python/Bash 脚本可处理复杂逻辑references/ 存放参考文档使用时加载到上下文assets/ 存放模板不加载到上下文仅引用路径。上述配套资源文件夹中仅 SKILL.md 的元信息会常驻加载其余文件均按需引用以此避免主文档内容臃肿。五、Skill.md 标准结构每个 Skill 的核心是 SKILL.md由 元数据头YAML 正文Markdown两部分组成格式固定、规范清晰。5.1 第一部分YAML 元数据头配置区放在文件最顶部用 --- 包裹定义技能的基础信息、权限、规则必填字段仅 name 和 description。具体示例如下--- # 1. 技能名称必填唯一标识 name: trip-planner # 2. 技能描述必填1-2句话决定Agent能否匹配 description: 智能行程规划技能自动查询天气、推荐景点、生成2-7天个性化行程 # 3. 技能版本可选用于迭代管理 version: 1.0.0 # 4. 权限配置可选开放工具白名单 allowed-tools: getWeather, recommendAttractions # 5. 模型指定可选默认继承Agent模型 model: inherit # 6. 禁用手动触发可选true仅自动匹配 disable-model-invocation: false ---标准字段说明name技能唯一标识调用时用的指令名description核心匹配依据必须简洁精准说明 “什么时候用、做什么”allowed-tools工具的白名单只开放技能必需的工具最小权限原则model复杂技能可指定更强模型默认继承 Agent 配置。5.2 第二部分Markdown 正文指令区元数据头下方是正文用 Markdown 编写详细工作流、操作步骤、示例控制 Agent 的行为逻辑。正文标准结构## 一、技能用途 自动生成个性化行程流程查询目标城市天气 → 推荐匹配景点 → 规划每日行程 → 输出完整方案 ## 二、前置条件 1. 已开放 getWeather天气、recommendAttractions景点工具权限 2. 用户需提供城市、出行天数、偏好人文/自然 ## 三、执行步骤 ### 步骤1解析需求 提取用户输入的城市、天数、偏好缺失则追问 ### 步骤2查询天气 调用 getWeather 工具获取目标城市实时天气作为行程依据 ### 步骤3推荐景点 调用 recommendAttractions 工具筛选匹配偏好的高评分景点 ### 步骤4规划行程 按天数拆分景点平衡游玩强度结合天气调整室内/室外安排 ### 步骤5输出结果 生成结构化行程包含每日安排、时间建议、出行提示 ## 四、输出格式 ### 行程标题XX市X日游 ### 每日行程 - 上午景点A时长/亮点 - 下午景点B时长/亮点 - 晚上住宿/美食推荐 ### 出行提示天气、预约、交通 ## 五、错误处理 - 天气查询失败提示无法获取天气仍生成基础行程 - 无匹配景点推荐热门地标说明原因五、实战从零开发一个 Skill本章完整落地一套可直接使用的 Skill。本案例使用外网公开免费 API 作为工具不依赖私有内部接口同时严格遵循前面章节的目录规范、SKILL.md 结构、五阶段执行流程可直接放到 Agent 的 skills 目录加载支持热更新。5.1 需求定义技能名称trip-planner目标能力用户提出旅游规划需求时自动触发接收目的地、出行天数、旅行偏好调用外网公共 API 获取天气、景点信息生成结构化多日行程。工具选型外网公共免费工具publicWeatherApi公开天气查询 API获取目的地未来几天天气publicAttractionApi公开景点推荐 API按城市 偏好推荐景点说明两个都是外网公共只读 API无私有鉴权仅用于信息查询不支持写入操作。约束规则仅调用上面两个公共工具禁止调用其他外部接口用户缺少城市、出行天数、旅行偏好任一信息时主动追问不自行编造工具调用失败时降级使用模型内置知识生成基础行程输出固定结构化 Markdown 行程模板遵循最小权限原则仅开放本技能需要的 2 个工具。5.2 创建 Skill 目录结构按照第四章 AgentSkills 规范创建目录完整结构如下本案例无需复杂本地脚本不创建 scripts 目录。references 目录的文档会在技能激活时按需加载assets 下的模板只引用路径不会默认灌入上下文节约 token。5.3 编写 SKILL.md--- name: trip-planner description: 旅游行程规划技能。用户请求规划旅游、出行方案、多日游玩路线时触发。调用公共外网API查询目的地天气与景点生成个性化旅游行程。 version: 1.0.0 allowed-tools: publicWeatherApi, publicAttractionApi model: inherit disable-model-invocation: false --- # 旅游行程规划技能 ## 一、技能用途 接收用户的出行需求调用外网公共API查询目标城市天气、景点信息结合用户偏好生成2~7天个性化旅游行程。 ## 二、前置条件 1. Agent已注册外网公共工具 publicWeatherApi、publicAttractionApi 2. 参考文档 references/travel_tips.md 存在存放通用出行贴士 3. 用户需要提供目的地城市、出行天数、旅行偏好人文/自然风光/美食。 ## 三、执行步骤 ### 步骤1解析需求提取参数 读取用户输入提取3个核心参数目的地城市、出行天数、旅行偏好。 - 任意参数缺失向用户追问缺失信息不猜测、不编造 - 参数齐全进入下一步。 ### 步骤2调用公共天气API 调用publicWeatherApi传入目标城市获取出行时间段的天气。 天气将用于调整行程雨天优先安排室内景点晴天安排户外。 ### 步骤3调用公共景点推荐API 调用publicAttractionApi传入城市用户偏好获取推荐景点列表包含景点简介、建议游玩时长。 ### 步骤4编排每日行程 结合天气情况拆分景点到每一天均衡每日游玩强度 - 晴天优先户外景点 - 雨天替换为博物馆、展馆等室内景点 - 兼顾美食、休息不要行程过度拥挤。 ### 步骤5加载参考文档填充模板 读取references/travel_tips.md获取通用出行贴士引用assets/trip_template.md模板把天气、景点、行程信息填入模板。 ### 步骤6返回最终行程给用户 ## 四、输出格式 使用assets/trip_template.md模板输出Markdown结构化行程。 ## 五、错误处理 1. publicWeatherApi调用超时/失败不再重试提示天气获取失败基于景点信息生成基础行程并标注【天气数据获取失败行程未结合天气调整】 2. publicAttractionApi调用失败降级使用模型内置知识库推荐景点 3. API返回空景点列表推荐该城市热门地标备注“API未返回匹配偏好景点使用通用推荐” 4. 用户要求8天及以上行程提示本技能支持2~7天规划询问是否调整天数。 ## 六、边界约束 - 本技能只做行程规划不预订机票、酒店、门票 - 不生成高危、违规出行建议 - 外网API仅做只读查询禁止提交任何写入类请求 - 若API返回信息冲突以景点API信息为主。配套文件 1references/travel_tips.md# 通用出行贴士 1. 热门景点建议提前线上预约 2. 山区景点注意防晒防滑 3. 博物馆、展馆周一常闭馆 4. 节假日景点人流量大建议早出发。配套文件 2assets/trip_template.md# {{city}} {{days}}日游行程方案 偏好{{preference}} 天气参考{{weather_info}} ## 每日行程 {{daily_plan}} ## 出行小贴士 {{travel_tips}}5.4 部署加载将整个trip-planner文件夹放到 Agent 的 skills 根目录Agent 自动扫描目录仅读取 SKILL.md 顶部 YAML 元数据加入技能清单此时不加载全文符合渐进式加载机制修改 SKILL.md 或配套文件无需重启 Agent热更新即时生效。5.5 测试验证用户提问帮我规划去成都 4日游自然风光偏好对照第三章的 5 阶段执行流程完整验证。skill 输出结果如下成都 4 日游行程方案偏好自然风光天气参考全程小雨/阵雨为主19~28℃无晴天窗口9/26 都江堰降水最低仅 25%为最佳户外日西岭雪山 4 天降水概率 100%9~16℃故排除每日行程Day 19/23周三成都市区 · 雨 63% —— 室内为主上午大熊猫繁育研究基地熊猫晨间活跃建议 7:30 前入园下午成都博物馆 / 金沙遗址博物馆雨天转室内傍晚人民公园鹤鸣茶社喝盖碗茶 → 晚上宽窄巷子小吃Day 29/24周四都江堰 · 小雨 45% —— 世界遗产 古城夜都江堰景区鱼嘴 → 飞沙堰 → 宝瓶口 → 安澜索桥 → 二王庙下午灌县古城、西街晚上**南桥「蓝眼泪」**夜景Day 39/25周五青城山前山 · 小雨 45% —— 雨中更「幽」建福宫 → 天师洞 → 上清宫 → 老君阁建议索道省力全程古树、青苔石阶、雾中森林晚宿泰安古镇Day 49/26周六青城山后山 · ☀ 最佳日 25% —— 自然风光核心小环线徒步泰安古镇 → 五龙沟 → 又一村 → 翠映湖 → 泰安古镇溪流瀑布 青苔栈道随手即古风山水大片下午返蓉出行小贴士热门景点建议提前线上预约都江堰、青城山门票分开买山区景点注意防晒防滑青城山后山栈道湿滑务必穿防滑鞋博物馆、展馆周一常闭馆本次行程已避开节假日景点人流量大建议早出发山上下温差 3~8℃带薄外套 雨具。总结本文围绕 Agent 的 Skill 能力展开从需求背景出发讲解 Skill 本质是基于 Markdown 文档的声明式能力封装。然后 拆解了底层按需加载原理、五阶段执行流程给出标准目录结构与 SKILL.md 文档规范并通过旅游行程规划案例做完整实战演示。Skill依靠文档定义工作流与权限可引用外网公共 API支持热更新不用修改 Agent 主体代码。相比传统 Tool它更适合多步骤业务场景能跨项目复用降低业务能力扩展成本为企业级 Agent 落地提供一套轻量化、可维护的工程化方案。资料展示下面是我整理的AI大模型 学习资料和工具包预览适合收藏后按主题逐步学习
Spring AI 实战｜深度解析 Agent Skill 原理、结构与运行机制
一、为什么 Agent 需要 Skill1.1 什么是Skill Skill 是预先封装好、可以重复调用的能力模块它的作用就是给 AI Agent 补齐落地执行任务的手段。AI Agent 负责判断 “要做什么”而 Skill 负责真正动手 “怎么做”。像天气查询、邮件发送、数据库检索这类具体操作都可以封装成独立 Skill。新增业务能力时只需要开发对应的 Skill不用改动 Agent 的主体逻辑实现能力的灵活扩展与复用。1.2 Skill 的核心价值Skill 是 Anthropic 提出的声明式能力封装方案核心设计理念是不用代码用自然语言Markdown定义能力。它不是一段可执行代码而是一份 “操作手册” 权限配置本质是Skill 提示词模板 权限管控 资源引用 工作流指引对比 ToolSkill 具备四大核心优势低代码化纯 Markdown 编写无需 Java 代码非开发人员也能配置动态注入无需重启 Agent修改 Skill 即可生效支持热更新流程化引导内置完整工作流引导 Agent 按步骤完成复杂任务精细化权限可精准管控工具使用权限降低安全风险高复用性独立文件封装跨项目、跨 Agent 直接复用。1.3 Tool 与 Skill 核心区别对比维度传统 ToolToolSkill技能本质代码级可执行逻辑自然语言操作手册 权限配置编写方式Java 代码 注解MarkdownSKILL.md部署方式与 Agent 同进程需编译独立文件动态加载能力范围单一原子操作复杂多步骤工作流权限管控统一授权粒度粗精细化授权按需开放复用性项目内复用跨项目、跨 Agent 复用简单原子操作适合采用 Tool 实现具备轻量高效的特点而多步骤业务流程、需要跨项目复用以及频繁迭代的场景则更推荐使用 Skill它支持流程化编排、独立封装无需改造业务还可实现热更新便于维护与快速上线。Skill 看似是智能能力模块但其底层逻辑非常简洁无复杂算法完全依托大模型阅读理解能力驱动。核心优势是通过渐进式加载、按需指令注入解决传统 Prompt 一次性全量注入导致的上下文溢出、指令失效问题精准驱动 AI Agent 完成用户任务。二、Skill 的底层原理2.1 Skill 本质轻量化文档能力而非代码框架Skill 无需服务部署、无需编写业务代码本质是独立的文档化能力单元。每个 Skill 对应一个独立文件夹以 SKILL.md 为核心载体搭配少量可选资源文件即可实现完整能力定义真正做到一份文档、一项可复用技能。2.2 核心机制渐进式加载按需加载Skill 采用分步加载、按需披露的核心设计大幅节省上下文资源启动轻量扫描服务启动仅读取 SKILL.md 头部元数据名称、描述、权限快速生成技能清单不加载全文保证启动高效命中再加载全文用户请求触发语义匹配、命中对应技能后才加载完整文档内容执行按需引用任务执行阶段再按需调用配套资源、脚本全程避免上下文冗余溢出。Skill 不直接执行业务操作核心价值是标准化、轻量化地给 AI Agent 植入专业工作流程用文档驱动智能执行实现能力可插拔、无需改代码即可扩展 Agent 功能。三、Skill 的执行流程Skill 的整体执行逻辑简洁清晰可通过用户提问「今天热搜有哪些」这一场景完整拆解其运行流程核心分为发现、匹配、激活、执行、响应五个阶段。以你对 AI 说 “今天热搜有哪些” 为例发现DiscoverAI 启动时扫描所有 Skill 目录只读取每个 SKILL.md 的 name 和 description。匹配Match用户输入后AI 判断“这句话是否匹配某个 Skill 的描述”→ 比如 Skill 描述写了 “用户说‘今日简报’‘今天热点’时触发”。激活Activate匹配成功AI 加载该 Skill 的完整 SKILL.md 内容作为上下文。执行ExecuteAI 按照 Workflow工作流 一步步操作 调用 curl 获取天气 调用 API 拉取 V2EX 热帖 运行脚本处理数据如有 整理成指定格式响应Respond把结果返回给用户核心运行机制说明AI 运行 Skill 的核心逻辑并非自主编译、运行代码而是通过读取配置文件中的指令规则完成模拟执行与自动化调度。在此过程中AI 可正常调用系统命令、读取本地文件、执行自定义脚本实现多元化的自动化业务能力。四、Skill 资源目录目前OpenClaw、Claude Code、GitHub Copilot 等主流 AI 工具均遵循AgentSkills 开放规范。核心为SKILL.md 、存放脚本的script目录、存放参考文档的references目录 以及 assets模版目录。具体如下trip-planner/ ├── SKILL.md # 核心指令文件 ├── scripts/ # 可执行脚本如行程计算逻辑 │ └── calculate.py ├── references/ # 参考文档景点数据库、交通指南 │ └── attractions.md └── assets/ # 静态模板行程输出模板 └── template.mdscripts/ 脚本目录用于存放 Python/Bash 脚本可处理复杂逻辑references/ 存放参考文档使用时加载到上下文assets/ 存放模板不加载到上下文仅引用路径。上述配套资源文件夹中仅 SKILL.md 的元信息会常驻加载其余文件均按需引用以此避免主文档内容臃肿。五、Skill.md 标准结构每个 Skill 的核心是 SKILL.md由 元数据头YAML 正文Markdown两部分组成格式固定、规范清晰。5.1 第一部分YAML 元数据头配置区放在文件最顶部用 --- 包裹定义技能的基础信息、权限、规则必填字段仅 name 和 description。具体示例如下--- # 1. 技能名称必填唯一标识 name: trip-planner # 2. 技能描述必填1-2句话决定Agent能否匹配 description: 智能行程规划技能自动查询天气、推荐景点、生成2-7天个性化行程 # 3. 技能版本可选用于迭代管理 version: 1.0.0 # 4. 权限配置可选开放工具白名单 allowed-tools: getWeather, recommendAttractions # 5. 模型指定可选默认继承Agent模型 model: inherit # 6. 禁用手动触发可选true仅自动匹配 disable-model-invocation: false ---标准字段说明name技能唯一标识调用时用的指令名description核心匹配依据必须简洁精准说明 “什么时候用、做什么”allowed-tools工具的白名单只开放技能必需的工具最小权限原则model复杂技能可指定更强模型默认继承 Agent 配置。5.2 第二部分Markdown 正文指令区元数据头下方是正文用 Markdown 编写详细工作流、操作步骤、示例控制 Agent 的行为逻辑。正文标准结构## 一、技能用途 自动生成个性化行程流程查询目标城市天气 → 推荐匹配景点 → 规划每日行程 → 输出完整方案 ## 二、前置条件 1. 已开放 getWeather天气、recommendAttractions景点工具权限 2. 用户需提供城市、出行天数、偏好人文/自然 ## 三、执行步骤 ### 步骤1解析需求 提取用户输入的城市、天数、偏好缺失则追问 ### 步骤2查询天气 调用 getWeather 工具获取目标城市实时天气作为行程依据 ### 步骤3推荐景点 调用 recommendAttractions 工具筛选匹配偏好的高评分景点 ### 步骤4规划行程 按天数拆分景点平衡游玩强度结合天气调整室内/室外安排 ### 步骤5输出结果 生成结构化行程包含每日安排、时间建议、出行提示 ## 四、输出格式 ### 行程标题XX市X日游 ### 每日行程 - 上午景点A时长/亮点 - 下午景点B时长/亮点 - 晚上住宿/美食推荐 ### 出行提示天气、预约、交通 ## 五、错误处理 - 天气查询失败提示无法获取天气仍生成基础行程 - 无匹配景点推荐热门地标说明原因五、实战从零开发一个 Skill本章完整落地一套可直接使用的 Skill。本案例使用外网公开免费 API 作为工具不依赖私有内部接口同时严格遵循前面章节的目录规范、SKILL.md 结构、五阶段执行流程可直接放到 Agent 的 skills 目录加载支持热更新。5.1 需求定义技能名称trip-planner目标能力用户提出旅游规划需求时自动触发接收目的地、出行天数、旅行偏好调用外网公共 API 获取天气、景点信息生成结构化多日行程。工具选型外网公共免费工具publicWeatherApi公开天气查询 API获取目的地未来几天天气publicAttractionApi公开景点推荐 API按城市 偏好推荐景点说明两个都是外网公共只读 API无私有鉴权仅用于信息查询不支持写入操作。约束规则仅调用上面两个公共工具禁止调用其他外部接口用户缺少城市、出行天数、旅行偏好任一信息时主动追问不自行编造工具调用失败时降级使用模型内置知识生成基础行程输出固定结构化 Markdown 行程模板遵循最小权限原则仅开放本技能需要的 2 个工具。5.2 创建 Skill 目录结构按照第四章 AgentSkills 规范创建目录完整结构如下本案例无需复杂本地脚本不创建 scripts 目录。references 目录的文档会在技能激活时按需加载assets 下的模板只引用路径不会默认灌入上下文节约 token。5.3 编写 SKILL.md--- name: trip-planner description: 旅游行程规划技能。用户请求规划旅游、出行方案、多日游玩路线时触发。调用公共外网API查询目的地天气与景点生成个性化旅游行程。 version: 1.0.0 allowed-tools: publicWeatherApi, publicAttractionApi model: inherit disable-model-invocation: false --- # 旅游行程规划技能 ## 一、技能用途 接收用户的出行需求调用外网公共API查询目标城市天气、景点信息结合用户偏好生成2~7天个性化旅游行程。 ## 二、前置条件 1. Agent已注册外网公共工具 publicWeatherApi、publicAttractionApi 2. 参考文档 references/travel_tips.md 存在存放通用出行贴士 3. 用户需要提供目的地城市、出行天数、旅行偏好人文/自然风光/美食。 ## 三、执行步骤 ### 步骤1解析需求提取参数 读取用户输入提取3个核心参数目的地城市、出行天数、旅行偏好。 - 任意参数缺失向用户追问缺失信息不猜测、不编造 - 参数齐全进入下一步。 ### 步骤2调用公共天气API 调用publicWeatherApi传入目标城市获取出行时间段的天气。 天气将用于调整行程雨天优先安排室内景点晴天安排户外。 ### 步骤3调用公共景点推荐API 调用publicAttractionApi传入城市用户偏好获取推荐景点列表包含景点简介、建议游玩时长。 ### 步骤4编排每日行程 结合天气情况拆分景点到每一天均衡每日游玩强度 - 晴天优先户外景点 - 雨天替换为博物馆、展馆等室内景点 - 兼顾美食、休息不要行程过度拥挤。 ### 步骤5加载参考文档填充模板 读取references/travel_tips.md获取通用出行贴士引用assets/trip_template.md模板把天气、景点、行程信息填入模板。 ### 步骤6返回最终行程给用户 ## 四、输出格式 使用assets/trip_template.md模板输出Markdown结构化行程。 ## 五、错误处理 1. publicWeatherApi调用超时/失败不再重试提示天气获取失败基于景点信息生成基础行程并标注【天气数据获取失败行程未结合天气调整】 2. publicAttractionApi调用失败降级使用模型内置知识库推荐景点 3. API返回空景点列表推荐该城市热门地标备注“API未返回匹配偏好景点使用通用推荐” 4. 用户要求8天及以上行程提示本技能支持2~7天规划询问是否调整天数。 ## 六、边界约束 - 本技能只做行程规划不预订机票、酒店、门票 - 不生成高危、违规出行建议 - 外网API仅做只读查询禁止提交任何写入类请求 - 若API返回信息冲突以景点API信息为主。配套文件 1references/travel_tips.md# 通用出行贴士 1. 热门景点建议提前线上预约 2. 山区景点注意防晒防滑 3. 博物馆、展馆周一常闭馆 4. 节假日景点人流量大建议早出发。配套文件 2assets/trip_template.md# {{city}} {{days}}日游行程方案 偏好{{preference}} 天气参考{{weather_info}} ## 每日行程 {{daily_plan}} ## 出行小贴士 {{travel_tips}}5.4 部署加载将整个trip-planner文件夹放到 Agent 的 skills 根目录Agent 自动扫描目录仅读取 SKILL.md 顶部 YAML 元数据加入技能清单此时不加载全文符合渐进式加载机制修改 SKILL.md 或配套文件无需重启 Agent热更新即时生效。5.5 测试验证用户提问帮我规划去成都 4日游自然风光偏好对照第三章的 5 阶段执行流程完整验证。skill 输出结果如下成都 4 日游行程方案偏好自然风光天气参考全程小雨/阵雨为主19~28℃无晴天窗口9/26 都江堰降水最低仅 25%为最佳户外日西岭雪山 4 天降水概率 100%9~16℃故排除每日行程Day 19/23周三成都市区 · 雨 63% —— 室内为主上午大熊猫繁育研究基地熊猫晨间活跃建议 7:30 前入园下午成都博物馆 / 金沙遗址博物馆雨天转室内傍晚人民公园鹤鸣茶社喝盖碗茶 → 晚上宽窄巷子小吃Day 29/24周四都江堰 · 小雨 45% —— 世界遗产 古城夜都江堰景区鱼嘴 → 飞沙堰 → 宝瓶口 → 安澜索桥 → 二王庙下午灌县古城、西街晚上**南桥「蓝眼泪」**夜景Day 39/25周五青城山前山 · 小雨 45% —— 雨中更「幽」建福宫 → 天师洞 → 上清宫 → 老君阁建议索道省力全程古树、青苔石阶、雾中森林晚宿泰安古镇Day 49/26周六青城山后山 · ☀ 最佳日 25% —— 自然风光核心小环线徒步泰安古镇 → 五龙沟 → 又一村 → 翠映湖 → 泰安古镇溪流瀑布 青苔栈道随手即古风山水大片下午返蓉出行小贴士热门景点建议提前线上预约都江堰、青城山门票分开买山区景点注意防晒防滑青城山后山栈道湿滑务必穿防滑鞋博物馆、展馆周一常闭馆本次行程已避开节假日景点人流量大建议早出发山上下温差 3~8℃带薄外套 雨具。总结本文围绕 Agent 的 Skill 能力展开从需求背景出发讲解 Skill 本质是基于 Markdown 文档的声明式能力封装。然后 拆解了底层按需加载原理、五阶段执行流程给出标准目录结构与 SKILL.md 文档规范并通过旅游行程规划案例做完整实战演示。Skill依靠文档定义工作流与权限可引用外网公共 API支持热更新不用修改 Agent 主体代码。相比传统 Tool它更适合多步骤业务场景能跨项目复用降低业务能力扩展成本为企业级 Agent 落地提供一套轻量化、可维护的工程化方案。资料展示下面是我整理的AI大模型 学习资料和工具包预览适合收藏后按主题逐步学习
