6.9 KiB

Raw Blame History

Steps Pattern

Composable building blocks for skill workflows. Use when skills depend on other skills or have clear sequential stages.

Basic Structure

# Skill Name

## Steps

1. Load the `plugin:prerequisite-skill` skill
2. { main action }
3. { next action }

Place ## Steps immediately after the H1 title, before any other content.

Syntax

Loading Skills

1. Load the `outfitter:skills-dev` skill

Always use the full plugin:skill-name format. Never link to SKILL.md files.

Conditional Steps

3. If working with TypeScript, load the `outfitter:typescript-dev` skill
4. If tests fail, load the `outfitter:debugging` skill

Conditions should be brief and contextual.

Action Steps

2. Analyze the codebase structure
5. Generate the implementation plan

Use imperative voice, drop articles, keep brief.

Delegated Skills (Agent-Handled)

Skills with context: fork + agent delegate work to agents rather than loading instructions into the current context. Use "delegate by loading" language:

3. Delegate by loading the `outfitter:security-audit` skill for vulnerability analysis
4. Delegate by loading the `outfitter:codebase-recon` skill for deep analysis

Key difference:

Load the skill → instructions enter current context
Delegate by loading the skill → agent runs in isolated context, returns results

Delegated skills are defined with:

---
name: security-audit
context: fork
agent: outfitter:reviewer
model: sonnet
---

When referenced in Steps, make the delegation explicit so readers understand work happens in a subagent.

Branching Workflows

## Steps

1. Load the `outfitter:codebase-recon` skill
2. Investigate the problem area
3. Based on findings:
   - If pattern issue → load `outfitter:patterns` skill
   - If root cause needed → load `outfitter:find-root-causes` skill
   - If ready to report → load `outfitter:report-findings` skill

Plan Mode and User Questions

Use Plan mode and AskUserQuestion for workflows that need user input or have decision points:

## Steps

1. Delegate by loading the `outfitter:claude-plugin-audit` skill for analysis
2. Apply auto-fixable issues
3. Enter Plan mode
4. Present remaining issues with AskUserQuestion

Why Plan mode? Claude thinks more carefully and presents options sequentially. Good for:

Transitioning from automated to manual work
Complex decisions requiring user input
Presenting multiple options with tradeoffs

Brainstorming with Plan Agent

For complex problems benefiting from multiple perspectives:

## Steps

1. Gather initial context
2. Brainstorm with Plan agent for approaches
3. Present options with AskUserQuestion
4. Implement chosen approach

The Plan agent (subagent_type: Plan) explores the problem space independently, returning with considered options. Gets more than one "mind" on the problem before committing to an approach.

Examples

Extension Skill (claude-skills)

# Claude Code Skills

## Steps

1. Load the `outfitter:skills-dev` skill
2. Apply Claude Code-specific extensions from this skill

Simple two-step: load base, extend with specifics.

Research Workflow

# Technical Research

## Steps

1. Load the `outfitter:codebase-recon` skill
2. Gather evidence from codebase
3. If external research needed, use WebSearch/WebFetch
4. Load the `outfitter:report-findings` skill
5. Synthesize into structured report

Linear workflow with conditional mid-step.

Debugging Workflow

# Debugging

## Steps

1. Load the `outfitter:find-root-causes` skill
2. Investigate with systematic diagnosis
3. If code-level issue, apply fix
4. If architectural issue, load the `outfitter:architecture` skill
5. Validate fix resolves the issue

Branching based on diagnosis outcome.

TDD Workflow

# Test-Driven Development

## Steps

1. Write failing test (Red)
2. Implement minimal code to pass (Green)
3. Load the `outfitter:simplify` skill
4. Refactor while keeping tests green
5. Repeat from step 1 for next requirement

Cyclical workflow with embedded skill.

Security Review with Delegated Skill

# Pre-Merge Security Check

## Steps

1. Gather changed files from PR
2. Delegate by loading the `outfitter:security-audit` skill for vulnerability scan
3. Review findings and severity levels
4. If critical issues, block merge with explanation
5. If clean, approve with security sign-off

The security-audit skill has context: fork and agent: outfitter:reviewer, so step 2 delegates to a subagent. Results return to main context for steps 3-5.

Guidelines

Keep Steps Brief

Each step should be one line. If a step needs explanation, the detail belongs in the skill body, not the steps.

# Good
2. Analyze authentication patterns

# Bad
2. Analyze authentication patterns including OAuth flows, JWT handling,
   session management, and credential storage

3-6 Steps Ideal

Fewer than 3: probably doesn't need Steps section
More than 6: consider splitting into stages or separate skills

Steps vs Workflow Tag

Use `## Steps`	Use `<workflow>` tag
Dependencies on other skills	Self-contained process
High-level orchestration	Detailed methodology
Composable building blocks	Single-skill workflow

Can combine both: Steps for orchestration, <workflow> for detail within a step.

Steps vs Stages

Steps are for the top-level flow. Stages are for detailed breakdown within the skill body.

# Skill Name

## Steps

1. Load prerequisite skill
2. Execute Stage 1-3 below
3. Load synthesis skill

## Stage 1: Discovery
{ detailed content }

## Stage 2: Analysis
{ detailed content }

## Stage 3: Output
{ detailed content }

Anti-Patterns

Linking to SKILL.md

# Wrong
1. See [skills-dev](../skills-dev/SKILL.md) for base patterns

# Right
1. Load the `outfitter:skills-dev` skill

Verbose Steps

# Wrong
1. First, you should load the skills-dev skill which provides the base
   Agent Skills specification that this skill extends

# Right
1. Load the `outfitter:skills-dev` skill

Steps That Are Just Headers

# Wrong - these are stages, not steps
## Steps
1. Discovery
2. Analysis
3. Synthesis

# Right - actionable steps
## Steps
1. Load the `outfitter:codebase-recon` skill
2. Investigate problem area
3. Load the `outfitter:report-findings` skill

Too Many Steps

# Wrong - this is a detailed workflow, not steps
## Steps
1. Read the error message
2. Check the stack trace
3. Find the failing line
4. Read surrounding context
5. Form hypothesis
6. Add logging
7. Reproduce issue
8. Verify hypothesis
9. Implement fix
10. Run tests

# Right - high-level steps, detail in body
## Steps
1. Load the `outfitter:find-root-causes` skill
2. Diagnose with systematic investigation
3. Implement and validate fix

6.9 KiB Raw Blame History