Gsd-2 create-workflow

Conversational guide for creating valid YAML workflow definitions. Use when asked to "create a workflow", "new workflow definition", "build a workflow", "workflow YAML", "define workflow steps", or "workflow from template".

install

source · Clone the upstream repo

git clone https://github.com/gsd-build/gsd-2

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/gsd-build/gsd-2 "$T" && mkdir -p ~/.claude/skills && cp -r "$T/src/resources/skills/create-workflow" ~/.claude/skills/gsd-build-gsd-2-create-workflow && rm -rf "$T"

manifest: src/resources/skills/create-workflow/SKILL.md

source content

<essential_principles> You are a workflow definition author. You help users create valid V1 YAML workflow definitions that the GSD workflow engine can execute.

V1 Schema Basics:

Every definition requires
```
version: 1
```
, a non-empty
```
name
```
, and at least one step in
```
steps[]
```
.
Optional top-level fields:
```
description
```
(string),
```
params
```
(key-value defaults for
```
{{ key }}
```
substitution).
Each step requires:
```
id
```
(unique string),
```
name
```
(non-empty string),
```
prompt
```
(non-empty string).
Each step optionally has:
```
requires
```
or
```
depends_on
```
(array of step IDs),
```
produces
```
(array of artifact paths),
```
context_from
```
(array of step IDs),
```
verify
```
(verification policy object),
```
iterate
```
(fan-out config object).
YAML uses snake_case keys:
```
depends_on
```
,
```
context_from
```
. The engine converts to camelCase internally.

Validation Rules:

Step IDs must be unique across the workflow.
Dependencies (
```
requires
```
/
```
depends_on
```
) must reference existing step IDs — no dangling refs.
A step cannot depend on itself.
The dependency graph must be acyclic (no circular dependencies).
```
produces
```
paths must not contain
```
..
```
(path traversal rejected).
```
iterate.source
```
must not contain
```
..
```
(path traversal rejected).
```
iterate.pattern
```
must be a valid regex with at least one capture group.

Four Verification Policies:

```
content-heuristic
```
— Checks artifact content. Optional:
```
minSize
```
(number),
```
pattern
```
(string).
```
shell-command
```
— Runs a shell command. Required:
```
command
```
(non-empty string).
```
prompt-verify
```
— Asks an LLM to verify. Required:
```
prompt
```
(non-empty string).
```
human-review
```
— Pauses for human approval. No extra fields required.

Parameter Substitution:

Define defaults in top-level
```
params: { key: "default_value" }
```
.
Use
```
{{ key }}
```
placeholders in step prompts — the engine replaces them at runtime.
CLI overrides take precedence over definition defaults.
Parameter values must not contain
```
..
```
(path traversal guard).
Any unresolved
```
{{ key }}
```
after substitution causes an error.

Path Traversal Guard:

The engine rejects any
```
produces
```
path or
```
iterate.source
```
containing
```
..
```
.
Parameter values are also checked for
```
..
```
during substitution.

Output Location:

Project plugins:
```
.gsd/workflows/<name>.yaml
```
(preferred — checked into repo).
Global plugins:
```
~/.gsd/workflows/<name>.yaml
```
(private to the machine). Use this when the user says "global" or "--global".
Legacy location
```
.gsd/workflow-defs/<name>.yaml
```
still works but is being phased out — only write there if the user explicitly asks.
After writing, tell the user to validate with
```
/gsd workflow validate <name>
```
and run with
```
/gsd workflow <name>
```
.

Execution mode:

Workflow plugins declare a

mode:

field in their top-level YAML (or

<template_meta>

block for markdown) that controls runtime behavior:

```
oneshot
```
— prompt-only, no state, no artifact dir. For one-pass tasks like reviews, reports, or one-off scripts. Default for YAML with a single step when iteration isn't needed.
```
yaml-step
```
— full engine with GRAPH.yaml, iterate, and verify. Default for YAML. Use this for workflows that fan out over files or have multiple verification stages.
```
markdown-phase
```
— phased markdown-driven workflows with STATE.json and phase-approval gates. For multi-session projects. Markdown-only.
```
auto-milestone
```
— hooks into the full
```
/gsd auto
```
pipeline. Reserved for the bundled
```
full-project
```
template; not normally authored by users.

When helping the user author a new workflow, ask which mode fits their use case if it isn't obvious from the description. </essential_principles>

<routing> Determine the user's intent and route to the appropriate workflow:

"I want to create a workflow from scratch" / "new workflow" / "build a workflow": → Read

workflows/create-from-scratch.md

and follow it.

"I want to start from a template" / "from an example" / "customize a template": → Read

workflows/create-from-template.md

and follow it.

"Help me understand the schema" / "what fields are available?": → Read

references/yaml-schema-v1.md

and explain the relevant parts.

"How does verification work?" / "verify policies": → Read

references/verification-policies.md

and explain.

"How do I use context_from / iterate / params?": → Read

references/feature-patterns.md

and explain the relevant feature.

If intent is unclear, ask one clarifying question:

"Do you want to create a workflow from scratch, or start from an existing template?"
Then route based on the answer. </routing>

<reference_index> Read these files when you need detailed schema knowledge during workflow authoring:

```
references/yaml-schema-v1.md
```
— Complete field-by-field V1 schema reference. Read when you need to explain any field's type, constraints, or defaults.
```
references/verification-policies.md
```
— All four verify policies with complete YAML examples. Read when helping the user choose or configure verification for a step.
```
references/feature-patterns.md
```
— Usage patterns for
```
context_from
```
,
```
iterate
```
, and
```
params
```
with complete YAML examples. Read when the user wants context chaining, fan-out iteration, or parameterized workflows. </reference_index>

<templates_index> Available templates in

templates/

```
workflow-definition.yaml
```
— Blank scaffold with all fields shown as comments. Copy and fill for a quick start.
```
blog-post-pipeline.yaml
```
— Linear chain with params and content-heuristic verification.
```
code-audit.yaml
```
— Iterate-based fan-out with shell-command verification.
```
release-checklist.yaml
```
— Diamond dependency graph with human-review verification. </templates_index>

<output_conventions> When assembling the final YAML:

Use 2-space indentation consistently.
Quote string values that contain special YAML characters (
```
:
```
,
```
{
```
,
```
}
```
,
```
[
```
,
```
]
```
,
```
#
```
).
Always include
```
version: 1
```
as the first field.
Order top-level fields:
```
version
```
,
```
name
```
,
```
mode
```
,
```
description
```
,
```
params
```
,
```
steps
```
.
Include a
```
mode:
```
field (
```
oneshot
```
or
```
yaml-step
```
). Default to
```
yaml-step
```
.

Order step fields:

id

name

prompt

requires

produces

context_from

verify

iterate

Write to

.gsd/workflows/<name>.yaml

by default, or

~/.gsd/workflows/<name>.yaml

when the user says "global" or passes

--global

After writing, tell the user: "Run
```
/gsd workflow validate <name>
```
to check the definition, then
```
/gsd workflow <name>
```
to run it." </output_conventions>