Back to Details

skill-editor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Editor

Skill Editor

Comprehensive multi-agent workflow system for editing Claude Code skills with structured phases, quality gates, and expert review.
这是一个用于编辑Claude Code技能的综合性多Agent工作流系统，具备结构化阶段、质量关卡和专家评审功能。

When to Use This Skill

何时使用此技能

Use this skill when:
  1. Creating new skills: User wants to add a new skill to the repository
  2. Modifying existing skills: User wants to update, enhance, or refactor a skill
  3. Complex skill changes: Change involves multiple files, agents, or architectural decisions
  4. Quality assurance needed: Change requires thorough review and validation
This skill provides:
  • Structured 4-phase workflow (2 modes: QUICK and FULL)
  • Interactive requirements refinement
  • Multi-perspective swarm analysis via brainstorming-pm delegation (FULL mode)
  • Domain-specific edge-case analysis (FULL mode)
  • Adversarial review before implementation (FULL mode)
  • Automated validation and testing
  • Integration with sync-config.py and planning journal
在以下场景使用此技能：
  1. 创建新技能：用户希望向仓库中添加新技能
  2. 修改现有技能：用户希望更新、增强或重构某一技能
  3. 复杂技能变更：变更涉及多个文件、Agent或架构决策
  4. 需要质量保证：变更需要全面的评审和验证
此技能提供：
  • 结构化的4阶段工作流（两种模式：QUICK快速模式和FULL完整模式）
  • 交互式需求细化
  • 通过头脑风暴PM委托实现多视角群体分析（仅FULL模式）
  • 特定领域的边缘案例分析（仅FULL模式）
  • 实施前的对抗性评审（仅FULL模式）
  • 自动化验证和测试
  • 与sync-config.py和规划日志集成

When NOT to Use This Skill

何时不使用此技能

Do NOT use this skill when:
  • Simple documentation fixes: Typo fixes, minor documentation updates (edit directly)
  • Non-skill changes: Modifying agents, settings, or other configuration
  • Urgent hotfixes: Emergency fixes that can't wait for full workflow
  • Exploratory work: Just browsing or understanding skills (use Read or Explore agent)
请勿在以下场景使用此技能：
  • 简单文档修复：拼写错误修复、微小文档更新（直接编辑即可）
  • 非技能变更：修改Agent、设置或其他配置
  • 紧急热修复：无法等待完整工作流的紧急修复
  • 探索性工作：仅浏览或了解技能（使用Read或Explore Agent）

Delegation Mandate

委托规则

You are an orchestrator. You coordinate specialist agents -- you do not perform specialist analysis, research, or implementation yourself.
You ARE the coordinator who ensures analysis, research, review, and implementation happen through delegation to specialist agents via Task tool.
You are NOT an analyst, researcher, reviewer, or implementor. You do not perform best-practices analysis, external research, edge-case simulation, knowledge-engineering analysis, adversarial review, or code implementation yourself.
Orchestrator-owned tasks (you DO perform these yourself):
  • Session setup, directory creation, state file management
  • Mode detection and user interaction for mode selection
  • Quality gate evaluation (checking that agent outputs meet criteria)
  • User communication (presenting options, gathering decisions)
  • Workflow routing (determining which phase to execute next)
  • Pre-flight validation (git checks, file existence)
  • Orchestrator detection (determining if target skill is an orchestrator)
你是一名编排者。你负责协调专业Agent——你自己不执行专业分析、研究或实施工作。
你作为协调者的职责是：通过Task工具委托给专业Agent，确保分析、研究、评审和实施工作得以开展。
你不是分析师、研究员、评审员或实施者。你不得自行执行最佳实践分析、外部研究、边缘案例模拟、知识工程分析、对抗性评审或代码实施工作。
编排者专属任务（你需要自行执行这些任务）：
  • 会话设置、目录创建、状态文件管理
  • 模式检测和用户交互以选择模式
  • 质量关卡评估（检查Agent输出是否符合标准）
  • 用户沟通（呈现选项、收集决策）
  • 工作流路由（确定下一阶段执行内容）
  • 预执行验证（git检查、文件存在性验证）
  • 编排者检测（确定目标技能是否为编排者类型）

When You Might Be Resisting Delegation

你可能抗拒委托的情况

RationalizationReality
"This analysis is too simple to delegate"Simple tasks still consume context window. Delegate.
"I can do it faster myself"Speed is not the goal; context isolation and specialist quality are.
"The agent will just repeat what I already know"The agent provides independent verification. Your knowledge may be incomplete.
"It's just a quick read of the file"Reading specialist content to make specialist decisions IS specialist work.
Self-check before every action: "Am I about to load specialist instructions into my context so I can do their work? If yes, use Task tool instead."
自我合理化理由实际情况
"这个分析太简单了，不需要委托"简单任务仍会占用上下文窗口，应委托。
"我自己做更快"速度不是目标；上下文隔离和专业质量才是。
"Agent只会重复我已经知道的内容"Agent提供独立验证，你的知识可能存在遗漏。
"只是快速读取文件而已"读取专业内容并做出专业决策属于专业工作范畴。
每次行动前自我检查："我是否要加载专业指令到自己的上下文来执行他们的工作？如果是，请改用Task工具。"

State Anchoring

状态锚定

Start every response with a phase indicator:
[Phase N/4 - {phase_name}] {brief status}
Examples:
  • [Phase 1/4 - Refinement] Gathering requirements from user
  • [Phase 2/4 - Analysis] Swarm complete, waiting for edge-case-simulator
  • [Phase 3/4 - Decision] Synthesizing swarm + edge-case reports
  • [Phase 4/4 - Execution] Implementing change 3/12
