---
name: skills-workflows
description: Design multi-skill workflow systems with artifact-based state handoff. Use when building skill pipelines, sequenced workflows, or when "workflow system", "skill pipeline", "state handoff", or "artifacts" are mentioned.
metadata:
  version: "1.0.0"
  related-skills:
    - skills-dev
    - claude-skills
    - codify
allowed-tools: Read Write Edit Grep Glob Bash TaskCreate TaskUpdate TaskList TaskGet AskUserQuestion
---

# Skills Workflows

Design skill systems that chain together with artifact-based state passing.

## 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>

## 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
```

| File | Purpose | Updated By |
|------|---------|------------|
| `context.md` | Task state, decisions made, current focus | Each skill as work progresses |
| `constraints.md` | Project invariants, security rules, style guide | Setup once, rarely changed |
| `artifacts/{step}.md` | Step outputs, consumed by next step | The skill that completes that step |

## 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
```

### Artifact Format

Each artifact should be self-contained and parseable:

```markdown
# Triage: {task description}

## Problem Statement
{clear definition}

## Scope
- Files: {list}
- Modules: {list}

## Acceptance Criteria
- [ ] {criterion 1}
- [ ] {criterion 2}

## Risks
- {risk 1}
- {risk 2}

---
Generated by /triage at {timestamp}
```

## Preprocessing with `!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:*)
---

## 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.
```

### When to Preprocess

| Use Case | Preprocessing | Why |
|----------|---------------|-----|
| 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 |

### 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

| Context | Use When | Example |
|---------|----------|---------|
| `inherit` (default) | Skill needs conversation history | Implementation skills |
| `fork` | Clean-room analysis, no chat noise | Research, review, triage |

### Fork Pattern

```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

### Inherit Pattern

```yaml
---
name: implement
# context: inherit is default
---
```

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

## Workflow Isolation Patterns

### Analysis Skills → Fork

```yaml
# triage, review, research skills
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
```

Read-only, returns summary.

### Planning Skills → Fork with Plan

```yaml
# plan, spec, architecture skills
context: fork
agent: Plan
allowed-tools: Read, Grep, Glob
```

Deliberative, returns structured plan.

### Implementation Skills → Inherit

```yaml
# implement, fix, refactor skills
# No context/agent fields (inherit default)
```

Needs full context, makes changes.

### Side-Effect Skills → User-Invoked Only

```yaml
# deploy, ship, commit skills
disable-model-invocation: true
```

Never auto-triggered, explicit human decision.

## Failure Mode Mitigations

| Failure Mode | Mitigation |
|--------------|------------|
| Context blowup | Keep analysis in `context: fork`; store results in artifacts |
| State lost between steps | All state in files, not conversation |
| Unsafe auto-execution | `disable-model-invocation: true` on side-effect skills |
| Tool permission creep | Explicit `allowed-tools` per skill, minimal set |
| Workflow step skipped | Artifacts serve as gates (next step reads previous) |

## SKILL.md Template for Workflow Steps

```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
---

# Purpose

- Why this step exists
- What "done" looks like

# Inputs

- Read: artifacts/{previous-step}.md
- Read: .claude/skills/_shared/constraints.md
- $ARGUMENTS: {expected input}

# Process

1. {step 1}
2. {step 2}
3. {step 3}

# Outputs

- Write: artifacts/{this-step}.md
- Update: .claude/skills/_shared/context.md with decisions

# 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>