Creating Multi-Step Workflows with Claude Skills: A Practical Guide

Multi-step workflows in Claude skills are defined in the SKILL.md front-matter and body, using hierarchical step sequences that reference executable scripts in the scripts/ directory and load contextual documentation from references/ on demand.

The awesome-claude-skills repository provides a structured framework for building complex automation chains. A skill is treated as a self-contained package that tells Claude when to activate, what resources to use, and how to carry out tasks. Creating multi-step workflows involves structuring your SKILL.md with procedural logic while offloading deterministic actions to scripts, enabling sophisticated automation that remains maintainable and token-efficient.

Anatomy of a Multi-Step Skill Package

According to the source code in skill-creator/SKILL.md, a workflow-ready skill consists of four core components:

Component	Purpose	Content Type
SKILL.md	Metadata + high-level procedural guide with workflow definitions	Markdown with YAML front-matter
scripts/	Deterministic, executable code for concrete actions	Python, Bash, or other executable scripts
references/	Large documentation loaded on-demand (API specs, schemas)	Markdown technical documents
assets/	Static files for final output generation	Templates, images, fonts

When Claude activates a skill, it first processes the SKILL.md metadata and workflow section, then progressively loads scripts and references as specific steps require them.

Structuring Workflows in SKILL.md

Multi-step logic lives primarily in the SKILL.md file. As documented in skill-creator/SKILL.md (lines 20-22), the repository supports "Specialized workflows – Multi-step procedures" through hierarchical headings and enumerated steps.

Each workflow step can:

• Describe the intent – A concise sentence Claude uses to decide the next action
• Reference a script – Point to files in scripts/ for deterministic processing
• Load a reference – Pull from references/ when extensive context is needed

A typical workflow structure follows this pattern:

---
name: data-processor
description: Processes raw data through validation and transformation.
---

## Workflow

1. **Validate Input** – Claude checks file format using `scripts/validate.py`.
2. **Extract Data** – Claude runs `scripts/extract.py` to parse content.
3. **Transform** – Claude loads `references/transform_rules.md` and applies `scripts/transform.py`.
4. **Generate Report** – Claude uses `scripts/generate_report.py` with templates from `assets/`.

Progressive Disclosure for Token Efficiency

The architecture implements progressive disclosure to manage context windows efficiently. As noted in skill-creator/SKILL.md (lines 77-84), Claude first sees only the front-matter, then the body of SKILL.md, and finally loads scripts or references on demand.

This approach:

• Keeps the initial token budget minimal by deferring large reference documents until needed
• Allows workflows to branch conditionally based on intermediate results
• Maintains clarity by separating high-level logic from implementation details

Implementing Workflow Steps with Scripts

Scripts in the scripts/ directory handle deterministic, executable actions. Consider this example from an image enhancement workflow that adjusts brightness as Step 2:

#!/usr/bin/env python3

# scripts/adjust_brightness.py

import sys
from PIL import Image, ImageEnhance

def adjust_brightness(image_path: str, factor: float, out_path: str):
    img = Image.open(image_path)
    enhancer = ImageEnhance.Brightness(img)
    img_enhanced = enhancer.enhance(factor)
    img_enhanced.save(out_path)
    print(f"Brightness adjusted by {factor}; saved to {out_path}")

if __name__ == "__main__":
    if len(sys.argv) != 4:
        print("Usage: adjust_brightness.py <input> <factor> <output>")
        sys.exit(1)
    adjust_brightness(sys.argv[1], float(sys.argv[2]), sys.argv[3])

Claude invokes this script when the workflow reaches the brightness adjustment step, passing arguments extracted from user input.

Bootstrapping New Skills

To standardize workflow creation, the repository includes skill-creator/scripts/init_skill.py (lines 14-30). This utility bootstraps a new skill with the proper folder layout and a starter SKILL.md template.

The script enforces naming conventions and creates the three resource directories automatically:

python skill-creator/scripts/init_skill.py my-new-workflow

This generates the skeleton structure with pre-defined sections for metadata, workflow steps, and resource declarations.

Validation and Distribution

Before distribution, skills must pass validation. The skill-creator/scripts/package_skill.py utility (lines 87-95) validates the structure—including YAML front-matter syntax, required directories, and script executability—before zipping the skill for distribution.

This ensures that multi-step workflows contain all referenced scripts and that the SKILL.md file is parseable by Claude.

Summary

• Workflow definition happens in SKILL.md using hierarchical step sequences and decision trees, supporting complex multi-step procedures.
• Resource separation keeps deterministic logic in scripts/, large documentation in references/, and static assets in assets/, making skills portable and maintainable.
• Progressive loading optimizes token usage by loading scripts/ and references/ content only when specific workflow steps require them.
• Standardized tooling via init_skill.py and package_skill.py enforces consistent structure and validates workflow integrity before distribution.

Frequently Asked Questions

How do I create a decision tree workflow in SKILL.md?

Decision trees use hierarchical headings (e.g., ## Workflow Decision Tree → Step 1 → Step 2) to represent branching logic. Claude traverses these sections sequentially, evaluating conditions at each step to determine the next action or script invocation. Each branch can reference different scripts from the scripts/ directory based on intermediate results.

When should I use references/ versus scripts/?

Use references/ for large documentation that provides context but doesn't execute code, such as API specifications, JSON schemas, or policy documents that exceed the token budget for initial loading. Use scripts/ for deterministic, executable code that performs actions like API calls, file processing, or data transformation. Claude loads references on-demand when a step requires extensive context, while scripts are invoked to perform concrete operations.

How does Claude know which script to execute next?

Claude follows the step sequence defined in the SKILL.md workflow section. Each step description explicitly names the script file (e.g., "Claude calls scripts/load_image.py") along with the required arguments. Claude maps the natural language step description to the concrete script invocation, passing parameters extracted from user input or previous step outputs.

What validation occurs before packaging a skill?

The package_skill.py utility validates YAML front-matter syntax, checks that all referenced directories (scripts/, references/, assets/) exist, verifies that scripts have proper execution permissions, and ensures the SKILL.md file contains required metadata fields such as name and description. This prevents deployment of malformed workflow definitions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}