Protocol:
  1. Before starting any phase: Read 
    ${SESSION_DIR}/session-state.json
    . Confirm current_phase matches expectations.
  2. After any user interaction: Answer the user, then re-anchor with phase indicator.
  3. If phase indicator and state file disagree: Trust state file, not memory.
每条回复开头需包含阶段指示器：
[Phase N/4 - {phase_name}] {brief status}
示例：
  • [Phase 1/4 - Refinement] 向用户收集需求
  • [Phase 2/4 - Analysis] 群体分析完成，等待边缘案例模拟器输出
  • [Phase 3/4 - Decision] 综合群体分析与边缘案例报告
  • [Phase 4/4 - Execution] 正在实施第3项变更，共12项
协议：
  1. 开始任何阶段前：读取
    ${SESSION_DIR}/session-state.json
    ，确认current_phase与预期一致。
  2. 任何用户交互后：回复用户，然后重新添加阶段指示器。
  3. 如果阶段指示器与状态文件不一致：以状态文件为准，而非记忆。

Tool Selection

工具选择

SituationToolReason
Phase 2 swarm analysisTask tool (brainstorming-pm)Multi-perspective analysis via swarm delegation
Phase 2 edge-case analysisTask tool (edge-case-simulator)Domain-specific failure modes, parallel with swarm
Phase 3 adversarial reviewTask tool (adversarial-reviewer)Independent, skeptical review
Phase 4 implementationTask tool (executor)Isolated execution environment
Loading reference docs for YOUR routing decisionsRead toolOrchestrator decision support
Loading skill instructions to decide WHICH specialist to invokeRead tool (brief scan)Routing information, not specialist work
User interaction (questions, approvals, options)AskUserQuestionStructured user communication
File operations (create, modify files)Write tool (via executor agent)Delegated to executor specialist
Validation scripts, git operationsBash toolInfrastructure commands
Self-check: "Am I about to load specialist instructions into my context so I can do their work? If yes, use Task tool instead."
场景工具原因
阶段2群体分析Task工具（brainstorming-pm）通过群体委托实现多视角分析
阶段2边缘案例分析Task工具（edge-case-simulator）特定领域故障模式分析，与群体分析并行执行
阶段3对抗性评审Task工具（adversarial-reviewer）独立、批判性的评审
阶段4实施Task工具（executor）隔离的执行环境
为你的路由决策加载参考文档Read工具编排者决策支持
加载技能指令以决定调用哪个专业AgentRead工具（快速扫描）路由信息，非专业工作
用户交互（问题、审批、选项）AskUserQuestion结构化用户沟通
文件操作（创建、修改文件）Write工具（通过executor Agent）委托给executor专业人员
验证脚本、git操作Bash工具基础设施命令
自我检查："我是否要加载专业指令到自己的上下文来执行他们的工作？如果是，请改用Task工具。"

Workflow Overview

工作流概述

QUICK MODE (~30 min)
├── Phase 1: Refinement
├── [SKIP Phase 2]
├── Phase 3: Lightweight plan (orchestrator creates minimal plan)
└── Phase 4: Execution (Gate 3 always runs)

FULL MODE (~1.5-2 hrs) [Default]
├── Phase 1: Refinement
├── Phase 2: Swarm + Edge-case analysis (parallel)
├── Phase 3: Inline synthesis + Adversarial review
└── Phase 4: Execution (Gate 3 always runs)
QUICK MODE (~30 min)
├── Phase 1: 需求细化
├── [跳过 Phase 2]
├── Phase 3: 轻量级计划（编排者创建最小化计划）
└── Phase 4: 实施（始终执行关卡3）

FULL MODE (~1.5-2 hrs) [默认]
├── Phase 1: 需求细化
├── Phase 2: 群体分析 + 边缘案例分析（并行）
├── Phase 3: 内综合 + 对抗性评审
└── Phase 4: 实施（始终执行关卡3）

Workflow

工作流

Pre-Workflow: Safety Checks

预工作流：安全检查

Before starting workflow, run the session management script which performs:
  • Git safety checks (uncommitted changes, merge/rebase detection, detached HEAD)
  • sync-config.py status verification
  • Directory verification (must be repo root)
  • Archival awareness detection
  • Trap handler registration for graceful interrupt
  • Session management commands (
    --list-sessions
    , 
    --cleanup
    )
  • Resume protocol with multi-session support (including legacy format migration)
  • Session directory creation and state initialization
Implementation: See 
references/session-management.sh
for complete bash.
If checks fail: Ask user to resolve before proceeding.
开始工作流前，运行会话管理脚本执行以下操作：
  • Git安全检查（未提交的变更、合并/变基检测、分离HEAD状态）
  • sync-config.py状态验证
  • 目录验证（必须在仓库根目录）
  • 归档感知检测
  • 注册陷阱处理程序以实现优雅中断
  • 会话管理命令（
    --list-sessions
    、
    --cleanup
    ）
  • 支持多会话的恢复协议（包括旧格式迁移）
  • 会话目录创建和状态初始化
实现：完整bash脚本见
references/session-management.sh
。
如果检查失败：请用户解决后再继续。

If User Cancels (Ctrl+C)

如果用户取消（Ctrl+C）

Session state is preserved in 
${SESSION_DIR}/session-state.json
.
On next invocation:
  1. Offer to resume from last phase
  2. If declined, session remains in /tmp/skill-editor-session/{session-id}
  3. Re-sync if needed: 
    ./sync-config.py push
会话状态将保存在
${SESSION_DIR}/session-state.json
中。
下次调用时：
  1. 提供从最后阶段恢复的选项
  2. 如果用户拒绝恢复，会话将保留在
    /tmp/skill-editor-session/{session-id}
    中
  3. 如需重新同步：
    ./sync-config.py push

