文档教程AI 技能【免费下载链接】claude-code-best-practicefrom vibe coding to agentic engineering - practice makes claude perfect项目地址https://gitcode.com/GitHub_Trending/cl/claude-code-best-practice点击查看免费下载本文以本仓库implementation/claude-skills-implementation.md为骨架围绕仓库中真实落地的两个 Skills 展开weather-svg-creatorskill直接调用与weather-fetcheragent skill预加载注入。读者将掌握 SKILL.md 的编写规范、20 个 YAML frontmatter 字段的语义与默认值、两种技能调用模式的区别以及如何在一个「Command → Agent → Skill」编排链路中组合使用它们。一、仓库里落地了什么两种 Skill 模式在 Claude Code 中Skills 是存放在.claude/skills/skill-name/SKILL.md下的 Markdown 文件通过 YAML frontmatter 描述元数据正文给出具体的任务与指令。本仓库以Command → Agent → Skill架构模式落地了两个 Skill分别演示两种截然不同的调用方式Pattern调用方式仓库示例关键差异SkillSkill(skill: name)直接调用weather-svg-creator由 Skill 工具显式唤起在调用方上下文中独立执行Agent Skill通过 agent 定义中的skills:字段预加载weather-fetcher启动时注入 agent 上下文作为领域知识存在不单独唤起两个 Skill 共同服务于一个真实可运行的天气看板工作流weather-fetcher负责从 Open-Meteo API 抓取迪拜实时气温weather-svg-creator负责把温度渲染成 SVG 天气卡片并写出输出文件。二、Skill直接调用weather-svg-creator文件.claude/skills/weather-svg-creator/SKILL.md--- name: weather-svg-creator description: Creates an SVG weather card showing the current temperature for Dubai. Writes the SVG to orchestration-workflow/weather.svg and updates orchestration-workflow/output.md. ---正文包含 Task 与 Instructions 两级结构Task接收调用上下文传入的温度值与单位Celsius / Fahrenheit生成 SVG 天气卡片并写出 SVG 与 Markdown 摘要两个文件Instructions明确三步操作——按reference.md中的模板创建 SVG、将内容写入orchestration-workflow/weather.svg、再按模板把摘要写入orchestration-workflow/output.mdRules必须使用给定的温度值与单位不得重新抓取或修改、SVG 必须自包含且合法、两个输出文件都落在orchestration-workflow/目录。2.1 模板与设计规格reference.mdSkill 目录下可以附带参考文件被 SKILL.md 正文以相对路径引用。仓库中的.claude/skills/weather-svg-creator/reference.md给出了可复用的 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/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-anchormiddlex1502.2 示例输入输出examples.md.claude/skills/weather-svg-creator/examples.md提供了两组完整的输入输出对可作为技能验收基准。以摄氏为例Temperature: 26.2°C Unit: Celsius生成的orchestration-workflow/weather.svgsvg 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同步写出的orchestration-workflow/output.md# Weather Result ## Temperature 26.2°C ## Location Dubai, UAE ## Unit Celsius ## SVG Card [](https://link.gitcode.com/i/de461de2e358b75a0844b0c9ede8fc09)weather-svg-creator是典型的skill直接调用由命令通过 Skill 工具显式唤起它从会话上下文中拿到温度数据自行完成 SVG 渲染与文件写出不依赖任何 agent 环境。三、Agent Skill预加载注入weather-fetcher文件.claude/skills/weather-fetcher/SKILL.md--- name: weather-fetcher description: Instructions for fetching current weather temperature data for Dubai, UAE from Open-Meteo API user-invocable: false allowed-tools: - WebFetch(*) ---正文是三段式指令Fetch Weather Data用 WebFetch 工具抓取 Open-Meteo 数据。摄氏接口https://api.open-meteo.com/v1/forecast?latitude25.2048longitude55.2708currenttemperature_2mtemperature_unitcelsius华氏接口仅将temperature_unit换为fahrenheitExtract Temperature从 JSON 响应中提取current.temperature_2m单位标签位于current_units.temperature_2mReturn Result清晰返回温度数值与单位。Notes 部分限定了边界只抓温度、不做任何转换或写文件Open-Meteo 免费且无需 API key迪拜坐标 latitude 25.2048、longitude 55.2708。这里有两个值得注意的 frontmatter 细节user-invocable: false把技能从/命令菜单中隐藏使该技能成为「背景知识」专为 agent 预加载设计避免用户误从菜单唤起allowed-tools限定为WebFetch(*)与 agent 定义中的工具白名单配合形成「只能通过技能间接联网」的约束。3.1 从源码看预加载机制weather-agentAgent Skill 的「预加载」语义在.claude/agents/weather-agent.md中有完整实现证据。agent 的 frontmatter 通过skills:字段声明预加载技能--- name: weather-agent description: Use this agent PROACTIVELY when you need to fetch weather data for Dubai, UAE... allowedTools: - Read - Skill model: sonnet color: green maxTurns: 5 permissionMode: acceptEdits memory: project skills: - weather-fetcher hooks: PreToolUse: - matcher: .* hooks: - type: command command: python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py --agentvoice-hook-agent timeout: 5000 async: true PostToolUse: - matcher: .* hooks: - type: command command: python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py --agentvoice-hook-agent timeout: 5000 async: true ---关键设计是fail-closed失败即关闭的执约契约agent必须通过 Skill 工具调用weather-fetcher禁止自己直接调用WebFetch/WebSearch/curl也禁止「读了技能指令后内联执行」agent 的allowedTools故意不含任何网络工具——一旦发现自己需要联网即是绕过了技能的信号应当停下并改用Skill(weather-fetcher)若 Skill 调用未返回数字温度与单位agent 不得自行抓取而是报告失败并停止。也就是说weather-fetcher的完整内容在weather-agent启动时被注入其上下文agent 把它当作领域知识再经 Skill 工具执行取数最终只向调用方返回「温度数值 单位」这份数据Step 3 还要求与记忆中的历史读数对比。四、两种 Skill 模式对比总结维度SkillAgent Skill调用方式Skill(skill: name)直接唤起通过 agent 的skills:字段启动时预加载仓库示例weather-svg-creatorweather-fetcher上下文注入调用时按需加载启动时全文注入 agent 上下文典型用途独立产出渲染、写文件、生成文档领域知识/取数指令作为 agent 的「参考资料」是否出现在/菜单是除非设置user-invocable: false通常隐藏user-invocable: false这条对比也体现在 orchestration-workflow/orchestration-workflow.md 的架构总结中Fetchagent 预加载技能→ Renderskill每个组件单一职责、干净分离。五、SKILL.md 的 frontmatter 字段20 个本仓库 best-practice/claude-skills.md 完整整理了 SKILL.md 支持的 20 个 frontmatter 字段写技能时按需选用字段类型必填说明namestring否显示名与/slash-command标识缺省时用目录名descriptionstring推荐技能做什么显示在自动补全中供 Claude 自动发现when_to_usestring否何时应调用技能的额外上下文触发短语、示例请求追加到description之后计入 1,536 字符上限argument-hintstring否自动补全时显示的提示如[issue-number]、[filename]argumentsstring/list否命名位置参数用于正文中的$name替换接受空格分隔字符串或 YAML 列表按顺序映射位置disable-model-invocationboolean否设为true阻止 Claude 自动调用该技能user-invocableboolean否设为false从/菜单隐藏技能仅作背景知识用于 agent 预加载allowed-toolsstring否技能激活期间免权限提示的工具disallowed-toolsstring/list否技能激活期间从 Claude 可用工具池移除的工具如后台循环中屏蔽AskUserQuestion接受空格/逗号分隔字符串或 YAML 列表限制在下一轮消息清除modelstring否技能运行所用模型如haiku、sonnet、opuseffortstring否调用时覆盖模型 effort 等级low、medium、high、xhigh、maxcontextstring否设为fork在隔离的 subagent 上下文中运行技能agentstring否context: fork时的 subagent 类型默认general-purposebackgroundboolean否仅context: fork下生效设为false等待 fork 的 subagent 结果默认true后台运行需 v2.1.218hooksobject否作用域限定于该技能的钩子pathsstring/list否限制技能自动激活的 glob 模式接受逗号分隔字符串或 YAML 列表仅当处理匹配文件时加载技能shellstring否!command代码块的 shellbash默认或powershell需CLAUDE_CODE_USE_POWERSHELL_TOOL1metadataYAML map否自由格式 YAML 映射供自建工具从SKILL.md读取如 entitlement、catalog 字段Claude Code 不解读其内容且会丢弃非 map 的值不要复用 frontmatter 字段名如paths作键licensestring否技能许可证属于 Agent Skills 规范字段Claude Code 接受但不生效compatibilitystring否环境要求最多 500 字符如目标产品、系统前置条件同属 Agent Skills 规范Claude Code 接受但不生效仓库中的weather-fetcher就用到了user-invocable与allowed-tools两个字段来塑造「隐藏 仅限联网工具」的行为是字段语义的最佳演示。六、把两种技能串起来Command → Agent → Skill 编排单看两个 Skill 不足以体现价值它们在.claude/commands/weather-orchestrator.md编排下构成完整工作流--- description: Fetch Dubai weather and create an SVG weather card model: haiku allowed-tools: - AskUserQuestion - Agent - Skill ---命令的三步执行契约Step 1 — AskUserQuestion询问用户要摄氏还是华氏先捕获单位偏好Step 2 — Agent 取数通过 Agent 工具调用weather-agentsubagent_type: weather-agentprompt 中注明「该 agent 预加载了 weather-fetcher 技能提供详细取数指令」model: haikufail-closed 护栏——若 agent 未返回数字温度与单位禁止进入 Step 3直接报告失败Step 3 — Skill 渲染通过 Skill 工具调用weather-svg-creator技能直接消费 Step 2 已进入上下文的温度数据产出 SVG 卡片与摘要。组件职责一览implementation/claude-commands-implementation.md 同款表格组件角色本仓库落地Command入口、用户交互/weather-orchestratorAgent用预加载技能取数agent skillweather-agentweather-fetcherSkill独立产出skillweather-svg-creator整体调用链为用户运行/weather-orchestrator→ 命令询问温度单位 → Agent 工具唤起weather-agent→ agent 经 Skill 工具执行weather-fetcher从 Open-Meteo 取数并返回 → 命令经 Skill 工具唤起weather-svg-creator→ 写出orchestration-workflow/weather.svg与orchestration-workflow/output.md→ 命令汇总展示结果。完整的 ASCII 流程图为 orchestration-workflow/orchestration-workflow.md 所收录七、如何使用启动 Claude Code 后直接以斜杠命令唤起技能$ claude /weather-svg-creatorweather-svg-creator因未设置user-invocable: false会出现在/菜单中可直接触发weather-fetcher则因user-invocable: false从菜单隐藏只能作为weather-agent的预加载知识使用。实际体验完整链路时运行$ claude /weather-orchestrator命令会先询问单位偏好随后自动完成取数与渲染最终在orchestration-workflow/weather.svg真实输出示例见 orchestration-workflow/weather.svg与orchestration-workflow/output.md见 orchestration-workflow/output.md落盘结果。八、如何实现让 Claude 生成 SKILL.md仓库文档给出的实现路径非常直接——让 Claude 帮你生成Ask Claude to create one for you — it will generate the markdown file with YAML frontmatter and body in.claude/skills/my-skill/SKILL.md即向 Claude 描述技能需求它会自动在.claude/skills/skill-name/SKILL.md生成「YAML frontmatter 正文」的 Markdown 文件--- name: my-skill description: ... --- # My Skill Instructions for what the skill does.生成后按前文 20 字段表补充元数据并按需在技能目录下添加reference.md、examples.md等附件如仓库中 weather-svg-creator 的做法技能即可被自动发现。九、落地建议结合本仓库两个技能的实际形态总结几条可直接复用的经验取数类技能用 agent skill把 API 抓取、指令型步骤如weather-fetcher预加载进专门 agent配合allowed-tools收紧工具面杜绝 agent「自作主张直接联网」产出类技能用独立 skill渲染、写文件、生成文档如weather-svg-creator保持独立由命令或上层直接Skill(skill: ...)唤起职责单一、可复用用 fail-closed 护栏兜底agent 与命令层面都写明「拿不到有效数据就停下报告不得自行绕路」保证编排链路的确定性善用user-invocable: false纯背景知识型技能一律隐藏避免污染/菜单与用户心智模板与示例分离SKILL.md只放指令SVG 模板、设计规格放reference.md输入输出对放examples.md既控制技能正文篇幅又便于维护。若要在大型 monorepo 中组织技能可进一步参考 reports/claude-skills-for-larger-mono-repos.md技能没有CLAUDE.md 的向上祖先加载行为而是从嵌套目录自动发现编辑packages/frontend/下文件时才加载packages/frontend/.claude/skills/且默认只把 description 加载进上下文、完整内容按需加载预加载给 subagent 的技能除外因此共享技能放根目录、包级技能放包内、description 保持精炼是 monorepo 场景的关键取舍。赞分享文档教程AI 技能【免费下载链接】claude-code-best-practicefrom vibe coding to agentic engineering - practice makes claude perfect项目地址https://gitcode.com/GitHub_Trending/cl/claude-code-best-practice点击查看免费下载相关推荐Hydra 插件开发实战指南从插件发现机制到自定义 LauncherHydra 插件开发实战指南从插件发现机制到自定义 Launcher Hydra 通过插件系统将 Launcher启动器、Sweeper搜索器、Con文档教程AI 技能Claude Code 实战用 weather-agent 子代理 Skill 工具构建专注的天气数据抓取 AgentClaude Code 实战用 weather agent 子代理 Skill 工具构建专注的天气数据抓取 Agent 导读 本文以开源仓库 claude文档教程AI 技能Dagger TypeScript SDK 错误处理指南UnknownDaggerError 的定位、源码实现与实战排查Dagger TypeScript SDK 错误处理指南UnknownDaggerError 的定位、源码实现与实战排查 导读 UnknownDaggerEr文档教程AI 技能上一篇wasm-bindgen终极指南掌握代码生成钩子和自定义转换规则下一篇Go安全扫描器Gosec终极配置指南优化扫描策略的10个技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考