skills-workflows

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:

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

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

• workflow-templates.md — 10 complete workflow templates
• state-handoff.md — Artifact patterns and examples
• preprocessing.md — !command syntax and patterns