Phase 1: Refinement (Interactive)

阶段1：需求细化（交互式）

Objective: Transform user's request into detailed, unambiguous specification.
Agent: 
skill-editor-request-refiner
Model: Opus 4.6
Process:
  1. Launch request-refiner agent via Task tool
  2. Agent asks clarifying questions to understand:
    • What user wants to change
    • Why they want this change
    • What success looks like
    • What's in scope vs. out of scope
  3. Agent reads existing skill (if modifying)
  4. Agent establishes clear boundaries and success criteria
  5. Agent presents refined specification to user
Output File: 
${SESSION_DIR}/refined-specification.md
containing:
  • Objective (one sentence)
  • Scope (IN/OUT lists)
  • Success criteria (measurable)
  • Files affected
  • User approval
Quality Gate 1: Specification Approval
User must approve:
  • Specification matches intent
  • Scope is appropriate
  • Success criteria are clear
  • Ready to proceed to analysis
If Gate 1 fails: Return to request-refiner for more refinement.
If Gate 1 passes: Update session state and proceed to Mode Selection.
Post-Gate 1: Orchestrator Detection
After specification approval, determine if the target skill is an orchestrator:
  1. Read target SKILL.md (if editing an existing skill)
  2. Score against detection criteria:
SignalScoreCheck
Name contains orchestrator keyword (pm, coordinator, orchestrator, pipeline, architect)+1Check skill name
Description mentions coordination terms (coordinate, orchestrate, multi-agent, pipeline)+1Check description field
Delegates to other skills via Task tool+2Search for Task tool usage
Has named phases/stages with sequential progression+1Search for Phase/Stage headers
Has quality gates between phases+1Search for Gate references
Manages session state across phases+1Search for state file management
  1. Apply thresholds:
    • Score >= 4: 
      "Detected as orchestrator (confidence: high). Apply orchestrator analysis? [Y/n]"
    • Score 2-3: 
      "May be an orchestrator (confidence: medium). Apply orchestrator analysis? [y/N]"
    • Score 0-1: Not an orchestrator. Skip orchestrator analysis.
    • Always append: 
      "If this IS an orchestrator, reply 'orchestrator' to enable pattern analysis."
  2. If creating a new skill: Ask directly: "Will this skill orchestrate other skills? [y/N]"
  3. Record detection result in session state:
    json
    "orchestrator_detected": true/false,
"orchestrator_confidence": "high"/"medium"/"none",
"orchestrator_user_confirmed": true/false
Update session state to phase 1.5 with 
agents_completed: ["request-refiner"]
.
目标：将用户请求转换为详细、明确的规范。
Agent：
skill-editor-request-refiner
模型：Opus 4.6
流程：
  1. 通过Task工具启动request-refiner Agent
  2. Agent提出澄清问题以了解：
    • 用户想要更改什么
    • 用户为什么想要此更改
    • 成功的标准是什么
    • 哪些内容在范围内，哪些在范围外
  3. Agent读取现有技能（如果是修改操作）
  4. Agent建立清晰的边界和成功标准
  5. Agent向用户呈现细化后的规范
输出文件：
${SESSION_DIR}/refined-specification.md
，包含：
  • 目标（一句话）
  • 范围（IN/OUT列表）
  • 成功标准（可衡量）
  • 受影响的文件
  • 用户批准
质量关卡1：规范批准
用户必须批准：
  • 规范符合用户意图
  • 范围合适
  • 成功标准清晰
  • 准备进入分析阶段
如果关卡1失败：返回至request-refiner进行进一步细化。
如果关卡1通过：更新会话状态并进入模式选择阶段。
关卡1后：编排者检测
规范批准后，确定目标技能是否为编排者类型：
  1. 读取目标SKILL.md（如果是编辑现有技能）
  2. 根据检测标准评分：
信号分数检查内容
名称包含编排者关键词（pm、coordinator、orchestrator、pipeline、architect）+1检查技能名称
描述中提及协调术语（coordinate、orchestrate、multi-agent、pipeline）+1检查描述字段
通过Task工具委托给其他技能+2搜索Task工具的使用情况
具有命名的阶段/步骤且按顺序推进+1搜索Phase/Stage标题
阶段之间有质量关卡+1搜索Gate引用
跨阶段管理会话状态+1搜索状态文件管理情况
  1. 应用阈值：
    • 分数≥4：
      "检测为编排者类型（置信度：高）。是否应用编排者分析？[Y/n]"
    • 分数2-3：
      "可能为编排者类型（置信度：中）。是否应用编排者分析？[y/N]"
    • 分数0-1：非编排者类型，跳过编排者分析。
    • 始终附加：
      "如果此技能确实是编排者类型，请回复'orchestrator'以启用模式分析。"
  2. 如果是创建新技能：直接询问："此技能是否将编排其他技能？[y/N]"
  3. 在会话状态中记录检测结果：
    json
    "orchestrator_detected": true/false,
"orchestrator_confidence": "high"/"medium"/"none",
"orchestrator_user_confirmed": true/false
更新会话状态至阶段1.5，
agents_completed: ["request-refiner"]
。

Mode Selection (After Phase 1)

模式选择（阶段1后）

Objective: Select workflow execution mode.
Trigger: After Quality Gate 1 passes (specification approved)
Decision rule:
  • Default: FULL
  • Auto-detect QUICK: Single file AND <50 lines AND (documentation OR typo OR comment fix)
  • User can always override in either direction
  • When uncertain: default to FULL (preserves safety)
