designing-workflow-skills

Guides the design of multi-phase workflow skills with routing patterns, safety gates, and progressive disclosure.

Updated Mar 22, 2026
One-click install
npx skills add https://github.com/TECH-HY/SKILLS --skill designing-workflow-skills-tech-hy
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: designing-workflow-skills
Source: https://github.com/TECH-HY/SKILLS/tree/main/skills/designing-workflow-skills
Command: npx skills add https://github.com/TECH-HY/SKILLS --skill designing-workflow-skills-tech-hy

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Workflow-based Claude Code skills often fail in execution because of vague descriptions, unnumbered phases, monolithic SKILL.md files, and tool-call patterns that do not scale. This Skill provides structural patterns, anti-pattern catalogs, and review checklists so skills activate correctly and execute reliably. ## Core Features & Use Cases - Five Workflow Patterns: Routing, Sequential Pipeline, Linear Progression, Safety Gate, and Task-Driven patterns with structural skeletons and decision trees for choosing between them. - Anti-Pattern Catalog: Twenty documented anti-patterns (AP-1 through AP-20) with before/after fixes covering structure, workflow design, tool assignment, and scalability. - Progressive Disclosure Rules: The 500-line rule, one-level-deep linking, and sizing guidelines for splitting content between SKILL.md, references/, and workflows/. - Use Case: When building a security audit skill with multiple analysis phases, use the 6-phase design workflow to define scope, pick the Safety Gate pattern, assign least-privilege tools, and self-review against the submission checklist. ## Quick Start Ask the agent to design a new workflow skill for your task domain and follow the six-phase creation process from scope definition to self-review.

Frequently Asked Questions about designing-workflow-skills

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure a multi-phase Claude Code skill?

Number every phase with explicit entry criteria, numbered actions, and exit criteria. Choose one of five patterns (Routing, Sequential Pipeline, Linear Progression, Safety Gate, Task-Driven) based on whether the skill has one path, multiple independent paths, or dependent steps.

What controls when a Claude Code skill activates?

The description field in the SKILL.md frontmatter is the only thing that controls activation. It should contain triggering conditions and keywords in third-person voice, never workflow steps, since Claude may shortcut the body if the description summarizes the process.

How long should a SKILL.md file be?

SKILL.md should stay under 500 lines, ideally 200-400. Detailed patterns go in references/ files (under 400 lines each) and step-by-step processes go in workflows/ files (under 300 lines each), all linked one hop from SKILL.md.

Which tools should a read-only analysis skill declare?

A read-only analysis skill should list only Read, Glob, Grep, TodoRead, and TodoWrite in allowed-tools. Never include Write or Bash on read-only skills, and prefer dedicated tools like Glob and Grep over Bash equivalents like find and grep.

Why does my skill miss results when searching large codebases?

Workflows that grep each file for each pattern produce N×M tool calls, causing the agent to shortcut and miss results. Combine all patterns into a single regex, grep the codebase once, then filter results, and batch subagent work into groups of 10-20 items.

When should I not use a workflow skill structure?

Skip workflow patterns for simple single-purpose skills with no multi-step process; write the SKILL.md directly instead. This guidance also does not cover plugin configuration like plugin.json, hooks, or slash commands.