Back to Details

skills-workflows

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skills Workflows

Skill工作流

Design skill systems that chain together with artifact-based state passing.
设计通过基于工件的状态传递来串联的Skill系统。

Steps

步骤

  1. Load the 
    outfitter:skills-dev
    skill for base skill authoring
  2. Apply workflow patterns from this skill
  3. If Claude-specific features needed, load the 
    outfitter:claude-skills
    skill
<when_to_use>
  • Building multi-skill pipelines (triage → plan → implement → review)
  • Designing state handoff between workflow steps
  • Creating deterministic preprocessing with 
    !command
    syntax
  • Setting up shared conventions (artifacts/, context.md)
  • Choosing fork vs inherit for workflow isolation
NOT for: single standalone skills, one-off commands, simple patterns
</when_to_use>
  1. 加载
    outfitter:skills-dev
    Skill以进行基础Skill开发
  2. 应用本Skill中的工作流模式
  3. 如果需要Claude特定功能，加载
    outfitter:claude-skills
    Skill
<when_to_use>
  • 构建多Skill流水线（分类→规划→实现→评审）
  • 设计工作流步骤间的状态传递
  • 使用
    !command
    语法创建确定性预处理
  • 建立共享约定（artifacts/、context.md）
  • 为工作流隔离选择fork或inherit模式
不适用于：单个独立Skill、一次性命令、简单模式
</when_to_use>

Shared Conventions

共享约定

Every workflow system benefits from standard file locations:
text
.claude/
  skills/
    _shared/
      context.md       # Living summary of current task + decisions
      constraints.md   # Non-negotiables (security, style, perf budgets)
    triage/SKILL.md
    plan/SKILL.md
    implement/SKILL.md
    review/SKILL.md
artifacts/
  triage.md           # Output of /triage
  plan.md             # Output of /plan
  test-report.md      # Output of /test
  review-notes.md     # Output of /review
scripts/
  run-tests.sh
  security-check.sh
FilePurposeUpdated By
context.md
Task state, decisions made, current focusEach skill as work progresses
constraints.md
Project invariants, security rules, style guideSetup once, rarely changed
artifacts/{step}.md
Step outputs, consumed by next stepThe skill that completes that step
每个工作流系统都能从标准文件位置中获益：
text
.claude/
  skills/
    _shared/
      context.md       # 当前任务+决策的动态摘要
      constraints.md   # 不可协商项（安全、风格、性能预算）
    triage/SKILL.md
    plan/SKILL.md
    implement/SKILL.md
    review/SKILL.md
artifacts/
  triage.md           # /triage的输出
  plan.md             # /plan的输出
  test-report.md      # /test的输出
  review-notes.md     # /review的输出
scripts/
  run-tests.sh
  security-check.sh
文件用途更新者
context.md
任务状态、已做决策、当前重点每个Skill在工作推进时更新
constraints.md
项目不变量、安全规则、风格指南仅设置一次，极少更改
artifacts/{step}.md
步骤输出，供下一步使用完成该步骤的Skill

State Passing Discipline

状态传递规范

Each skill reads from previous artifacts and writes its own:
text
/triage → writes artifacts/triage.md
    ↓
/plan reads artifacts/triage.md → writes artifacts/plan.md
    ↓
/implement reads artifacts/plan.md → updates context.md
    ↓
/test reads artifacts/plan.md → writes artifacts/test-report.md
    ↓
/review reads all → writes artifacts/review-notes.md
每个Skill读取之前的工件并写入自己的工件：
text
/triage → 写入artifacts/triage.md
    ↓
/plan读取artifacts/triage.md → 写入artifacts/plan.md
    ↓
/implement读取artifacts/plan.md → 更新context.md
    ↓
/test读取artifacts/plan.md → 写入artifacts/test-report.md
    ↓
/review读取所有工件 → 写入artifacts/review-notes.md

Artifact Format

工件格式

Each artifact should be self-contained and parseable:
markdown
undefined
每个工件应具备自包含性和可解析性：
markdown
undefined

Triage: {task description}

分类：{任务描述}

Problem Statement

问题陈述

{clear definition}
{清晰定义}

Scope

范围

  • Files: {list}
  • Modules: {list}
  • 文件：{列表}
  • 模块：{列表}

Acceptance Criteria

验收标准

  • {criterion 1}
  • {criterion 2}
  • {标准1}
  • {标准2}

Risks