Modes:
ModeWhenWhat runsDuration
QUICKDocumentation, typos, single-file fixesPhase 1 → Phase 3 (lightweight) → Phase 4~30 min
FULLEverything else (default)Phase 1 → Phase 2 (swarm + edge-case) → Phase 3 (synthesis + adversarial) → Phase 4~1.5-2 hrs
Record mode selection in session state and proceed.
目标：选择工作流执行模式。
触发条件：质量关卡1通过（规范已批准）
决策规则：
  • 默认：FULL完整模式
  • 自动检测QUICK快速模式：单个文件且<50行，且为文档/拼写错误/注释修复
  • 用户可随时双向覆盖默认选择
  • 不确定时：默认使用FULL完整模式（保障安全性）
模式详情：
模式适用场景执行流程时长
QUICK快速模式文档、拼写错误、单文件修复阶段1 → 阶段3（轻量级） → 阶段4~30分钟
FULL完整模式所有其他场景（默认）阶段1 → 阶段2（群体分析+边缘案例分析） → 阶段3（综合+对抗性评审） → 阶段4~1.5-2小时
在会话状态中记录模式选择并继续。

Phase 2: Analysis (FULL mode only)

阶段2：分析（仅FULL完整模式）

Objective: Analyze proposed change from multiple expert perspectives using two parallel tracks.
Agents (run in parallel):
  • Track A: 
    brainstorming-pm
    (swarm delegation) — multi-perspective analysis
  • Track B: 
    skill-editor-edge-case-simulator
    (Opus 4.6) — domain-specific failure modes
目标：通过两个并行轨道从多个专家视角分析提议的变更。
Agent（并行运行）：
  • 轨道A：
    brainstorming-pm
    （群体委托）——多视角分析
  • 轨道B：
    skill-editor-edge-case-simulator
    （Opus 4.6）——特定领域故障模式分析

Track A: Brainstorming-PM Swarm Delegation

轨道A：头脑风暴PM群体委托

  1. Read 
    references/swarm-challenge-templates.md
  2. Fill challenge template with values from refined specification:
    • Skill name, change type, file count, line count
    • Orchestrator detection result
    • Specification summary (objective + scope)
    • Current skill summary (if modifying existing skill)
  3. Invoke 
    brainstorming-pm
    via Task tool with the filled challenge template
  4. Receives convergent/divergent insights with confidence scores from 5-archetype swarm
Quality threshold: Synthesis must contain 2+ specific recommendations and 1+ alternative approach. If below threshold: log and proceed without swarm input.
Timeout: 15 minutes. On timeout: skip swarm, proceed with edge-case-simulator output only.
Orchestrator Analysis (conditional -- when orchestrator_detected is true):
  • Add to challenge template: "This skill is an orchestrator -- evaluate against orchestrator patterns in references/orchestrator-checklist.md (6 REQUIRED + 4 RECOMMENDED patterns)"
  1. 读取
    references/swarm-challenge-templates.md
  2. 使用细化规范中的值填充挑战模板：
    • 技能名称、变更类型、文件数量、代码行数
    • 编排者检测结果
    • 规范摘要（目标+范围）
    • 当前技能摘要（如果是修改现有技能）
  3. 通过Task工具调用
    brainstorming-pm
    并传入填充后的挑战模板
  4. 接收来自5种原型群体的收敛/发散见解及置信度评分
质量阈值：综合结果必须包含2+条具体建议和1+种替代方案。如果低于阈值：记录日志并在无群体输入的情况下继续。
超时：15分钟。超时后：跳过群体分析，仅使用边缘案例模拟器的输出继续。
编排者分析（条件触发——当orchestrator_detected为true时）：
  • 在挑战模板中添加："此技能为编排者类型——根据references/orchestrator-checklist.md中的编排者模式进行评估（6项必填+4项推荐模式）"

Track B: Edge-Case Simulator

轨道B：边缘案例模拟器

  1. Launch 
    skill-editor-edge-case-simulator
    via Task tool with refined specification
  2. Agent produces skill-specific failure mode matrix covering:
    • YAML parsing failures, sync-config.py edge cases
    • Task tool timeouts, git dirty state scenarios
    • Claude Code-specific boundary conditions
  3. Quality threshold: report exists and >100 words
Output Files:
  • ${SESSION_DIR}/swarm-synthesis.md
    (from brainstorming-pm, or absent if skipped/degraded)
  • ${SESSION_DIR}/edge-cases.md
    (from edge-case-simulator)
Quality Gate 2: Analysis Completion
Track A (swarm)Track B (edge-case)Action
CompleteCompletePASS
Below thresholdCompletePASS with note (graceful degradation)
TimeoutCompletePASS with note (proceed without swarm)
AnyFailedRETRY edge-case-simulator once, then ask user
If Gate 2 passes: Update session state to phase 3 and proceed.
  1. 通过Task工具启动
    skill-editor-edge-case-simulator
    并传入细化规范
  2. Agent生成特定于技能的故障模式矩阵，涵盖：
    • YAML解析失败、sync-config.py边缘情况
    • Task工具超时、git脏状态场景
    • Claude Code特定边界条件
  3. 质量阈值：报告存在且字数>100
输出文件：
  • ${SESSION_DIR}/swarm-synthesis.md
    （来自brainstorming-pm，若跳过/降级则不存在）
  • ${SESSION_DIR}/edge-cases.md
    （来自edge-case-simulator）
质量关卡2：分析完成
轨道A（群体分析）轨道B（边缘案例分析）操作
完成完成通过
低于阈值完成通过并记录备注（优雅降级）
超时完成通过并记录备注（无群体分析继续）
任意失败重试edge-case-simulator一次，然后询问用户
如果关卡2通过：更新会话状态至阶段3并继续。

