skills-workflows

Original：🇺🇸 English
Translated

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.

18installs
Sourceoutfitter-dev/agents
Added on

NPX Install

npx skill4agent add outfitter-dev/agents skills-workflows

Tags

Translated version includes tags in frontmatter
skill-workflowsartifact-state-handoffclaude-skillsworkflow-pipelinespreprocessing-commands

SKILL.md Content

View Translation Comparison →

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

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

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

ContextUse WhenExample
inherit
(default)		Skill needs conversation historyImplementation skills
fork
Clean-room analysis, no chat noiseResearch, 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 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.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 — 10 complete workflow templates
  • state-handoff.md — Artifact patterns and examples
  • preprocessing.md — 
    !command
    syntax and patterns
</references>