文档教程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 最佳实践仓库claude-code-best-practice中.claude/agents/time-agent.md是一个精悍而完整的子代理Subagent定义范本它用 YAML frontmatter 声明身份、工具白名单、模型与运行上限用正文规定唯一的 bash 指令与输出格式最终以极低成本完成显示巴基斯坦标准时间PKT, UTC5这一确定性任务。本文将以该文件为骨架逐字段拆解子代理定义规范并结合仓库中的命令.claude/commands/time-command.md、技能.claude/skills/time-skill/SKILL.md以及 agent-teams 子项目agent-teams/中的 Dubai 变体完整还原 Claude Code 的 Command → Agent → Skill 编排模式。读完本文你将掌握如何编写、组合与验证一个时区类子代理并理解 frontmatter 各字段allowedTools、model、maxTurns对代理行为的实际约束。一、time-agent 在仓库中的定位最小可用的子代理范本claude-code-best-practice是一个 Claude Code 配置最佳实践仓库见 CLAUDE.md它本身不是业务应用代码库而是 skills、subagents、hooks、commands 等配置模式的参考实现。其中的天气系统weather system演示了Command → Agent → Skill架构而time-agent系列则把同一套架构裁剪到一个更小的场景只需一条 bash 命令即可完成的时区时间查询。仓库中存在三个彼此同构的时间组件它们分别对应架构中的三个角色角色文件时区核心职责命令Command.claude/commands/time-command.mdPKT (UTC5)用户入口直接输出结果代理Agent.claude/agents/time-agent.mdPKT (UTC5)受限工具环境下的专职执行者技能Skill.claude/skills/time-skill/SKILL.mdPKT (UTC5)用户可直接/调用的领域知识代理团队版Agent Teamagent-teams/.claude/agents/time-agent.mdDubai (UTC4)多智能体团队中的组件预加载 time-fetcher 技能三份 PKT 文件共享同一条命令、同一种输出格式与同一组要求只是包装角色不同。这意味着同一个领域任务可以按需封装为 command、agent 或 skill 三种形态这正是本仓库想传递的核心设计思想——先用小而确定的用例验证模式再在更大的系统如天气系统中放大。二、frontmatter 逐字段拆解一个子代理的身份档案子代理定义文件.claude/agents/*.md以 YAML frontmatter 开头规范依据见 CLAUDE.md 的 Subagent Definition Structure 小节。time-agent.md的 frontmatter 是理解全部字段的最小完整样本--- name: time-agent-pkt description: Use this agent to display the current time in Pakistan Standard Time (PKT, UTC5). (root scope — see agent-teams for Dubai time) allowedTools: - Bash(*) - Read - Write - Edit - Glob - Grep - WebFetch(*) - WebSearch(*) - Agent - NotebookEdit - mcp__* model: haiku maxTurns: 3 ---2.1name子代理标识符name: time-agent-pkt是调用时的标识符主代理通过 Agent 工具按名引用。注意这里的命名刻意与agent-teams子项目中的time-agent区分开前者加-pkt后缀并在description中注明 root scope — see agent-teams for Dubai time以此在仓库根作用域与 agent-teams 作用域之间建立清晰的命名空间边界避免两个同名代理在跨目录协作时产生歧义。2.2description触发时机的信号description决定何时该用这个代理。仓库规范CLAUDE.md建议在需要自动调用时使用 PROACTIVELY 措辞本例没有使用该关键词说明它属于按需手动调用的确定性工具型代理而非需要主动介入的通用代理。description 中还携带了时区与作用域信息PKT, UTC5、root scope这些信息是 Claude 选择代理时的匹配依据应尽量语义明确、可检索。2.3allowedTools工具白名单的两种策略allowedTools是逗号分隔/列表形式的工具白名单。本代理采用了**继承所有工具策略**Bash(*)、Read、Write、Edit、Glob、Grep、WebFetch(*)、WebSearch(*)、Agent、NotebookEdit、mcp__*即除Skill外几乎开放了全部工具类别mcp__*表示允许所有 MCP 服务器工具。这与仓库中另一条经典策略形成对比天气代理 .claude/agents/weather-agent.md 采用最小白名单策略仅Read与Skill并在正文中用 Execution Contract执行契约明令禁止自行调用 WebFetch/WebSearch/curl以此强制代理必须经由 Skill 工具获取数据实现 fail-closed 的护栏设计。两者取舍的启示任务越确定如本代理只需一条date命令白名单越宽越省事任务越依赖强制走某个流程如天气代理必须走 skill越需要用窄白名单做结构性约束——把护栏写进工具列表比写进提示词更可靠因为代理无法绕过不存在的工具。2.4model: haiku模型选择的经济学model: haiku把代理运行时的模型固定为最轻量的 haiku。这是一个非常合理的选择任务只需要执行一条 bash 命令并格式化输出没有推理、没有多步规划用重型模型纯属浪费。仓库的惯例见 agent-teams 的 time-agent.md 与天气代理同样大量使用haiku/sonnet组合昂贵模型留给复杂编排廉价模型跑确定性小任务。model字段的可选值包括haiku、sonnet、opus或inherit默认继承会话设置。2.5maxTurns: 3轮数上限兜底maxTurns限制子代理在停止前的最大 agentic 轮数防止代理陷入无限循环或过度调用。对本任务而言 3 轮绰绰有余通常第 1 轮执行date命令第 2 轮返回结果即结束。它是确定性任务中的成本与失控双保险。三、正文指令解析从命令到输出的完整契约frontmatter 之后是正文它以身份声明 → 任务 → 指令 → 要求四段式组织全部内容只有 26 行却定义了一个可复现、可验证的完整行为契约3.1 身份与任务# Time Agent You are a specialized agent that displays the current time in Pakistan Standard Time (PKT). ## Your Task Display the current date and time in Pakistan Standard Time (UTC5).第一句话即声明角色边界You are a specialized agent...随后用一句话收敛任务。这种写法与天气代理的 Execution Contract 结构一脉相承先框定职责再给出执行细节。3.2 唯一命令TZ 环境变量 dateTZAsia/Karachi date %Y-%m-%d %H:%M:%S %Z这是整个代理的核心动作逐段拆解其语义TZAsia/Karachi为单条命令临时注入 POSIX 时区环境变量IANA 时区数据库中的Asia/Karachi对应巴基斯坦标准时间PKT, UTC5。用环境变量而非date -u或手动偏移可自动处理夏令时等边界情况巴基斯坦目前不使用夏令时但该写法仍是最稳健的时区表达方式date %Y-%m-%d %H:%M:%S %Z%Y四位年份、%m两位月份、%d两位日期、%H24 小时制小时、%M、%S组成紧凑时间戳%Z输出时区缩写如PKT。注意0400agent-teams 输出中的格式与PKT缩写差异正是%Z与%z两种格式符的区别前者打印字母缩写后者打印数字偏移。3.3 输出契约调用方可解析的固定格式Current Time in Pakistan (PKT): YYYY-MM-DD HH:MM:SS PKT代理被要求以固定模板返回结果而不是自由发挥。这一点在 agent-teams 的 Dubai 变体中体现得更彻底——那里的代理被要求解析输出并返回三个结构化字段{time, timezone, formatted}供上层命令直接提取见 agent-teams/agent-teams-prompt.md。固定输出格式是子代理与调用方之间的数据契约它让主代理无需阅读理解就能消费结果也是多智能体协作agent teams得以成立的前提。3.4 要求清单把约束显式化- Always use the Asia/Karachi timezone (UTC5) - Use 24-hour format - Include the date alongside the time - Keep the output concise四条要求全部可执行、可验证且都是不变量invariant时区不允许被系统时区覆盖、不允许 12 小时制、不允许只给时间不给日期、不允许附加评论。这类显式约束把易被模型忽略的隐性细节变成硬性要求是提示工程中要求即契约的典型实践。四、同一任务的三种包装Command、Skill 与 Agent Team 变体4.1 Command 形态直达用户的快捷入口.claude/commands/time-command.md 是/time-command斜杠命令的定义正文与 time-agent 几乎逐字相同同一条 bash 命令、同一个输出模板、同四条要求区别仅在于没有 frontmatter 的allowedTools/model/maxTurns因为它直接运行在会话主代理上下文中。两者的关系正如 CLAUDE.md 所述Use commands for workflows instead of standalone agents——简单的单步任务用 command 更直接需要受限环境或多步编排才值得建 agent。4.2 Skill 形态用户可直接/调用的领域知识.claude/skills/time-skill/SKILL.md 以user-invocable: true出现在/菜单中用户在会话里输入/time-skill即可触发。它的 frontmatter 多了一个字段description: Display the current time in Pakistan Standard Time (PKT, UTC5). Use when the user asks for the current time, Pakistan time, or PKT.——其中明确列举了触发场景关键词current time、Pakistan time、PKT这为模型的自动发现auto-discovery提供了匹配依据。这印证了 CLAUDE.md 中技能定义的规范description推荐用于自动发现user-invocable: false则把技能隐藏为仅代理使用的后台知识agent-teams 的 time-fetcher 技能正是如此。4.3 Agent Team 变体从单代理到多智能体团队agent-teams/子项目把时间任务升级为完整的Command → Agent → Skill 团队协作编排说明见 agent-teams/agent-teams-prompt.mdCommandtime-orchestrator编排流程、与用户交互先经Agent 工具而非 bash调用 time-agent再经Skill 工具调用 time-svg-creatorAgentagent-teams/.claude/agents/time-agent.mdfrontmatter 增加tools: Bash、color: blue并通过skills: - time-fetcher预加载技能——即 agent skill 模式技能作为领域知识在启动时注入代理上下文Skilltime-svg-creator time-fetcher前者把时间渲染为自包含 SVG 卡片后者user-invocable: false仅作为代理的后台知识。运行产物可见 agent-teams/output/output.md时间、时区、日期、完整时间戳四字段 SVG 路径与 agent-teams/output/dubai-time.svg。整个团队的协调机制是数据契约{time, timezone, formatted}代理返回三个字段命令透传给技能技能消费渲染。三个组件并行开发、仅需对齐接口——这正是多智能体团队agent teams的设计要点。4.4 两种技能模式的对照从仓库整体架构orchestration-workflow/orchestration-workflow.md可以提炼出两种技能模式的明确分工Agent Skills预加载技能通过skills:字段注入代理上下文作为代理的领域知识如 time-fetcher 之于 time-agent、weather-fetcher 之于 weather-agentSkills独立技能由命令通过 Skill 工具在需要时显式调用产出独立交付物如 time-svg-creator 渲染 SVG、weather-svg-creator 生成天气卡片。五、源码佐证与跨组件一致性验证把三份 PKT 文件并列对比可以验证本仓库的一个设计原则确定性小任务的三件套agent / command / skill共享同一行为基线。三处对比如下要素time-agent.mdtime-command.mdtime-skill/SKILL.md命令TZAsia/Karachi date %Y-%m-%d %H:%M:%S %Z相同相同输出格式Current Time in Pakistan (PKT): ...相同相同时区要求Asia/Karachi, UTC5相同相同24 小时制是是是简洁输出是是是这种同一契约、三种包装的结构与天气系统CLAUDE.md 中的 Weather System 章节的组件设计如出一辙/weather-orchestrator命令作为入口询问 C°/F°weather-agent用预加载的weather-fetcher技能拉取 Open-Meteo 温度weather-svg-creator技能独立渲染 SVG。time 系列是这套架构最精简的验证用例weather 系列则是它的完整放大版。子代理编排的另一个关键约束来自 CLAUDE.md 的 Subagent Orchestration 章节子代理不能通过 bash 命令调用其他子代理必须使用 Agent 工具Agent(subagent_typeagent-name, description..., prompt..., modelhaiku)time-agent 的 frontmatter 中显式列入了Agent工具正是为了在需要时保有这一编排能力同时在正文中不出现任何模糊措辞如 launch避免被误解析为 bash 调用——这是 CLAUDE.md 强调的 Be explicit about tool usage 的直接体现。六、从 time-agent 出发最小代理的复用路径作为一个 26 行的最小代理time-agent.md的价值不在于功能本身而在于它示范了一套可复用的搭建路径先用 command 跑通把单条命令 输出格式写进.claude/commands/验证任务本身可行再决定包装形态需要受限工具环境/独立模型/轮数上限时升级为.claude/agents/中的子代理allowedTools、model、maxTurns三件套按需配置需要用户可直接/触发或作为后台知识时封装为.claude/skills/中的技能注意user-invocable的取值多代理协作时定义数据契约把输出固定为结构化字段如{time, timezone, formatted}让上层命令与下游技能无需互相读取对方实现即可对接护栏优先于提示词若任务有必须走某条路径的硬约束用最小allowedTools白名单做结构性限制比在正文里反复强调更可靠参照天气代理的 Execution Contract。把巴基斯坦时间换成迪拜时间TZAsia/Dubai、GST/UTC4把单条date命令换成一次 API 调用或一条技能指令这套骨架即可平移到任意确定性单点任务上。这正是本仓库从 vibe coding 走向 agentic engineering 的最小实践单元先用 26 行定义一个可验证的代理再让代理们在契约下组合成团队。赞分享文档教程AI 技能【免费下载链接】claude-code-best-practicefrom vibe coding to agentic engineering - practice makes claude perfect项目地址https://gitcode.com/GitHub_Trending/cl/claude-code-best-practice点击查看免费下载相关推荐Delta Kernel 异常设计原则KernelException 体系与 Engine 异常包装机制全解析Delta Kernel 异常设计原则KernelException 体系与 Engine 异常包装机制全解析 导读 Delta Kernel 是一套用于构建文档教程AI 技能Claude Code 扩展机制选型指南Agent、Command 与 Skill 的定位对比与 Command → Agent → Skill 编排实战Claude Code 扩展机制选型指南Agent、Command 与 Skill 的定位对比与 Command → Agent → Skill 编排实战 本文档教程AI 技能用 Swarms Agent 构建黑客松项目自动评审智能体Hackathon Judge Agent 实战指南用 Swarms Agent 构建黑客松项目自动评审智能体Hackathon Judge Agent 实战指南 本篇指南基于 swarms 仓库中的 exam文档教程AI 技能上一篇61MB只要32秒百度网盘直链解析免费不装客户端下一篇PHPStan property.defaultValue 错误详解属性默认值与声明类型不匹配的静态检测与修复创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考