Phase 3: Decision

阶段3：决策

QUICK mode: Orchestrator creates a minimal implementation plan directly from the refined specification. No swarm analysis or adversarial review — just objective, files to modify, validation steps, and rollback plan. If target files include core workflow/agent files, offer upgrade to FULL mode. Proceed to Phase 4.
FULL mode: Full synthesis + adversarial review (below).
QUICK快速模式：编排者直接根据细化规范创建最小化实施计划。无群体分析或对抗性评审——仅包含目标、待修改文件、验证步骤和回滚计划。如果目标文件包含核心工作流/Agent文件，提供升级到FULL完整模式的选项。进入阶段4。
FULL完整模式：完整综合+对抗性评审（如下）。

Part A: Inline Synthesis (orchestrator-owned, FULL mode)

A部分：内综合（编排者专属，仅FULL完整模式）

The orchestrator performs synthesis directly (like brainstorming-pm Stage 3), NOT via a separate agent:
  1. Read swarm synthesis output (
    swarm-synthesis.md
    ) — convergent/divergent insights
  2. Read edge-case report (
    edge-cases.md
    )
  3. Identify consensus and conflicts across both sources
  4. Resolve conflicts or present options to user:
    • Major decisions: MUST ask user via AskUserQuestion (new agents, structure changes)
    • Medium decisions: SHOULD ask user (workflow changes)
    • Minor decisions: Orchestrator decides (examples, docs)
  5. Create detailed implementation plan with:
    • Exact file paths and specific changes
    • Edge case handling strategies
    • Validation steps and rollback plan
Orchestrator-Specific Synthesis (when orchestrator_detected is true):
  • If REQUIRED orchestrator patterns are ABSENT: plan MUST include adding them
  • If RECOMMENDED patterns are ABSENT: plan SHOULD note them as suggestions
  • Reference 
    orchestrator-best-practices.md
    for pattern templates
Output File: 
${SESSION_DIR}/implementation-plan.md
编排者直接执行综合工作（类似brainstorming-pm的第3阶段），而非通过单独Agent：
  1. 读取群体综合输出（
    swarm-synthesis.md
    ）——收敛/发散见解
  2. 读取边缘案例报告（
    edge-cases.md
    ）
  3. 识别两个来源中的共识和冲突
  4. 解决冲突或向用户呈现选项：
    • 重大决策：必须通过AskUserQuestion询问用户（新增Agent、结构变更）
    • 中等决策：应询问用户（工作流变更）
    • 微小决策：编排者自行决定（示例、文档）
  5. 创建详细的实施计划，包含：
    • 确切文件路径和具体变更内容
    • 边缘案例处理策略
    • 验证步骤和回滚计划
编排者专属综合（当orchestrator_detected为true时）：
  • 如果缺少必填编排者模式：计划必须包含添加这些模式的内容
  • 如果缺少推荐编排者模式：计划应将其列为建议项
  • 参考
    orchestrator-best-practices.md
    获取模式模板
输出文件：
${SESSION_DIR}/implementation-plan.md

Part B: Adversarial Review (delegated)

B部分：对抗性评审（委托执行）

Agent: 
skill-editor-adversarial-reviewer
Model: Opus 4.6 (expert review)
Process:
  1. Launch adversarial-reviewer via Task tool with implementation plan
  2. Reviewer reads plan with expert skepticism
  3. Challenges assumptions, identifies uncaught failure modes
  4. Verifies exact file paths and git workflow safety
  5. Checks alignment with original specification
  6. Provides verdict: GO / CONDITIONAL / NO-GO
Output File: 
${SESSION_DIR}/adversarial-review.md
Quality Gate 2: Plan Approval
Check:
  • Implementation plan has exact file paths
  • Git workflow is safe and correct
  • Adversarial reviewer approved (GO or CONDITIONAL with fixes applied)
  • User approves plan
If CONDITIONAL: Fix issues, re-review. If NO-GO: Revise plan, re-submit. If user doesn't approve: Refine plan or return to Phase 1.
If Gate 2 passes: Update session state to phase 4 and proceed.
Agent：
skill-editor-adversarial-reviewer
模型：Opus 4.6（专家评审）
流程：
  1. 通过Task工具启动adversarial-reviewer并传入实施计划
  2. 评审员以专家批判性视角读取计划
  3. 挑战假设、识别未发现的故障模式
  4. 验证确切文件路径和git工作流安全性
  5. 检查与原始规范的一致性
  6. 提供 verdict：通过/有条件通过/不通过
输出文件：
${SESSION_DIR}/adversarial-review.md
质量关卡2：计划批准
检查项：
  • 实施计划包含确切文件路径
  • Git工作流安全且正确
  • 对抗性评审员已批准（通过或有条件通过且已修复问题）
  • 用户批准计划
如果是有条件通过：修复问题，重新评审。 如果是不通过：修订计划，重新提交。 如果用户不批准：细化计划或返回至阶段1。
如果关卡2通过：更新会话状态至阶段4并继续。

Phase 4: Execution (Implement + Validate + Commit)

阶段4：实施（执行+验证+提交）

Objective: Execute approved plan with validation at each step.
Agent: 
skill-editor-executor
Model: Opus 4.6
Process:
目标：执行已批准的计划，每一步都进行验证。
Agent：
skill-editor-executor
模型：Opus 4.6
流程：

Step 1: Pre-Implementation Safety

步骤1：实施前安全检查

  • git status
    — must be clean
  • ./sync-config.py status
    — must be synced
  • pwd
    — must be repo root
  • Stop if any check fails.
  • git status
    — 必须为干净状态
  • ./sync-config.py status
    — 必须已同步
  • pwd
    — 必须在仓库根目录
  • 任何检查失败则停止。

