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:

.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:

/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:

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

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

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

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

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

Read-only, returns summary.

Planning Skills → Fork with Plan

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

Deliberative, returns structured plan.

Implementation Skills → Inherit

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

Needs full context, makes changes.

Side-Effect Skills → User-Invoked Only

# 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

---
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 — 10 complete workflow templates
• state-handoff.md — Artifact patterns and examples
• preprocessing.md — !command syntax and patterns

</references>