开源项目oh-my-claudecode分析——学习如何编写skill和agent

OMC Skill 与 Agent 编写规范对比指南本文档基于 oh-my-claudecode 项目源码整理目标是让大模型或开发者读完后如何能够学习omc的理念设计自己的 Skill 和 Agent 定义文件。一、定位差异一句话理解Agent “我是谁”——定义一个专职执行角色的身份、能力边界和行为规范。Skill “怎么办事”——定义一个可复用工作流的触发条件、执行步骤和调度逻辑。类比Agent 是团队中的岗位说明书如前端工程师、“安全审计员”Skill 是团队的SOP 流程手册如上线发布流程、“Bug 排查流程”。Agent 本身不决定何时被调用Skill 本身不执行具体实现。二、文件结构差异2.1 文件位置与命名维度AgentSkill目录agents/skills/{skill-name}/文件名{agent-name}.md如executor.mdSKILL.md固定名称放在以技能命名的子目录中命名风格名词角色executor, designer, critic, writer动词/动作短语plan, debug, cancel, autopilot单文件 vs 目录单个.md文件目录结构SKILL.md为入口可包含辅助文件2.2 YAML Frontmatter 字段对比Agent Frontmatter---name:executor# 必填角色标识符description:Focused task executor (Sonnet)# 必填角色描述通常注明模型级别model:claude-sonnet-4-6# 必填绑定的具体模型level:2# 必填Agent 层级1Haiku, 2Sonnet, 3OpusdisallowedTools:Write,Edit# 可选禁用的工具列表如 critic 只读不写---Skill Frontmatter---name:omc-plan# 必填技能标识符description:Strategic planning with interview# 必填技能描述argument-hint:[--direct|--consensus] task# 可选参数提示Agent 没有此字段pipeline:[deep-interview,omc-plan,autopilot]# 可选技能链定义Agent 没有此字段next-skill:autopilot# 可选下一个接力技能Agent 没有此字段next-skill-args:--direct# 可选后继技能的参数Agent 没有此字段handoff:.omc/plans/ralplan-*.md# 可选交接产物路径Agent 没有此字段level:4# 可选技能层级---关键字段差异总结字段AgentSkill说明name✅ 必填✅ 必填Agent 是角色名词Skill 是动作名词description✅ 必填✅ 必填Agent 描述中通常注明模型如 “Sonnet”Skill 不注明model✅ 必填❌ 无Agent 绑定模型Skill 不绑定由内部调度的 Agent 各自决定模型level✅ 必填⚠️ 可选Agent level 对应模型层1/2/3Skill level 对应复杂度disallowedTools⚠️ 可选❌ 无部分 Agent 需要工具限制如 critic 禁止 Write/Editargument-hint❌ 无⚠️ 可选仅 Skill 有告诉用户怎么传参pipeline❌ 无⚠️ 可选仅 Skill 有定义多技能链next-skill❌ 无⚠️ 可选仅 Skill 有指定后继技能next-skill-args❌ 无⚠️ 可选仅 Skill 有后继技能的参数handoff❌ 无⚠️ 可选仅 Skill 有交接产物的文件路径三、Markdown 正文结构对比3.1 Agent 正文结构Agent 正文用Agent_Prompt包裹内部使用 XML 标签组织是一份注入到 subagent 上下文的 system prompt。Agent_Prompt Role !-- 必填我是谁、我负责什么、我不负责什么 -- Why_This_Matters !-- 必填为什么这些规则存在失败的代价 -- Success_Criteria !-- 必填怎样算完成得好 -- Constraints !-- 必填硬性约束和禁止事项 -- Investigation_Protocol !-- 必填拿到任务后的思考和探索步骤 -- Tool_Usage !-- 必填允许使用哪些工具、怎么用 -- Execution_Policy !-- 必填执行力度策略 -- Output_Format !-- 必填完成后输出什么格式 -- Failure_Modes_To_Avoid !-- 必填常见错误模式及对策 -- Examples !-- 必填Good/Bad 示例对比 -- Final_Checklist !-- 必填完成前的自检清单 -- /Agent_Prompt3.2 Skill 正文结构Skill 正文不使用Agent_Prompt包裹使用独立的 XML 标签组织是一份注入到 orchestrator 上下文的工作流剧本。复杂 Skill如 plan、ralph、autopilotPurpose !-- 必填这个 Skill 做什么 -- Use_When !-- 必填什么场景下使用Agent 没有此标签 -- Do_Not_Use_When !-- 必填什么场景下不要使用Agent 没有此标签 -- Why_This_Exists !-- 必填为什么需要这个 Skill -- Execution_Policy !-- 必填执行策略和并发规则 -- Steps !-- 必填分步骤的工作流编排Agent 没有此标签 -- Tool_Usage !-- 必填调度哪些 Agent、调用哪些工具 -- Examples !-- 必填Good/Bad 示例 -- Escalation_And_Stop_Conditions !-- 必填何时升级、何时停止Agent 没有此标签 -- Final_Checklist !-- 必填完成检查清单 -- Advanced !-- 可选高级配置、补充说明 --简单 Skill如 debug、cancel# Skill Name ## Goal !-- 对应 Purpose -- ## Workflow !-- 对应 Steps -- ## Rules !-- 对应 Constraints -- ## Output !-- 对应 Output_Format --注意简单 Skill 可以用标准 Markdown 标题代替 XML 标签但复杂 Skill 建议统一使用 XML 标签以保持解析一致性。四、内容写法的核心差异4.1 叙事视角维度AgentSkill人称第二人称“You are Executor”第三人称/祈使句“Plan creates comprehensive plans”对话对象对即将扮演该角色的 LLM 说话对即将编排工作流的 orchestrator 说话语气角色扮演式“Your mission is…”流程说明式“When user says X, do Y”Agent 示例“You are Executor. Your mission is to implement code changes precisely as specified. You are not responsible for architecture decisions.”Skill 示例“Ralph is a PRD-driven persistence loop that keeps working on a task until ALL user stories have passes: true.”4.2 是否包含流程控制能力AgentSkill条件分支❌ 没有 if/else 流程✅ 有模式选择如 Interview/Direct/Consensus循环迭代❌ 不定义循环✅ 有重试/迭代逻辑如 “max 5 iterations”状态管理❌ 不管理持久状态✅ 有 state_write/state_read/state_clear跨步骤 handoff❌ 不涉及✅ 有Skill(oh-my-claudecode:ralph)等链式调用模式参数❌ 无参数概念✅ 有--direct、--consensus、--force等4.3 Agent 调度方式维度AgentSkill调度其他 Agent⚠️ 有限仅 explore 类辅助查询✅ 核心职责大量Task(subagent_type...)调度其他 Skill❌ 不调度 Skill✅ 通过Skill(name)调度被谁调度被 orchestrator 或 Skill 通过Task(subagent_typeoh-my-claudecode:agent-name)调度被用户通过/oh-my-claudecode:skill-name触发或被其他 Skill 链式调用4.4 模板变量维度AgentSkill模板变量❌ 不使用✅ 使用{{PROMPT}}、{{ITERATION}}、{{MAX}}等上下文传入方式通过Task(prompt...)的 message 参数通过 hook 系统的模板替换机制4.5 触发机制维度AgentSkill触发方式被程序化调度Task(subagent_type...)关键词自动触发 或 手动/skill-nameUse_When❌ 没有✅ 有明确的使用场景列表Do_Not_Use_When❌ 没有✅ 有明确的不适用场景列表五、Agent 各标签编写规范Role— 角色定义三句话结构你是谁“You are {Name}.”你负责什么“You are responsible for {A}, {B}, and {C}.”你不负责什么“You are not responsible for {X}, {Y}, or {Z}.”RoleYou are Executor. Your mission is to implement code changes precisely as specified. You are responsible for writing, editing, and verifying code within the scope of your assigned task. You are not responsible for architecture decisions, planning, debugging root causes, or reviewing code quality./Role关键原则明确画出职责边界。不负责什么和负责什么同样重要——它防止 Agent 越权。Why_This_Matters— 为什么这些规则重要解释失败的代价激活 LLM 的审慎模式Why_This_MattersExecutors that over-engineer, broaden scope, or skip verification create more work than they save. These rules exist because the most common failure mode is doing too much, not too little. A small correct change beats a large clever one./Why_This_MattersSuccess_Criteria— 成功标准使用可验证的条件列表避免模糊描述Success_Criteria- The requested change is implemented with the smallest viable diff - All modified files pass lsp_diagnostics with zero errors - Build and tests pass (fresh output shown, not assumed) - No new abstractions introduced for single-use logic/Success_Criteria反面示例“代码质量好”、“实现完整”——这些不可验证。Constraints— 硬性约束使用祈使句每条一个明确禁止或要求Constraints- Work ALONE for implementation. READ-ONLY exploration via explore agents is permitted. - Prefer the smallest viable change. Do not broaden scope beyond requested behavior. - Plan files (.omc/plans/*.md) are READ-ONLY. Never modify them. - After 3 failed attempts on the same issue, escalate to architect agent with full context./ConstraintsInvestigation_Protocol— 调查协议定义拿到任务后的思考路径使用编号步骤Investigation_Protocol1) Classify the task: Trivial, Scoped, or Complex. 2) Read the assigned task and identify exactly which files need changes. 3) For non-trivial tasks, explore first: Glob, Grep, Read, ast_grep_search. 4) Answer before proceeding: Where is this? What patterns? What tests? What could break? 5) Discover code style: naming, error handling, imports. Match them. 6) Create a TodoWrite with atomic steps when the task has 2 steps./Investigation_ProtocolTool_Usage— 工具使用说明明确每个工具的用途和使用时机Tool_Usage- Use Edit for modifying existing files, Write for creating new files. - Use Bash for running builds, tests, and shell commands. - Use lsp_diagnostics on each modified file to catch type errors early. - Use Glob/Grep/Read for understanding existing code before changing it.External_ConsultationWhen a second opinion would improve quality, spawn a Claude Task agent: - Use Task(subagent_typeoh-my-claudecode:architect, ...) for architectural cross-checks Skip silently if delegation is unavailable. Never block on external consultation./External_Consultation/Tool_UsageExecution_Policy— 执行策略根据任务复杂度分级描述执行力度Execution_Policy- Default effort: match complexity to task classification. - Trivial tasks: skip extensive exploration, verify only modified file. - Scoped tasks: targeted exploration, verify modified files run relevant tests. - Complex tasks: full exploration, full verification suite. - Start immediately. No acknowledgments. Dense output over verbose./Execution_PolicyOutput_Format— 输出格式定义完成后的输出结构模板Output_Format## Changes Made - file.ts:42-55: [what changed and why] ## Verification - Build: [command] - [pass/fail] - Tests: [command] - [X passed, Y failed] ## Summary [1-2 sentences on what was accomplished]/Output_FormatFailure_Modes_To_Avoid— 避免的失败模式每条包含错误行为 正确替代方案Failure_Modes_To_Avoid- Overengineering: Adding abstractions not required. Instead, make the direct change. - Scope creep: Fixing while Im here issues. Instead, stay within requested scope. - Premature completion: Saying done before verification. Instead, show fresh output./Failure_Modes_To_AvoidExamples— Good/Bad 示例用简短的场景对比说明正确和错误的做法ExamplesGoodTask: Add timeout to fetchData(). Executor adds parameter with default, threads it through, updates the one test. 3 lines changed./GoodBadTask: Add timeout to fetchData(). Executor creates TimeoutConfig class, retry wrapper, refactors all callers. 200 lines. Scope far exceeded./Bad/ExamplesFinal_Checklist— 最终检查清单使用问句形式的自检列表Final_Checklist- Did I verify with fresh build/test output (not assumptions)? - Did I keep the change as small as possible? - Are all TodoWrite items marked completed? - Did I check for leftover debug code?/Final_Checklist六、Skill 各标签编写规范Purpose— 技能目的一段话说明这个 Skill 做什么、产出什么PurposePlan creates comprehensive, actionable work plans through intelligent interaction. It auto-detects whether to interview the user or plan directly, and supports consensus mode (iterative Planner/Architect/Critic loop)./PurposeUse_When— 使用时机列出触发关键词和典型场景Use_When- User wants to plan before implementing -- plan this, lets plan - User wants structured requirements gathering for a vague idea - Task is broad or vague and needs scoping before any code is written/Use_WhenDo_Not_Use_When— 不适用场景列出应该用其他 Skill/Agent 的场景并给出替代方案Do_Not_Use_When- User wants autonomous end-to-end execution -- use autopilot instead - User wants to start coding immediately -- use ralph or delegate to executor - User asks a simple question -- just answer it/Do_Not_Use_When这个对 Agent 不存在的标签是 Skill 的关键特征——它帮助 keyword-detector 和 skill-injector 做精确匹配避免错误激活。Steps— 步骤编排Skill 正文的核心定义分阶段的执行流程。可以包含模式选择表格| Mode | Trigger | Behavior | |------|---------|----------| | Interview | Default for broad requests | Interactive requirements gathering | | Direct | --direct, or detailed request | Skip interview, generate plan directly | | Consensus | --consensus | Planner → Architect → Critic loop |编号步骤含条件分支和循环1. **Phase 0 - Expansion**: Turn users idea into spec - **If consensus plan exists**: Skip Phase 0 and Phase 1, jump to Phase 2 - **If input is vague**: Offer redirect to /deep-interview - **Otherwise**: Analyst extracts requirements, Architect creates spec 2. **Phase 1 - Planning**: Create implementation plan 3. **Phase 2 - Execution**: Implement using Ralph Ultrawork - Executor (Haiku): Simple tasks - Executor (Sonnet): Standard tasks - Executor (Opus): Complex tasks - Run independent tasks in parallel 4. **Phase 3 - QA**: Cycle until all tests pass (max 5 cycles) - Stop early if same error repeats 3 times状态管理指令- **On entry**: Call state_write(moderalplan, activetrue, session_id...) - **On handoff to execution**: Call state_write(moderalplan, activefalse, session_id...) - **On terminal exit**: Call state_clear(moderalplan, session_id...)Execution_Policy— 执行策略定义并发规则、超时、重试等运行时约束Execution_Policy- Each phase must complete before the next begins - Parallel execution is used within phases where possible - QA cycles repeat up to 5 times; same error 3 times → stop and report - Cancel with /oh-my-claudecode:cancel at any time/Execution_PolicyTool_Usage— 工具/Agent 调度说明Skill 的 Tool_Usage重点在于调度 Agent而非直接使用底层工具Tool_Usage- Use Task(subagent_typeoh-my-claudecode:architect, ...) for architecture validation - Use Task(subagent_typeoh-my-claudecode:security-reviewer, ...) for security review - Use Task(subagent_typeoh-my-claudecode:critic, ...) for plan review - Use Skill(oh-my-claudecode:ralph) for execution handoff - CRITICAL: Consensus mode agent calls MUST be sequential, never parallel./Tool_UsageEscalation_And_Stop_Conditions— 升级与停止条件Agent 没有此标签。Skill 需要明确定义何时停止、何时升级到人工介入Escalation_And_Stop_Conditions- Stop when user says stop, cancel, or abort - Stop after 5 iterations if consensus not reached - If same QA error persists 3 cycles, report fundamental issue - Escalate when irreconcilable trade-offs require business decision/Escalation_And_Stop_ConditionsAdvanced— 高级配置Agent 没有此标签。Skill 可以在此放置可选配置、恢复机制、排障指南等Advanced## Configuration Optional settings in .claude/settings.json: { omc: { autopilot: { maxIterations: 10, maxQaCycles: 5 } } } ## Resume Run /oh-my-claudecode:autopilot again to resume from where it stopped./Advanced七、完整模板7.1 Agent 完整模板--- name: {agent-name} description: {一句话描述角色和职责} ({Model-Name}) model: {claude-haiku-4-5 | claude-sonnet-4-6 | claude-opus-4-6} level: {1 | 2 | 3} disallowedTools: {可选逗号分隔的禁用工具} --- Agent_Prompt Role You are {Name}. Your mission is to {核心使命}. You are responsible for {职责 A}, {职责 B}, and {职责 C}. You are not responsible for {非职责 X}, {非职责 Y}, or {非职责 Z}. /Role Why_This_Matters {解释为什么这些规则重要失败的代价是什么。} /Why_This_Matters Success_Criteria - {可验证的成功条件 1} - {可验证的成功条件 2} - {可验证的成功条件 3} /Success_Criteria Constraints - {硬性约束 1} - {硬性约束 2} - {禁止事项} /Constraints Investigation_Protocol 1) {拿到任务后的第一步} 2) {探索和理解步骤} 3) {关键问题自查} 4) {制定执行计划} /Investigation_Protocol Tool_Usage - Use {Tool A} for {用途}. - Use {Tool B} for {用途}. External_Consultation When a second opinion would improve quality: - Use Task(subagent_typeoh-my-claudecode:{agent}, ...) for {用途} Skip silently if unavailable. Never block on external consultation. /External_Consultation /Tool_Usage Execution_Policy - Default effort: {执行力度策略}. - {简单任务的策略} - {复杂任务的策略} - Start immediately. No acknowledgments. /Execution_Policy Output_Format ## {输出板块 1} - {输出内容模板} ## {输出板块 2} - {输出内容模板} /Output_Format Failure_Modes_To_Avoid - {错误模式}: {描述}. Instead, {正确做法}. - {错误模式}: {描述}. Instead, {正确做法}. /Failure_Modes_To_Avoid Examples Good{正确做法的具体场景描述}/Good Bad{错误做法的具体场景描述}/Bad /Examples Final_Checklist - {自检问题 1}? - {自检问题 2}? - {自检问题 3}? /Final_Checklist /Agent_Prompt7.2 Skill 完整模板复杂 Skill--- name: {skill-name} description: {一句话描述技能} argument-hint: [--option1|--option2] task description pipeline: [{前置技能}, {当前技能}, {后续技能}] next-skill: {后续技能名} next-skill-args: {后继技能参数} handoff: .omc/{交接产物路径} level: {2 | 3 | 4} --- Purpose {这个 Skill 做什么解决什么问题产出什么。1-3 句话。} /Purpose Use_When - {使用场景 1} -- {触发关键词} - {使用场景 2} - {使用场景 3} /Use_When Do_Not_Use_When - {不适用场景 1} -- use {替代方案} instead - {不适用场景 2} -- use {替代方案} instead /Do_Not_Use_When Why_This_Exists {为什么需要这个 Skill没有它会怎样。} /Why_This_Exists Execution_Policy - {并发规则} - {超时/重试策略} - {阶段间依赖关系} /Execution_Policy Steps ### Mode Selection如有多模式 | Mode | Trigger | Behavior | |------|---------|----------| | {模式 A} | {触发条件} | {行为描述} | | {模式 B} | {触发条件} | {行为描述} | ### {阶段名称} 1. **Step 1 - {步骤名}**: {做什么} - **If {条件 A}**: {分支 A 行为} - **If {条件 B}**: {分支 B 行为} - **Otherwise**: {默认行为} - 状态管理state_write(mode{mode}, activetrue, session_id...) 2. **Step 2 - {步骤名}**: {做什么} - 调度Task(subagent_typeoh-my-claudecode:{agent}, prompt...) - **Wait for completion before proceeding to Step 3.** 3. **Step 3 - {步骤名}**: {做什么} 4. **Re-review loop** (max N iterations): If rejected: a. Collect feedback b. Revise c. Return to Step 2 d. Repeat until approved OR max iterations reached /Steps Tool_Usage - Use Task(subagent_typeoh-my-claudecode:{agent}, ...) for {用途} - Use Skill(oh-my-claudecode:{skill}) for {用途} - Use AskUserQuestion for {用途} - CRITICAL: {关键的调度顺序约束} /Tool_Usage Examples Good {正确使用场景} Why good: {解释} /Good Bad {错误使用场景} Why bad: {解释} /Bad /Examples Escalation_And_Stop_Conditions - Stop when {停止条件 1} - Stop when {停止条件 2} - Escalate when {升级条件} /Escalation_And_Stop_Conditions Final_Checklist - [ ] {检查项 1} - [ ] {检查项 2} - [ ] {状态清理检查} /Final_Checklist Advanced ## Configuration {可选配置} ## Resume {恢复机制} /Advanced7.3 Skill 完整模板简单 Skill--- name: {skill-name} description: {一句话描述} --- # {Skill Name} {一段话说明用途} ## Goal {目标描述} ## Workflow 1. {步骤 1} 2. {步骤 2} 3. {步骤 3} ## Rules - {规则 1} - {规则 2} ## Output - {输出项 1} - {输出项 2}八、编写 Checklist编写 Agent 前的自查这个角色有明确的职责边界吗能说清负责什么和不负责什么吗它是一个执行者角色写代码、跑测试、写文档等具体动作吗它需要绑定到一个特定的模型级别Haiku/Sonnet/Opus吗它的成功标准是否每条都可以通过工具调用来验证它是否需要限制某些工具如只读 Agent 应该disallowedTools: Write, Edit编写 Skill 前的自查这是一个多步骤工作流吗包含条件分支、循环、或跨 Agent 调度吗它需要被用户通过关键词触发吗它是否调度多个 Agent 协作完成任务它是否需要管理持久状态state_write/state_read/state_clear它是否有明确的不适用场景需要引导到其他 Skill它是否需要接力到其他 Skillpipeline/next-skill选择创建 Agent 还是 Skill 的决策树用户需求 ├─ 需要定义一个专职角色来执行具体任务 │ └─ → 创建 Agent │ 例写代码、做审计、跑测试、写文档 │ ├─ 需要定义一个工作流程来协调多个步骤/角色 │ └─ → 创建 Skill │ 例规划→实现→验证的端到端流程 │ └─ 需要一个关键词触发的快捷操作 └─ → 创建 Skill 例/cancel、/debug、/setup九、实际案例参考类型文件复杂度特点Agent简单agents/writer.md~4KBHaiku 模型、最小权限、简洁的 Investigation ProtocolAgent标准agents/executor.md~7KBSonnet 模型、分级执行策略、External_ConsultationAgent复杂agents/critic.md~21KBOpus 模型、禁用 Write/Edit、5 阶段调查协议、自适应严厉度Skill简单skills/debug/SKILL.md~0.5KB纯 Markdown 标题、无 XML 标签、无状态管理Skill中等skills/autopilot/SKILL.md~5KB5 阶段流程、Agent 调度、QA 循环Skill复杂skills/plan/SKILL.md~12KB4 种模式、共识循环、状态生命周期、跨 Skill handoffSkill重型skills/ralph/SKILL.md~10KBPRD 驱动、迭代验证、模板变量、deslop pass十、常见误区误区说明正确做法在 Agent 里写流程编排Agent 不该有 “Step 1 调 architect, Step 2 调 critic”Agent 只描述自己的行为编排逻辑放 Skill在 Skill 里写角色定义Skill 不该有 “You are a planner, your mission is…”Skill 定义流程角色行为放 AgentAgent 的 frontmatter 没写 model缺少 model 会导致运行时无法确定使用哪个模型必须指定 modelSkill 的 frontmatter 写了 modelSkill 不绑定模型删除 model 字段由被调度的 Agent 决定模型Agent 写了Use_WhenAgent 不需要声明使用场景它被主动调度删除Agent 由 orchestrator 或 Skill 选择Skill 没写Do_Not_Use_When缺少排除场景可能导致 Skill 被错误触发补充不适用场景和替代方案Skill 中直接写实现代码Skill 是编排者不该自己写 src 代码通过Task(subagent_type...)委派给 AgentAgent 的 Examples 只有 Good缺少反面教材LLM 可能重复常见错误Good/Bad 必须成对出现Skill 的 Steps 没有状态清理缺少 state_clear 会导致 stop hook 无法正常退出每个退出路径都要有状态清理指令