风险

  • {risk 1}
  • {risk 2}
Generated by /triage at {timestamp}
undefined
  • {风险1}
  • {风险2}
由/triage在{时间戳}生成
undefined

Preprocessing with 
!command

使用
!command
进行预处理

The 
!command
syntax runs shell commands before prompt reaches Claude. Claude sees rendered output, not the command. IMPORTANT: The "!" must precede the opening backtick for a command.
text
---
name: pr-summary
context: fork
agent: Explore
allowed-tools: Bash(gh:*)
---
!command
语法会在提示词到达Claude之前执行Shell命令。Claude只会看到渲染后的输出，而非命令本身。重要提示：必须在反引号前添加“!”才能启用预处理。
text
---
name: pr-summary
context: fork
agent: Explore
allowed-tools: Bash(gh:*)
---

Pull Request Context

拉取请求上下文

<!-- NOTE: The "!" must be placed in front of backticks for preprocessing to work. -->
  • Diff: 
    gh pr diff
  • Comments: 
    gh pr view --comments
  • Status: 
    gh pr status
Summarize changes and highlight risks.
undefined
<!-- 注意：必须在反引号前添加“!”才能使预处理生效。 -->
  • 差异：
    gh pr diff
  • 评论：
    gh pr view --comments
  • 状态：
    gh pr status
总结变更并突出风险。
undefined

When to Preprocess

何时使用预处理

Use CasePreprocessingWhy
Git status
git status
Deterministic snapshot
PR context
gh pr diff
Avoid tool call overhead
Schema info
psql -c "\\d table"
Fresh at invocation
Env info
echo $NODE_ENV
Runtime context
使用场景预处理命令原因
Git状态
git status
获取确定性快照
PR上下文
gh pr diff
避免工具调用开销
架构信息
psql -c "\\d table"
调用时获取最新数据
环境信息
echo $NODE_ENV
获取运行时上下文

When NOT to Preprocess

何时不使用预处理

  • Dynamic queries based on conversation (use tools instead)
  • Large outputs that bloat context
  • Commands with side effects (never preprocess mutations)
  • 基于对话的动态查询（改用工具）
  • 会导致上下文膨胀的大输出
  • 有副作用的命令（绝不对突变操作进行预处理）

Fork vs Inherit

Fork模式 vs Inherit模式

ContextUse WhenExample
inherit
(default)		Skill needs conversation historyImplementation skills
fork
Clean-room analysis, no chat noiseResearch, review, triage
上下文使用场景示例
inherit
（默认）		Skill需要对话历史实现类Skill
fork
纯净环境分析，无聊天噪音研究、评审、分类类Skill

Fork Pattern

Fork模式示例

yaml
---
name: triage
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---
Fork benefits:
  • Prevents context pollution from prior conversation
  • Enables parallel execution
  • Returns only the focused output
yaml
---
name: triage
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---
Fork模式优势：
  • 避免对话历史导致的上下文污染
  • 支持并行执行
  • 仅返回聚焦的输出

Inherit Pattern

Inherit模式示例

yaml
---
name: implement
yaml
---
name: implement

context: inherit is default

context: inherit为默认设置


Inherit when:
- Skill needs prior decisions/context
- Building on previous work
- Conversation history is valuable

在以下场景使用Inherit：
- Skill需要之前的决策/上下文
- 基于之前的工作进行构建
- 对话历史具有价值

Workflow Isolation Patterns

工作流隔离模式

Analysis Skills → Fork

分析类Skill → 使用Fork

yaml
undefined
yaml
undefined

triage, review, research skills

分类、评审、研究类Skill

context: fork agent: Explore allowed-tools: Read, Grep, Glob

Read-only, returns summary.
context: fork agent: Explore allowed-tools: Read, Grep, Glob

只读权限，返回摘要。

Planning Skills → Fork with Plan

规划类Skill → 使用Fork并生成计划

yaml
undefined
yaml
undefined

plan, spec, architecture skills

规划、规格、架构类Skill

context: fork agent: Plan allowed-tools: Read, Grep, Glob

Deliberative, returns structured plan.
context: fork agent: Plan allowed-tools: Read, Grep, Glob

审慎决策，返回结构化计划。

Implementation Skills → Inherit

实现类Skill → 使用Inherit

yaml
undefined
yaml
undefined

implement, fix, refactor skills

实现、修复、重构类Skill

No context/agent fields (inherit default)

