Skills Workflows

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

Steps

• Load the outfitter:skills-dev skill for base skill authoring

• Apply workflow patterns from this skill

• 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