文档教程AI 技能【免费下载链接】claude-code-best-practicefrom vibe coding to agentic engineering - practice makes claude perfect项目地址https://gitcode.com/GitHub_Trending/cl/claude-code-best-practice点击查看免费下载本文以 claude-code-best-practice 仓库中的/weather-orchestrator自定义命令为核心深入讲解 Claude Code 的Command → Agent → Skill三层编排架构命令如何通过 AskUserQuestion 与用户交互、如何委托携带预载技能的weather-agent子代理从 Open-Meteo 获取迪拜实时温度再由独立的weather-svg-creator技能生成 SVG 天气卡片。读完本文你将掌握自定义 Slash Command 的 YAML 配置、Agent 定义与 Skill 的两种挂载模式预载技能 vs 直接调用、fail-closed 防御式编排写法以及一套可直接复用的取数 → 渲染职责分离模板。一、系统概览一条命令里的三层编排架构/weather-orchestrator是注册在 .claude/commands/weather-orchestrator.md 的 Claude Code 自定义命令它的目标非常聚焦获取阿联酋迪拜Dubai, UAE的当前温度并生成一张可视化的 SVG 天气卡片。这套天气系统演示了两种不同的 Skill 使用模式共同组成一条完整的编排链路见 orchestration-workflow/orchestration-workflow.md组件角色本仓库中的具体实现Command命令工作流入口负责用户交互与流程调度.claude/commands/weather-orchestrator.mdAgent子代理携带预载技能agent skill取数weather-agentweather-fetcherSkill技能独立创建可视化输出weather-svg-creator三个角色各司其职命令负责编排与交互Agent 负责取数Skill 负责渲染输出。整体调用链如下╔══════════════════════════════════════════════════════════════════╗ ║ ORCHESTRATION WORKFLOW ║ ║ Command → Agent → Skill ║ ╚══════════════════════════════════════════════════════════════════╝ ┌───────────────────┐ │ User Interaction │ └─────────┬─────────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ /weather-orchestrator — Command (Entry Point) │ └─────────────────────────┬───────────────────────────┘ │ Step 1 │ ▼ ┌────────────────────────┐ │ AskUser — C° or F°? │ └────────────┬───────────┘ │ Step 2 — Agent tool │ ▼ ┌─────────────────────────────────────────────────────┐ │ weather-agent — Agent ● skill: weather-fetcher │ └─────────────────────────┬───────────────────────────┘ │ Returns: temp unit │ Step 3 — Skill tool │ ▼ ┌─────────────────────────────────────────────────────┐ │ weather-svg-creator — Skill ● SVG card output │ └─────────────────────────┬───────────────────────────┘ │ ┌────────┴────────┐ │ │ ▼ ▼ ┌────────────┐ ┌────────────┐ │weather.svg │ │ output.md │ └────────────┘ └────────────┘二、命令入口/weather-orchestrator 的配置与执行契约2.1 Frontmatter 配置解析自定义命令以 Markdown 文件承载文件头部的 YAML frontmatter 决定了命令的行为边界--- description: Fetch Dubai weather and create an SVG weather card model: haiku allowed-tools: - AskUserQuestion - Agent - Skill ---逐项解读description命令的功能描述也是 Claude Code 展示给用户以及供模型判断何时使用该命令的说明文本model: haiku命令主体运行在haiku模型上。由于命令只负责流程编排提问、委托、汇总不承担复杂推理使用轻量模型即可把重活交给后面的 sonnet 子代理——这是对模型成本与能力的精细化分配allowed-tools该命令被允许调用的工具白名单仅有三个AskUserQuestion用户交互、Agent委托子代理、Skill调用技能。白名单从工具层面直接封死了命令自行取数的路径——它没有WebFetch、Bash因此绕过 Agent 直接拉天气在结构上就不可能发生。2.2 不可协商的执行契约Execution Contract命令正文首先声明了一段非协商的强制约束这是整个编排可靠性的基石必须通过委托weather-agent子代理来完成本命令禁止自行用 Bash、WebFetch 或任何其他工具获取天气数据禁止跳过 Step 1——用户的温度单位偏好是交给 Agent 的必选输入禁止在 Agent 返回温度之前调用weather-svg-creator如果无法调用 Agent 工具立即停止并向用户报告错误不得临场发挥Do not improvise。这种宁可失败、不可篡改流程的写法把编排约束从提示词的软建议升级为硬性契约确保每一次执行都走同一条可审计的调用链。三、Step 1用 AskUserQuestion 采集单位偏好命令的第一动作是调用AskUserQuestion工具询问用户希望温度以Celsius摄氏还是Fahrenheit华氏显示并在进入下一步前捕获该选择。这一步的价值在于把用户偏好作为显式的上游输入Agent 拿到单位后才知道应该构造哪种 API 请求SVG 卡片也才能输出正确的单位标注。这也呼应了执行契约中单位偏好是 Agent 的必选输入的要求。四、Step 2委托 weather-agent 子代理取数4.1 命令侧调用参数命令通过Agent工具发起委托参数如下subagent_typeweather-agentdescriptionFetch Dubai weather datapromptFetch the current temperature for Dubai, UAE in [unit requested by user]. Return the numeric temperature value and unit. The agent has a preloaded skill (weather-fetcher) that provides the detailed instructions.modelhaiku此处为本次委托会话指定的模型命令需要等待 Agent 完成并捕获返回的温度数值与单位。4.2 Agent 定义为什么它能安全地取数weather-agent定义在 .claude/agents/weather-agent.md其 frontmatter 是理解整个设计的关键--- name: weather-agent description: Use this agent PROACTIVELY when you need to fetch weather data for Dubai, UAE. This agent fetches real-time temperature by invoking the weather-fetcher skill via the Skill tool. allowedTools: - Read - Skill model: sonnet color: green maxTurns: 5 permissionMode: acceptEdits memory: project skills: - weather-fetcher ---逐项说明allowedTools: [Read, Skill]子代理的工具白名单刻意不包含任何网络工具无 WebFetch / WebSearch / Bash。Agent 正文中有一句点睛之笔如果你的工具清单里没有网络工具却发现自己需要网络那就是你在绕过技能的信号——停下来改用Skill(weather-fetcher)。工具白名单在此成了防绕过机制的物理屏障model: sonnet取数子代理使用能力更强的sonnet与命令主体的haiku形成轻编排 重执行的分层skills: [weather-fetcher]这是预载技能agent skill——weather-fetcher的完整指令在 Agent 启动时被注入其上下文作为领域知识存在Agent 并不通过 Skill 工具动态调用它maxTurns: 5限制子代理最多 5 轮工具交互防止失控的循环调用permissionMode: acceptEdits允许自动接受文件编辑为 Agent 的取数与记忆写入提供权限memory: project启用项目级内存让 Agent 可以读取/写入 .claude/agent-memory/weather-agent/MEMORY.md 做历史读数追踪hooksPreToolUse/PostToolUse/PostToolUseFailure三个钩子都调用.claude/hooks/scripts/hooks.py --agentvoice-hook-agent异步、超时 5000ms用于在子代理工具调用的前后及失败时播放提示音或触发旁路逻辑钩子机制的完整说明见 .claude/hooks/HOOKS-README.md。Agent 自身的执行契约同样不可协商必须通过 Skill 工具调用weather-fetcher禁止自行调用 WebFetch/WebSearch/curl 等 HTTP/API 工具禁止把技能指令读出来内联执行禁止以缓存/我已经知道数值为由跳过 Skill 调用。4.3 fail-closed 守护取数失败即停命令与 Agent 都内置了同一条fail-closed 守护规则如果 Agent 没有返回数值型温度与单位不得进入 Step 3必须向用户报告失败并停止。这一条保证了SVG 卡片永远不可能用伪造的温度生成——渲染环节依赖的数据必须是 Step 2 的真实返回值。4.4 weather-fetcher 技能Open-Meteo 数据源细节.claude/skills/weather-fetcher/SKILL.md 是预载进weather-agent的领域知识其 frontmatter 中user-invocable: false表示该技能不向用户直接暴露只能经由 Agent 消费allowed-tools: [WebFetch(*)]则把网络访问能力限定在技能这一层。技能的核心指令是通过 WebFetch 调用Open-Meteo天气 API 获取迪拜实时温度。Open-Meteo免费、无需 API Key、按经纬度查询迪拜坐标固定为latitude 25.2048, longitude 55.2708单位API URLCelsiushttps://api.open-meteo.com/v1/forecast?latitude25.2048longitude55.2708currenttemperature_2mtemperature_unitcelsiusFahrenheithttps://api.open-meteo.com/v1/forecast?latitude25.2048longitude55.2708currenttemperature_2mtemperature_unitfahrenheit从 JSON 响应中提取字段温度值current.temperature_2m单位标签current_units.temperature_2m技能要求返回格式这也是 Agent 向命令汇报的格式Current Dubai Temperature: [X]°[C/F] Unit: [Celsius/Fahrenheit]技能备注明确只取温度不做任何变换、不写任何文件——取数与渲染的边界在这里被划得干干净净。五、Step 3用 weather-svg-creator 技能生成 SVG 卡片5.1 调用与运行方式命令通过Skill工具直接调用weather-svg-creatorskill: weather-svg-creator。与weather-fetcher不同这是一个独立技能skill——它不预载进任何 Agent而是在命令的上下文中被直接调用并从当前上下文读取 Step 2 返回的温度值与单位。这正是FetchAgent→ RenderSkill分离的关键渲染技能不需要自己取数天然防止了数据不一致。5.2 SVG 模板与设计规范技能定义在 .claude/skills/weather-svg-creator/SKILL.md具体模板与规范见同目录下的 reference.mdsvg xmlnshttp://www.w3.org/2000/svg viewBox0 0 300 160 width300 height160 rect width300 height160 rx12 fill#1a1a2e/ text x150 y45 text-anchormiddle fill#8892b0 font-familysystem-ui font-size14Unit: [Celsius/Fahrenheit]/text text x150 y100 text-anchormiddle fill#ccd6f6 font-familysystem-ui font-size42 font-weightbold[value]°[C/F]/text text x150 y140 text-anchormiddle fill#64ffda font-familysystem-ui font-size16Dubai, UAE/text /svg占位符替换规则占位符替换为示例[Celsius/Fahrenheit]输入中的完整单位名Celsius[value]输入中的数值温度26.2[C/F]单位缩写C或F设计规格一览可直接用于自定义卡片样式属性值画布尺寸300 × 160 px圆角半径12 px背景色#1a1a2e深海军蓝单位标签#8892b0柔和蓝14px温度数值#ccd6f6浅蓝42px 粗体地点文字#64ffda青色点缀16px字体system-ui对齐全部居中text-anchormiddlex1505.3 输出文件与 Markdown 摘要技能规则强调必须使用给定的温度值与单位不得重新取数或修改SVG 必须自包含且合法两个输出文件都写入orchestration-workflow/目录。文件路径SVG 天气卡片orchestration-workflow/weather.svgMarkdown 摘要orchestration-workflow/output.mdoutput.md使用 reference.md 中的模板生成# Weather Result ## Temperature [value]°[C/F] ## Location Dubai, UAE ## Unit [Celsius/Fahrenheit] ## SVG Card [](https://link.gitcode.com/i/5dd2b8d904dd3fb9cb77f7e560829593)5.4 输入/输出示例对examples.md 给出了摄氏与华氏两组完整示例可直接作为验收用例。摄氏示例输入Temperature: 26.2°C, Unit: Celsius产出的 SVG 卡片svg xmlnshttp://www.w3.org/2000/svg viewBox0 0 300 160 width300 height160 rect width300 height160 rx12 fill#1a1a2e/ text x150 y45 text-anchormiddle fill#8892b0 font-familysystem-ui font-size14Unit: Celsius/text text x150 y100 text-anchormiddle fill#ccd6f6 font-familysystem-ui font-size42 font-weightbold26.2°C/text text x150 y140 text-anchormiddle fill#64ffda font-familysystem-ui font-size16Dubai, UAE/text /svg华氏示例输入Temperature: 79.2°F, Unit: Fahrenheit同理只需替换单位名与数值。仓库中实际运行记录的输出 orchestration-workflow/output.md 显示一次真实执行为89.3°FFahrenheit对应的 SVG 卡片正是本文开头展示的图片。六、输出汇总与记忆机制命令完成后向用户展示清晰的汇总包含四要素用户请求的温度单位从迪拜获取的温度值SVG 卡片位置orchestration-workflow/weather.svg摘要文件位置orchestration-workflow/output.md此外weather-agent的memory: project让它每次取数后都会把读数写入 .claude/agent-memory/weather-agent/MEMORY.md 用于历史追踪。该文件既固化了 API 配置Provider、坐标、两种单位的 URL、温度字段也维护了一张最近读数表——Agent 汇报时可以对比上一次读数例如2026-04-16: 23.8°C为后续温度趋势类扩展提供数据基础。七、两种 Skill 模式对比与架构原则7.1 Agent Skill预载技能# .claude/agents/weather-agent.md --- name: weather-agent skills: - weather-fetcher # 启动时预载进 Agent 上下文 ---技能全文在 Agent 启动时注入上下文作为领域知识Agent 按技能指令行事不通过 Skill 工具单独调用适合知识注入型场景Agent 需要一套专属操作手册来完成取数。7.2 Skill直接调用# .claude/skills/weather-svg-creator/SKILL.md --- name: weather-svg-creator description: Creates an SVG weather card showing the current temperature for Dubai... ---由命令通过Skill(skill: weather-svg-creator)直接调用在命令上下文中独立执行不依附于任何 Agent从对话上下文接收已就绪的数据温度 单位适合纯输出型场景。7.3 本系统的关键设计原则双技能模式示范同一工作流同时演示预载技能agent skill与直接调用技能skill命令即编排器用户交互与流程调度全部由命令承担Agent 专职取数子代理借助预载技能取数后原样返回Skill 专职渲染SVG 创建独立运行只消费上下文中的数据职责干净分离FetchAgent→ RenderSkill每个组件单一职责配合 fail-closed 守护与工具白名单构成高可靠编排。八、从源码结构看扩展思路在 claude-code-best-practice 仓库中weather-orchestrator不是孤例而是一整套最佳实践的一个切片同类自定义命令还有 .claude/commands/time-command.md时间查询命令与 .claude/commands/workflows/ 下按主题分组的命令合集best-practice、agent-collections、development-workflows、skill-collections若要理解这套编排在更大规模下如何落地可参阅 implementation/claude-commands-implementation.md、implementation/claude-subagents-implementation.md、implementation/claude-skills-implementation.md 三份实施文档它们分别从命令、子代理、技能三个维度给出了本仓库的真实落地过程理论层面对应的最佳实践文档位于 best-practice/claude-commands.md、best-practice/claude-subagents.md、best-practice/claude-skills.md。以/weather-orchestrator为模板你可以快速把任意数据获取 可视化输出的需求改造成同构编排替换 Agent 的取数技能换 API、换坐标、替换渲染技能的模板与输出路径即可复用到股票行情卡、空气质量卡、汇率卡片等场景——三层职责边界与 fail-closed 契约无需改动。赞分享文档教程AI 技能【免费下载链接】claude-code-best-practicefrom vibe coding to agentic engineering - practice makes claude perfect项目地址https://gitcode.com/GitHub_Trending/cl/claude-code-best-practice点击查看免费下载相关推荐Claude Code Skills 实战指南以 Command → Agent → Skill 架构实现 Weather SVG 天气系统Claude Code Skills 实战指南以 Command → Agent → Skill 架构实现 Weather SVG 天气系统 本文以本仓库 i文档教程AI 技能Claude Code 技能实战用 weather-svg-creator 生成迪拜天气 SVG 卡片并理解 Command → Agent → Skill 编排链路Claude Code 技能实战用 weather svg creator 生成迪拜天气 SVG 卡片并理解 Command → Agent → Skill文档教程AI 技能Claude Code 实战用 weather-agent 子代理 Skill 工具构建专注的天气数据抓取 AgentClaude Code 实战用 weather agent 子代理 Skill 工具构建专注的天气数据抓取 Agent 导读 本文以开源仓库 claude文档教程AI 技能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考