Step 2: Implement Changes

步骤2：实施变更

For each file in implementation plan:
  • Edit: Read first, then Edit with exact string replacement
  • Create: Write new file
  • Delete: Remove file
对于实施计划中的每个文件：
  • 编辑：先读取，然后使用精确字符串替换进行编辑
  • 创建：写入新文件
  • 删除：移除文件

Step 3: Quality Gate 3 - Pre-Sync Validation

步骤3：质量关卡3 - 同步前验证

  • Validate YAML frontmatter for all modified skills
  • Validate JSON for modified agents
  • Dry-run sync: 
    ./sync-config.py push --dry-run
If Gate 3 fails: Fix issues, re-validate, do NOT proceed until pass.
  • 验证所有修改技能的YAML前置元数据
  • 验证修改Agent的JSON格式
  • 同步预演：
    ./sync-config.py push --dry-run
如果关卡3失败：修复问题，重新验证，通过前不得继续。

Step 4: Sync to ~/.claude/

步骤4：同步至~/.claude/

  • ./sync-config.py push
  • ./sync-config.py status
    — verify no divergence
  • ./sync-config.py push
  • ./sync-config.py status
    — 验证无差异

Step 5: Test Skill Invocation

步骤5：测试技能调用

  • Verify skill file exists at 
    $HOME/.claude/skills/$SKILL_NAME/SKILL.md
  • Verify YAML parses
  • Smoke test existing skills (no regressions)
  • 验证技能文件存在于
    $HOME/.claude/skills/$SKILL_NAME/SKILL.md
  • 验证YAML可解析
  • 冒烟测试现有技能（无回归问题）

Step 6: Post-Execution Verification (part of Gate 3)

步骤6：实施后验证（关卡3的一部分）

  • Original requirement met (from refined spec)
  • Edge cases handled (from edge-case report, if FULL mode)
  • sync-config.py push successful
  • Skill invokes without errors
  • No regressions in existing skills
  • Planning journal entry ready
If verification fails: Rollback via 
git reset --hard HEAD
, re-sync, fix, retry.
  • 满足原始需求（来自细化规范）
  • 已处理边缘案例（来自边缘案例报告，仅FULL完整模式）
  • sync-config.py push执行成功
  • 技能调用无错误
  • 现有技能无回归问题
  • 规划日志条目已准备好
如果验证失败：通过
git reset --hard HEAD
回滚，重新同步，修复问题后重试。

Step 7: Update Planning Journal

步骤7：更新规划日志

./sync-config.py plan --title "[Brief description from refined spec]"
./sync-config.py plan --title "[来自细化规范的简短描述]"

Optional: Git Strategy Advisory

可选：Git策略建议

Before committing, MAY invoke 
git-strategy-advisor
via Task tool in post-work mode for scope-adaptive git recommendations. This is advisory only — Step 8 logic takes precedence.
提交前，可在工作流后模式下通过Task工具调用
git-strategy-advisor
获取适配范围的git建议。这仅为建议——步骤8的逻辑优先。

Step 8: Commit Changes

步骤8：提交变更

Stage specific files (NEVER -A or .), commit with HEREDOC multi-line message using conventional commit format (
feat
/
fix
/
docs
) and including 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
, then mark session as completed.
Git Safety Checklist:
  • Specific files staged (not -A or .)
  • Conventional commit format (feat/fix/docs)
  • Descriptive message
  • Co-authored-by line
  • No destructive operations
  • No hook bypasses
暂存特定文件（切勿使用-A或.），使用conventional commit格式（
feat
/
fix
/
docs
）的HEREDOC多行消息提交，包含
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
，然后标记会话为已完成。
Git安全检查清单：
  • 暂存特定文件（非-A或.）
  • 使用conventional commit格式（feat/fix/docs）
  • 描述性提交消息
  • 包含Co-authored-by行
  • 无破坏性操作
  • 无钩子绕过

Step 9: Report Completion

步骤9：报告完成

Generate completion report with:
  • Summary of changes
  • Validation results (Gate 3)
  • Testing results
  • Commit SHA
  • Planning journal entry path
  • Success criteria verification
  • Session completion status
生成完成报告，包含：
  • 变更摘要
  • 验证结果（关卡3）
  • 测试结果
  • 提交SHA
  • 规划日志条目路径
  • 成功标准验证情况
  • 会话完成状态

Escalation Framework

升级框架

Decision thresholds (from CONFIG_MANAGEMENT.md):
决策阈值（来自CONFIG_MANAGEMENT.md）：

Major Decisions → User Approval Required

重大决策 → 需要用户批准

  • Add new agent to workflow
  • Change skill structure specification
  • Modify core workflow phases
Action: Use AskUserQuestion before proceeding
  • 向工作流中添加新Agent
  • 更改技能结构规范
  • 修改核心工作流阶段
操作：继续前使用AskUserQuestion询问用户

Medium Decisions → User Approval Required

中等决策 → 需要用户批准

  • Modify existing skill's core workflow
  • Add new supporting skill
  • Change skill naming convention
Action: Use AskUserQuestion with options
  • 修改现有技能的核心工作流
  • 添加新的支持性技能
  • 更改技能命名约定
操作：使用AskUserQuestion呈现选项询问用户

Minor Decisions → Agent Decides

微小决策 → Agent自行决定

  • Add example to existing skill
  • Fix documentation typo
  • Update reference material
Action: Proceed, notify user
  • 向现有技能添加示例
  • 修复文档拼写错误
  • 更新参考资料
操作：继续执行，通知用户

Error Handling

错误处理

Retry Protocol (Phase 2 Agent Failures)