无需指定context/agent字段（继承默认设置）


Needs full context, makes changes.

需要完整上下文，进行变更操作。

Side-Effect Skills → User-Invoked Only

有副作用的Skill → 仅允许用户调用

yaml
undefined
yaml
undefined

deploy, ship, commit skills

部署、发布、提交类Skill

disable-model-invocation: true

Never auto-triggered, explicit human decision.
disable-model-invocation: true

绝不自动触发，需明确的人工决策。

Failure Mode Mitigations

故障模式缓解方案

Failure ModeMitigation
Context blowupKeep analysis in 
context: fork
; store results in artifacts
State lost between stepsAll state in files, not conversation
Unsafe auto-execution
disable-model-invocation: true
on side-effect skills
Tool permission creepExplicit 
allowed-tools
per skill, minimal set
Workflow step skippedArtifacts serve as gates (next step reads previous)
故障模式缓解方案
上下文膨胀分析类Skill使用
context: fork
；将结果存储在工件中
步骤间状态丢失所有状态存储在文件中，而非对话中
不安全的自动执行对有副作用的Skill设置
disable-model-invocation: true
工具权限蔓延为每个Skill明确设置
allowed-tools
，仅保留必要权限
工作流步骤被跳过工件作为关卡（下一步必须读取上一步的工件）

SKILL.md Template for Workflow Steps

工作流步骤的SKILL.md模板

markdown
---
name: {step-name}
description: {what this step does}. Use when {trigger conditions}.
context: fork           # or omit for inherit
agent: Explore          # if forked
allowed-tools: Read, Grep, Glob
disable-model-invocation: true  # if side-effectful
---
markdown
---
name: {步骤名称}
description: {本步骤的作用}。适用于{触发条件}场景。
context: fork           # 或省略以使用inherit
agent: Explore          # 如果使用fork模式
allowed-tools: Read, Grep, Glob
disable-model-invocation: true  # 如果有副作用
---

Purpose

目标

  • Why this step exists
  • What "done" looks like
  • 本步骤存在的原因
  • “完成”的判定标准

Inputs

输入

  • Read: artifacts/{previous-step}.md
  • Read: .claude/skills/_shared/constraints.md
  • $ARGUMENTS: {expected input}
  • 读取：artifacts/{上一步骤}.md
  • 读取：.claude/skills/_shared/constraints.md
  • $ARGUMENTS: {预期输入}

Process

流程

  1. {step 1}
  2. {step 2}
  3. {step 3}
  1. {步骤1}
  2. {步骤2}
  3. {步骤3}

Outputs

输出

  • Write: artifacts/{this-step}.md
  • Update: .claude/skills/_shared/context.md with decisions
  • 写入：artifacts/{本步骤}.md
  • 更新：.claude/skills/_shared/context.md，记录决策

Constraints

约束

  • {constraint 1}
  • {constraint 2}

<rules>

ALWAYS:
- Use artifacts/ for state passing between skills
- Keep context.md updated with decisions
- Fork analysis skills to prevent context pollution
- Use `disable-model-invocation: true` for side-effect skills
- Minimize `allowed-tools` to required set

NEVER:
- Store state in conversation alone (lost on compaction)
- Auto-invoke deploy/commit/ship skills
- Mix analysis and mutation in one forked skill
- Skip artifact gates between workflow steps

</rules>

<references>

- [workflow-templates.md](references/workflow-templates.md) — 10 complete workflow templates
- [state-handoff.md](references/state-handoff.md) — Artifact patterns and examples
- [preprocessing.md](references/preprocessing.md) — `!command` syntax and patterns

</references>
  • {约束1}
  • {约束2}

<rules>

必须遵守：
- 使用artifacts/在Skill间传递状态
- 持续更新context.md以记录决策
- 分析类Skill使用fork模式避免上下文污染
- 对有副作用的Skill设置`disable-model-invocation: true`
- 将`allowed-tools`最小化到必要集合

严禁：
- 仅在对话中存储状态（压缩时会丢失）
- 自动调用部署/提交/发布类Skill
- 在单个fork模式Skill中混合分析和突变操作
- 跳过工作流步骤间的工件关卡

</rules>

<references>

- [workflow-templates.md](references/workflow-templates.md) — 10个完整的工作流模板
- [state-handoff.md](references/state-handoff.md) — 工件模式及示例
- [preprocessing.md](references/preprocessing.md) — `!command`语法及模式

</references>