重试协议（阶段2 Agent失败）

  • edge-case-simulator failure: Wait 30s, retry once automatically, then ask user
  • brainstorming-pm timeout (>15 min): Skip swarm, proceed with edge-case output only
  • brainstorming-pm below quality threshold: Log and proceed without swarm input
  • edge-case-simulator失败：等待30秒，自动重试一次，然后询问用户
  • brainstorming-pm超时（>15分钟）：跳过群体分析，仅使用边缘案例输出继续
  • brainstorming-pm低于质量阈值：记录日志并在无群体输入的情况下继续

Graceful Degradation

优雅降级

  • Swarm timeout or failure: Proceed without swarm analysis (orchestrator creates plan from specification + edge-case report only)
  • Edge-case-simulator timeout (after retry): Ask user to proceed with specification-only plan or abort
  • 群体分析超时或失败：无群体分析继续（编排者根据规范+边缘案例报告创建计划）
  • edge-case-simulator超时（重试后）：询问用户是继续使用仅规范计划还是中止

Rollback Protocol (Phase 4 Failures)

回滚协议（阶段4失败）

  1. Stop immediately
  2. git reset --hard HEAD
    (revert uncommitted changes)
  3. ./sync-config.py push
    (re-sync from repo)
  4. Document failure in planning journal
  5. Report to user with options: retry, skip, or abort
  1. 立即停止
  2. git reset --hard HEAD
    （撤销未提交的变更）
  3. ./sync-config.py push
    （从仓库重新同步）
  4. 在规划日志中记录失败情况
  5. 向用户报告并提供选项：重试、跳过或中止

Interrupt Handling (User Cancels)

中断处理（用户取消）

  1. Check git status
  2. Rollback uncommitted changes: 
    git reset --hard HEAD
  3. Re-sync: 
    ./sync-config.py push
  4. Session state preserved in 
    ${SESSION_DIR}/
    for potential resume
  5. Document in planning journal: "Cancelled by user"
  1. 检查git状态
  2. 回滚未提交的变更：
    git reset --hard HEAD
  3. 重新同步：
    ./sync-config.py push
  4. 会话状态保存在
    ${SESSION_DIR}/
    中以便后续恢复
  5. 在规划日志中记录："用户已取消"

Integration with Existing Tools

与现有工具的集成

CONFIG_MANAGEMENT.md

CONFIG_MANAGEMENT.md

This workflow extends the 7-step CONFIG_MANAGEMENT.md process:
  • Step 1 (Safety Check): Pre-workflow checks
  • Step 2 (Planning Entry): Phase 4, Step 7
  • Step 3 (Implement): Phase 4, Step 2
  • Step 4 (Quality Analysis): Phases 2-3, Quality Gates
  • Step 5 (Preview/Sync): Phase 4, Steps 3-4
  • Step 6 (Test): Phase 4, Step 5
  • Step 7 (Commit): Phase 4, Step 8
此工作流扩展了CONFIG_MANAGEMENT.md的7步流程：
  • 步骤1（安全检查）：预工作流检查
  • 步骤2（规划条目）：阶段4，步骤7
  • 步骤3（实施）：阶段4，步骤2
  • 步骤4（质量分析）：阶段2-3，质量关卡
  • 步骤5（预览/同步）：阶段4，步骤3-4
  • 步骤6（测试）：阶段4，步骤5
  • 步骤7（提交）：阶段4，步骤8

sync-config.py

sync-config.py

Executor agent uses sync-config.py:
  • ./sync-config.py status
    (pre-flight check)
  • ./sync-config.py push --dry-run
    (validation)
  • ./sync-config.py push
    (apply changes)
  • ./sync-config.py plan
    (create planning entry)
Executor Agent使用sync-config.py执行以下操作：
  • ./sync-config.py status
    （预执行检查）
  • ./sync-config.py push --dry-run
    （验证）
  • ./sync-config.py push
    （应用变更）
  • ./sync-config.py plan
    （创建规划条目）

Planning Journal

规划日志

Planning entry created in Phase 4, Step 7:
  • Title: Brief description from refined spec
  • Objective: From refined specification
  • Changes: Files modified
  • Testing: Validation and test results
  • Outcome: Success/Partial/Failed
规划条目在阶段4，步骤7创建：
  • 标题：来自细化规范的简短描述
  • 目标：来自细化规范
  • 变更：修改的文件
  • 测试：验证和测试结果
  • 结果：成功/部分成功/失败

Quality Gates Summary

质量关卡摘要

GatePhaseOwnerCriteriaFailure Action
1: Specification ApprovalPhase 1request-refinerSpec approved by userReturn to refinement
2: Plan ApprovalPhase 3adversarial-reviewer + userAdversarial GO + user approves planRevise plan
3: Execution VerificationPhase 4executorYAML validates, sync succeeds, skill invokes, no regressionsRollback
关卡阶段负责人标准失败操作
1: 规范批准阶段1request-refiner用户批准规范返回至需求细化
2: 计划批准阶段3adversarial-reviewer + 用户对抗性评审通过 + 用户批准计划修订计划
3: 实施验证阶段4executorYAML验证通过、同步成功、技能调用正常、无回归问题回滚

Examples

示例

Example 1: Add Parallel Execution to Researcher

示例1：为Researcher添加并行执行功能

User Request:
/skill-editor "Add parallel web search to researcher skill"
Phase 1 Output:
markdown
Objective: Modify researcher skill to execute 3 WebSearch calls in parallel

Scope:
- IN: researcher/SKILL.md Phase 2 workflow
- OUT: No changes to agents or other phases

Success Criteria:
- 3 WebSearch calls execute simultaneously
- Results synthesized correctly
- No regressions
Phase 2 Findings:
  • Swarm: Consensus on Task tool for parallel calls, alternative approaches explored
  • Edge cases: Handle timeout, network failure, partial results
Phase 3 Plan:
markdown
Edit: claude-config/skills/researcher/SKILL.md
Lines 45-60: Replace sequential WebSearch with parallel

Implementation:
[3 Task tool calls in single message]
Phase 4 Result:
YAML validates, sync succeeds, skill invokes correctly
Commit: feat(researcher): Add parallel web search
用户请求：
/skill-editor "为researcher技能添加并行网页搜索功能"
阶段1输出：
markdown
目标：修改researcher技能以并行执行3次WebSearch调用

范围：
- 包含：researcher/SKILL.md阶段2工作流
- 排除：不修改Agent或其他阶段

成功标准：
- 3次WebSearch调用同时执行
- 结果正确综合
- 无回归问题
阶段2发现：
  • 群体分析：共识是使用Task工具实现并行调用，已探索替代方案
  • 边缘案例：处理超时、网络故障、部分结果
阶段3计划：
markdown
编辑：claude-config/skills/researcher/SKILL.md
第45-60行：将顺序WebSearch替换为并行执行

实施：
[单条消息中包含3个Task工具调用]
阶段4结果：
YAML验证通过、同步成功、技能调用正常
提交：feat(researcher): 添加并行网页搜索功能

Example 2: Create New Skill

示例2：创建新技能

User Request:
/skill-editor "Create a new skill for API documentation"
Process:
  • Phase 1: Refine requirements (which APIs? format? tools?)
  • Phase 2: Analyze (best practices for doc skills, community patterns, edge cases)
  • Phase 3: Plan (file structure, workflow steps, examples)
  • Phase 4: Create files, validate, sync, test, commit
用户请求：
/skill-editor "创建一个用于API文档的新技能"
流程：
  • 阶段1：细化需求（哪些API？格式？工具？）
  • 阶段2：分析（文档技能最佳实践、社区模式、边缘案例）
  • 阶段3：计划（文件结构、工作流步骤、示例）
  • 阶段4：创建文件、验证、同步、测试、提交

Timeout Configuration

超时配置

PhaseComponentTimeoutExceeded Action
1request-refiner30 minEscalate to user
2brainstorming-pm (swarm)15 minSkip swarm, proceed with edge-case only
2edge-case-simulator10 minAuto-retry once, then user decision
3adversarial-reviewer30 minEscalate to user
4executor60 minEscalate to user
Globalentire workflow3 hoursSafety ceiling, force escalate
阶段组件超时时间超时操作
1request-refiner30分钟升级至用户处理
2brainstorming-pm（群体分析）15分钟跳过群体分析，仅使用边缘案例输出继续
2edge-case-simulator10分钟自动重试一次，然后由用户决策
3adversarial-reviewer30分钟升级至用户处理
4executor60分钟升级至用户处理
全局整个工作流3小时安全上限，强制升级至用户处理

Notes

说明

  • Hybrid swarm + specialist model: brainstorming-pm provides multi-perspective analysis, edge-case-simulator provides domain-specific failure modes
  • All agents use Opus 4.6: Maximum quality for all workflow phases
  • 3 quality gates: Specification Approval, Plan Approval, Execution Verification
  • Rollback on failure: Safe to abort at any point
  • Planning journal provides traceability: Full documentation of changes
  • Integration tested: Works with sync-config.py and existing workflows
  • 混合群体+专业模型：brainstorming-pm提供多视角分析，edge-case-simulator提供特定领域故障模式分析
  • 所有Agent使用Opus 4.6：所有工作流阶段均使用最高质量模型
  • 3个质量关卡：规范批准、计划批准、实施验证
  • 失败时回滚：任何阶段都可安全中止
  • 规划日志提供可追溯性：变更的完整文档记录
  • 经过集成测试：可与sync-config.py和现有工作流配合使用

References

参考资料

See 
skill-editor/references/
for:
  • swarm-challenge-templates.md
    : Challenge template for brainstorming-pm swarm delegation
  • session-management.sh
    : Git safety checks, session creation/resume, cleanup commands
  • anthropic-guidelines-summary.md
    : Anthropic best practices
  • skill-structure-specification.md
    : Skill format and validation
  • quality-gates.md
    : Detailed quality gate checklists
  • orchestrator-checklist.md
    : Orchestrator pattern evaluation checklist
  • orchestrator-best-practices.md
    : Orchestrator pattern templates
详见
skill-editor/references/
目录下的文件：
  • swarm-challenge-templates.md
    ：用于brainstorming-pm群体委托的挑战模板
  • session-management.sh
    ：Git安全检查、会话创建/恢复、清理命令
  • anthropic-guidelines-summary.md
    ：Anthropic最佳实践
  • skill-structure-specification.md
    ：技能格式和验证规范
  • quality-gates.md
    ：详细质量关卡检查清单
  • orchestrator-checklist.md
    ：编排者模式评估清单
  • orchestrator-best-practices.md
    ：编排者模式模板

Success Criteria

成功标准

Skill-editor workflow succeeds when:
  • User's original request is fulfilled
  • All quality gates pass
  • Changes are synced to 
    ~/.claude/
  • Skill invokes without errors
  • No regressions in existing skills
  • Planning journal documents changes
  • Changes committed to git
  • User confirms satisfaction
Skill-editor工作流成功的条件：
  • 满足用户原始请求
  • 所有质量关卡通过
  • 变更已同步至
    ~/.claude/
  • 技能调用无错误
  • 现有技能无回归问题
  • 规划日志记录了变更
  • 变更已提交至git
  • 用户确认满意",