--- name: workflow-create description: Creates, composes, updates, and deletes reusable skill workflow families from broad goals or from skills the user already owns. Use when the user invokes /workflow-create (case-insensitive), or asks to design, scaffold, wire existing skills together, compose, extend, repair, validate, or remove a parent coordinator skill plus child skills, linkages, a README, runStatus tracking, and reusable workflow contracts. --- # Workflow Create Create, compose, update, and delete reusable skill workflow families — from one broad goal, or by wiring skills the user already owns into a workflow. Treat `/workflow-create` as the user-facing invocation for this skill. The output is a maintained operating procedure: a parent coordinator skill, bounded child skills, a single linkage ledger, a short README, runStatus tracking, validation checks, and enough handoff structure for future runs to work without relying on chat memory. This skill creates and maintains the workflow family. It stays focused on the workflow and context, and defers skill-authoring craft to Anthropic's `skill-creator`: it uses the installed `skill-creator` if present, otherwise the agent retrieves it from the canonical source, then shapes the parent and child skills to its standards (see Phase 0 and [`references/skill-standards.md`](references/skill-standards.md)). Every skill it generates carries a Workflow Creator signature so a family member is always identifiable later (see Signature And Watermark). The generated parent skill runs the actual workflow later whenever the user invokes it; it should not call `skill-creator` during ordinary workflow runs unless the workflow itself is explicitly about creating or modifying skills. ## Quick Start Use this skill when the user wants to turn a repeatable process into a reusable family of skills, to wire skills they already own into a workflow, or to change or remove one that already exists. The user need not say the word "workflow" or "build me a workflow" — invoking this skill on a bare goal (for example, `/workflow-create "launch niche content sites"`) is itself the instruction to build that goal as a reusable workflow. ```text /workflow-create "Build me a reusable workflow for launching niche content sites." ``` ```text /workflow-create plan-only "Design a workflow for researching jobs, tailoring resumes, preparing interviews, and tracking follow-ups." ``` ```text /workflow-create compose "wire my-voice-it, voice-distance-check, and polish-my-voice-it into one publishing workflow." ``` ```text /workflow-create update "Add a publish step to the acme-website workflow." ``` ```text /workflow-create delete "Remove the content-site workflow." ``` Expected result for `create` (and `compose`, which reuses existing skills as members instead of authoring every child): - One parent coordinator skill named `-workflow`. - Usually two to five child skills, or a single skill when the goal does not justify a family. For `compose`, the members are the user's existing skills (adopted into the family and re-prefixed) plus any newly authored gap-filler skills. - A coordinator `linkages.md` that registers every family member, the run order, and a version stamp. - A short coordinator `README.md`. - A `runStatus.md` pattern written into the active project during each run. - A static validation result. ## Operating Rule Default to building the smallest useful workflow. First decide whether the goal even needs a family (the family gate in Phase 2). When it does, aim for two to five child skills; use more than five only when the domain has clear standalone responsibilities that would otherwise make a child too broad. Ask when the goal is too ambiguous to decompose precisely, when the likely skill boundaries are uncertain, or when multiple decompositions would produce meaningfully different workflows. A broad goal yields a generic workflow, so sharpening a vague goal into a specific one (see Phase 1) is mandatory, not optional. Otherwise proceed with clear assumptions and record them. Before creating files, collect enough upfront context to avoid mid-work interruptions. Prefer one focused intake round that captures the project name, workflow name, purpose, concrete examples, success criteria, and install root. It is fine to ask the user directly for these. ## Skill Design Principles Every generated skill should be: - Concise: keep `SKILL.md` lean and move durable details into directly linked references. - Responsible for one thing: a child skill owns one bounded capability, not a multi-step workflow. - Composable: it can be run by the parent, reused by another workflow, or called standalone. - Progressively disclosed: metadata triggers the skill, `SKILL.md` gives the core procedure, references load only when needed. - Harness-agnostic: write paths, commands, and state conventions that work in any agent that can read instructions and invoke skills (Claude Code, Codex, Cursor, CLI agents). - Process over prose: actionable workflows with checkpoints, evidence, and exit criteria, not essays about best practices. - Assumption-aware: surface assumptions before acting, stop when requirements conflict, and touch only the intended workflow files. ## Lifecycle This skill supports four verbs. Infer the verb from the request; default to `create`. - `create` (default): build a new workflow family. Modifiers: - `plan-only`: produce architecture, naming, and contracts without writing skill files. - `shell` / `scaffold-only`: write the coordinator and child skill shells, `linkages.md`, and `README.md` with minimal references. - `compose`: wire skills the user already owns into a workflow family — adopt the named existing skills as members (re-prefixed into the family) and generate the coordinator, `linkages.md`, and `README.md` around them instead of writing every child from scratch. See Compose Lifecycle. `create` also auto-detects this: when the request names existing skills to chain together, treat it as `compose` even without the explicit verb. - `update`: modify an existing family. Add a child, edit a child, remove a child, repair drift (paths, frontmatter names, orphans), re-sync `linkages.md` and `README.md`, and bump the version stamp. This absorbs the older `extend-existing` and `repair-linkages` flows. See Update Lifecycle. - `delete`: remove an existing family safely, with confirmation and orphan protection. See Delete Lifecycle. ## Naming Convention The naming prefix is what binds a family. There are no family folders; skills are installed flat and grouped by their shared prefix. - Workflow prefix: `` when there is no separate project or brand, or `-` when one brand or project will host multiple workflows. - Coordinator skill: `-workflow`. Exactly one per family. The `-workflow` suffix marks the single entrypoint that runs the whole sequence and calls the children. Children never use it. - Child skills: `-` with short, concrete phase verbs such as `init`, `research`, `scaffold`, `draft`, `design`, `transform`, `audit`, `publish`. An optional `-it` suffix is allowed but drop it when the name grows long. - Project run folder: `-workflow-run/runStatus.md`, created in the active project, never inside the skill folder. Examples: ```text voice-workflow (coordinator) voice-capture voice-polish voice-publish acme-website-workflow (coordinator) runs the whole website workflow acme-website-init acme-website-design acme-website-audit acme-content-workflow (coordinator) a second, separate workflow under the same brand acme-content-research acme-content-draft ``` Every generated name must conform to the Agent Skills open standard (https://agentskills.io/specification): - 1–64 characters. - Lowercase letters, digits, and hyphens only (`a-z`, `0-9`, `-`). - Must not start or end with a hyphen, and must not contain consecutive hyphens (`--`). - Must match the skill's parent folder name exactly. - Never contains `claude` or `anthropic`. These rules apply to `workflow-create` itself and to every coordinator and child skill it generates. `validate_workflow_family.py` enforces them, and `skills-ref validate` (the official validator) confirms spec conformance — see Phase 7. ## Phase 0: Preflight — Skill Authoring Standards `workflow-create` stays light. [`references/skill-standards.md`](references/skill-standards.md) inlines the **stable skill-format basics** (folder layout, frontmatter, progressive disclosure, the harness-fatal YAML rules) for offline self-sufficiency, and **points to Anthropic's `skill-creator`** for the deeper, evolving craft and the scaffolding/validation tooling. Run this preflight for `create`, `shell`, and `update`; skip for `plan-only` and `delete`. Resolve the standards via [`references/skill-standards.md`](references/skill-standards.md): 1. If `skill-creator` is already installed (host agent exposes it, or a folder exists under `${SKILLS_ROOT}/skill-creator`), use it. The installed copy is whatever the user last pulled, so upstream updates are captured this way. 2. If it is not present, **retrieve it** from the canonical source (`npx skills add anthropics/skills --skill skill-creator`, or fetch the files into `${SKILLS_ROOT}/skill-creator`), then follow it. The agent does the fetch at authoring time — this skill only points to where it lives. 3. If retrieval is impossible (offline/unreachable), proceed using the non-negotiable frontmatter rules in `references/skill-standards.md` and tell the user `skill-creator` could not be fetched. Whichever path, generation must satisfy `skill-creator`'s standards and the local frontmatter rules, the Phase 5 requirements (including the watermark) still apply, and the family is checked with `scripts/validate_workflow_family.py` before finishing (it hard-fails on invalid YAML frontmatter and merge-conflict markers — the breakage that silently de-registers a skill). ## Phase 1: Understand Goal And Name Capture: - Verbatim user request. - Project or brand name (optional). Drives the first prefix segment when present. - Workflow name (required). Drives the workflow prefix segment. - Purpose, in one or two sentences, for the README and coordinator context. - Desired outcome. - Two to three concrete use cases the workflow should support. - Trigger phrases that should invoke the coordinator, and negative triggers that should not. - Example inputs and outputs when available. - Target user or audience. - Constraints, assets, URLs, and references. - Desired automation level and validation expectation. - Success criteria for the workflow and for each child skill. - Distribution target: personal install, team install, public package, or repository template. - Install scope: global (default) or project-local. See Install Scope below. - Host harness: which agent is running this skill (Claude Code, Codex, Cursor, etc.). Detect it rather than asking — see Detect The Host Harness below. It is fine to ask the user directly for project name, workflow name, and purpose. Auto-derive a candidate workflow name from the goal, then confirm it. Convert the confirmed project and workflow names into the lowercase kebab-case prefix described in the Naming Convention. **Sharpen a broad goal before decomposing.** The quality of the generated skills is bounded by how specific the goal is — a broad one-liner (for example, "launch niche content sites") produces a generic, mediocre workflow. When the goal is vague, do not proceed on it; ask one focused round of questions that narrows it into a specific, well-scoped goal, prioritizing the answers that change the skill breakdown: - Who or what it's for, and what "good" output looks like. - The concrete steps the user already does by hand, in order. - Inputs available at the start, and the artifact expected at the end. - Tools, platforms, formats, or style the workflow must respect. - What should be explicitly out of scope. If the user has already defined the skills or the breakdown in their prompt (the steps, their order, or the child skills), treat that as the decomposition and honor it — confirm only what is genuinely ambiguous rather than re-deriving it. If the goal is already specific and well-scoped, proceed with explicit assumptions and record them in the brief. When the goal is vague or the user asks what this can do, offer the closest worked example from [`references/examples.md`](references/examples.md) as a starting template (for example, "something like the `clarify` writing workflow" or "composed like the `ship` example"), then sharpen their specific goal from there. The examples span the simple → complex range and the create/compose lifecycles. ### Detect The Host Harness `.agents/skills` is the standard, cross-client home for skills under the Agent Skills open standard: compliant agents scan it specifically so skills installed by one tool are visible to the others. **Prefer the standard `.agents/skills` location, and treat `.claude/skills` as the single exception — used only when Claude Code itself is the installing harness.** That exception is safe because most compliant agents also scan `.claude/skills` for pragmatic compatibility, so a Claude-Code install is still broadly discoverable, and the opt-in symlink (see Cross-Harness Access) closes any remaining gap. Determine the host harness with a simple, detection-first approach — do not ask the user which agent they are in. 1. **Self-identify (primary).** You are the running agent. If you are Claude Code, the host harness is Claude Code. If you are Codex, Cursor, Gemini CLI, or another agent, use that identity. This is the main signal — rely on it. 2. **Confirm from the environment (optional sanity check).** Claude Code exports `CLAUDECODE=1` (plus `CLAUDE_CODE_*` vars) into the shell. If you want to corroborate, a quick `env | grep -i claudecode` is enough. Filesystem checks like "does `~/.claude` exist" are weak — a directory only means the tool is *installed*, not that it is the active harness — so prefer self-identification and env vars over directory probing. 3. **Map harness → skills home (standard-first):** - **Claude Code** (the only exception) → `${USER_ROOT}/.claude/skills` (global) or `/.claude/skills` (project-local), its native home. - **Every other / unknown harness** → `${USER_ROOT}/.agents/skills` (global) or `/.agents/skills` (project-local), the standard cross-client home. Set `${SKILLS_ROOT}` to the resolved home for the detected harness and chosen scope. This is where the real folders are written — no symlink needed for the host harness to find them. Cross-linking to *other* harnesses is a separate, opt-in step (see Cross-Harness Access). ### Install Scope The family installs at one of two scopes, independent of harness. The path follows the standard-first rule above — `.agents/skills` by default, `.claude/skills` only when Claude Code is the installing harness: - **Global (default).** Under the user's home: `.agents/skills` (standard), or `.claude/skills` when Claude Code is the host. Available across all of the user's projects. - **Project-local.** Under a named ``: `/.agents/skills` (standard), or `/.claude/skills` when Claude Code is the host. Use when the user wants the workflow checked into and scoped to one repo (shareable with collaborators, versioned with the code). Default to global, but always tell the user which scope and which path you are using and offer the other. If the request clearly implies one ("install this in this repo", "just for this project", "make it available everywhere"), follow that. If scope is ambiguous and the choice would matter, ask. Resolve install locations from the user's home directory or the named project root, not hardcoded machine-specific paths. If the chosen `${SKILLS_ROOT}` does not exist, create it for `create` or `shell` modes and tell the user where it was created. For `plan-only`, state the resolved root and that it should be created before install. Generated families are plain Markdown folders with front matter, not locked to any home. The coordinator `README.md` lists the member folders and their paths so the user can move or copy the whole set into any agent's skill, rule, or prompt location (`.cursor/rules/`, Claude Code, Gemini CLI, Codex, Aider, Windsurf, OpenCode). ### Cross-Harness Access (opt-in) After writing the family to the host harness's native home, offer to make the same skills discoverable by *other* agents on the machine via a symlink. Only ask once, in plain language, and only act on a yes. This step applies only to the folders just written in the current `create`, `shell`, or `update` run — never touch unrelated skill folders in `.claude/skills` or `.agents/skills`. Skip entirely for project-local installs. Pick the offer based on the detected host harness: - **Host is Claude Code** (family written to `.claude/skills`): ask whether they also want these skills available to non–Claude Code agents. Something like: *"Want me to also link these into `~/.agents/skills` so other agents (Codex, Cursor, etc.) can find them? It's a one-time symlink — no copies, edits stay in sync."* On yes, for each new member create `ln -s ${USER_ROOT}/.claude/skills/ ${USER_ROOT}/.agents/skills/`. - **Host is another agent** (family written to `.agents/skills`): ask whether they also want these in Claude Code. Something like: *"Want me to also link these into `~/.claude/skills` so Claude Code picks them up too? One-time symlink, stays in sync."* On yes, for each new member create `ln -s ${USER_ROOT}/.agents/skills/ ${USER_ROOT}/.claude/skills/`. Wiring rules for either direction: 1. **Check the target root exists.** If the target skills dir is absent, mention it and offer to create it; don't fail the install over it. 2. **Per-member status.** For each new member, see whether the target already has an entry: "already symlinked" (skip), "real directory" (warn that edits won't sync, offer to replace with a symlink only on confirmation), or "missing" (create the symlink). 3. **Symlinks unavailable.** If `ln -s` fails (e.g. Windows without privileges), tell the user and offer to copy the folders instead, noting copies won't auto-sync on later updates. 4. **Report what you did**, with the resolved paths. For public or distributable workflows, write paths with placeholders such as `${USER_ROOT}`, `${SKILLS_ROOT}`, and `${PARENT_SKILL_DIR}`. Avoid absolute paths that include the creator's machine-specific username. ## Phase 2: Family Gate Before decomposing, decide whether the goal needs a family at all. If the goal collapses to one bounded capability, build a single skill and stop. Follow `references/skill-standards.md` and emit just that skill, wrapped in a minimal coordinator so the workflow can grow later: a `-workflow` coordinator plus a `linkages.md` with one entry. Do not invent extra phases to justify a family. Only proceed to a multi-skill decomposition when at least two phases each pass the split test in Phase 3. A coordinator that sequences a single real step is acceptable only as the single-skill case above; never split one capability into two children to look like a workflow. ## Phase 3: Decompose Domain Spend real design time here. The goal is the smallest set of standalone, composable skills that run well in sequence and independently. For a proven shape to borrow from, consult [`references/examples.md`](references/examples.md): it shows how five real goals were gated and split (medium sequential, complex multi-tool, context-aware with a child-owned reference, a composed family with conditional steps, and a single-skill case where the gate fired) and *why* each boundary was drawn. Adapt the closest one rather than decomposing from scratch. Split the workflow into phases with crisp verbs. A phase deserves a child skill only when it satisfies at least two of these tests: - Requires distinct expertise. - Produces a distinct artifact. - Can be reused independently. - Would make the parent too large if embedded. - Needs separate references, scripts, or assets. - Has its own validation or quality bar. - Has different failure modes, permissions, or rollback needs. Do not create a child skill merely because something is a step. Merge phases when they share the same inputs, produce one combined artifact, have the same validation bar, or would rarely be useful alone. Split/merge checks: - Standalone test: could a user sensibly call this child by itself? - Contract test: does it have clear inputs, outputs, and done criteria? - Context test: would separating it reduce context load or avoid mixing domains? - Coupling test: if it always needs the previous child and cannot infer missing context, merge it. - Count test: if there are more than five child skills, justify each one or merge the weakest boundaries. Prefer phase verbs like `research`, `scaffold`, `draft`, `transform`, `validate`, `publish`, and `audit`. Avoid vague phases like `strategy`, `misc`, or `support`. Name every skill with the workflow prefix per the Naming Convention. Classify the workflow pattern and record it in `linkages.md`: - `sequential`: phases must run in a fixed order. - `multi-tool`: phases coordinate multiple MCP servers, local tools, APIs, or apps. - `iterative`: output quality improves through validation and refinement loops. - `context-aware`: the coordinator chooses different tools or paths based on input. - `domain-intelligence`: the value is embedded judgment, policy, standards, or review. Before moving to contracts, produce a short decomposition review: ```md ## Decomposition Review - Project / workflow prefix: - Family needed? (yes / single-skill) - Candidate child skills: - Why these boundaries: - What was merged and why: - Open decomposition questions: ``` If open questions would change the number, names, order, or responsibilities of child skills, ask the user before writing files. Offer a recommended decomposition, but invite correction. ## Phase 4: Design Contracts Write a contract for each child before creating files: ```md ## - Role: - Trigger: - Inputs: - Outputs: - Reads: - Writes: - Validation: - Evidence: - Exit criteria: - Error handling: - Rollback or recovery: - Skip conditions: - Boundaries: - Orchestration note: - Standalone usage: - Why this is separate: ``` The parent is the coordinator skill and single user-facing entrypoint. It does not replace the child skills or own their implementation. Standalone, the parent mainly parses the verb and mode, initializes `runStatus.md`, checks `linkages.md`, sequences child skills, passes handoff context, and synthesizes the final result. Children own their bounded phase. ## Phase 5: Generate Skill Family Install skills flat under the skills root. The family is bound by the shared naming prefix, not by a wrapping folder. Only the coordinator folder holds family-level files. ```text ${SKILLS_ROOT}/ -workflow/ SKILL.md linkages.md README.md references/ scripts/ -/ SKILL.md references/ -/ SKILL.md references/ ``` The coordinator folder is the family hub. It holds `SKILL.md`, the single `linkages.md` (registry, run order, load-when notes, and version stamp), a short `README.md`, and any change-checking helper script. Do not create `linkages.md`, `README.md`, or `index.md` inside child folders. `README.md` is human-facing and short: what the workflow does, the coordinator command to call, the modes, what each child does, where `runStatus.md` appears during a run, and the member skill paths so the user can copy the set into another harness. There is no separate `index.md`. The navigation and load-when guidance live inside `linkages.md`. Do not add README, changelog, or setup files inside child skill folders. If human-facing docs are needed for a public package, put them at the repository root. Follow `skill-creator`'s standards (resolved in Phase 0 — installed or fetched) for every generated skill: correct frontmatter, clear trigger descriptions, concise bodies, progressive disclosure, direct `references/` links. Always enforce the non-negotiable frontmatter rules in [`references/skill-standards.md`](references/skill-standards.md) on top, even when offline. This is a creation-time responsibility, not a runtime responsibility of the generated coordinator. Generated skills must follow core requirements: - Folder name and frontmatter `name` match exactly. - Names use lowercase kebab-case, no spaces, underscores, capitals, `claude`, or `anthropic`. - Exactly one skill in the family is named `-workflow`; it is the coordinator. - `SKILL.md` is named exactly `SKILL.md`. - `SKILL.md` is saved as UTF-8 without BOM and starts at byte 1 with literal `---`; no invisible bytes may appear before frontmatter. - Description states what the skill does and when to use it, includes realistic trigger phrases, stays under 1024 characters, and contains no angle brackets. - Every generated skill carries the Workflow Creator signature (see Signature And Watermark below). - Use `scripts/` for deterministic fragile checks, `references/` for on-demand context, and `assets/` for files used in output. - Keep references one level deep; if a reference is longer than 100 lines, include a short table of contents. ### Signature And Watermark Every skill this tool generates — coordinator and children, on `create`, `shell`, `compose`, and `update` — must carry a Workflow Creator signature so the family is identifiable later by a human or a product harness scanning a skills directory. This is the durable marker that a skill came from Workflow Creator. A `compose` skill that is adopted (re-prefixed into the family) is signed like any generated member, with `adopted: true` added to its `metadata` to record that it began life as a skill the user already owned. Write the signature in two places in each generated `SKILL.md`: 1. A `metadata` block in the frontmatter (the canonical, machine-readable marker): ```yaml metadata: generator: workflow-create generator-version: workflow-prefix: role: coordinator # or: child ``` 2. A short human-visible footer as the last line of the body: ```md --- _Generated by workflow-create (Workflow Creator) · family `` · v. This signature marks the skill as part of a Workflow Creator family._ ``` Detection contract: the canonical signal is the frontmatter field `metadata.generator: workflow-create`. A harness built on top can recursively scan skill folders and treat any `SKILL.md` whose `metadata.generator` equals `workflow-create` as Workflow-Creator-generated, then read `workflow-prefix` to group families and `generator-version` to detect staleness. Keep these key names stable; do not rename them per family. When the `update` lifecycle bumps the version stamp, update `generator-version` in every touched skill's signature to match. ### Description And Triggering Because the family is installed flat and every child is standalone-callable, members compete to match a user request. Write descriptions so routing stays correct: - The coordinator (`-workflow`) description must claim the full, multi-step workflow and the broad trigger phrases. - Each child description must claim only its one phase and explicitly direct full-workflow requests to `/-workflow`. ## Phase 6: Wire Workflow The generated parent skill must: - State clearly that it is the workflow coordinator and user-facing entrypoint, not the creator of the family. - Read `linkages.md` before running, and verify child paths, frontmatter names, and orchestration notes against it. - Take the default run order from `linkages.md`, but honor run-scope sequence overrides in the brief: reordering steps, skipping steps, running only a subset, or stopping early (see Run-Scope Sequence Overrides below). Run-scope overrides apply to that run only and never edit `linkages.md`. - Create or update one `runStatus.md` per run in the active project, never inside the installed skill family. - Prefer the target project or repo root when the request names one. If the target workspace is not obvious, ask where to store the run folder. If the user skips, use the current working directory fallback and tell the user the chosen path. - Store the file at `/-workflow-run/runStatus.md`. For fallback cases, use `/.workflow-runs/-workflow-run/runStatus.md`. - Resolve where this run's **deliverables** land and in what form, using the same lightweight rule as `runStatus.md`: do a basic check of the project (is it a repo? what type — web app, library, docs, plain folder? where do similar files already live? what's already installed?), pick a sensible portable default (Markdown for prose, a self-contained file for a visual, reuse an existing convention when one exists), and **ask the user only when context demands** it — when the destination is ambiguous, the choice would scaffold heavily, install a dependency, or overwrite something. Record the resolved location in `runStatus.md`. Never write deliverables into the installed skill folder. This is a best-practice nudge, not a rigid spec: the coding agent supplies the intelligence to read the project and decide; the coordinator's job is only to pause and resolve this deliberately instead of scattering files. Leave format/tool/path specifics to the children and to how the user later evolves them. - Preserve the user request, derived inputs, dependency checks, step table, outputs, blockers, and log in `runStatus.md`. Keep most-recent run state; overwrite or append a short prior-run note rather than keeping full run history. - Mark each step `in-progress`, then `done`, `skipped`, or `blocked`. - Pass only relevant context to each child, including the exact `runStatus.md` path for this run. - Record each child's important outputs, changed files, and artifacts in `runStatus.md` immediately after that step completes. - Stop on dependency drift that could change behavior. - Write handoffs so any child is resumable from `runStatus.md` alone, without the parent's working memory. The agent may stay in one context or, if its context is constrained, continue in a fresh context or subagent; either way `runStatus.md` is the resume point. Do not encode harness-specific context-management mechanics. Each generated child skill must include: ```md ## Orchestration Linkage - Parent: `/-workflow` - Previous: `/` or none - Next: `/` or complete - When used by `/-workflow`, read and update this run's project `runStatus.md` for this step only. - When used standalone, derive a local brief from the current request, do not create or touch any workflow `runStatus.md`, and produce this phase's output independently. ``` Children must be callable standalone as well as by the parent. When a parent run is active, children read the project `runStatus.md`, respect sibling boundaries, and update only their assigned row or notes. When no parent run exists, children do not write `runStatus.md` at all; they ask only for missing inputs that cannot be safely inferred, then complete their bounded phase. Only the coordinator owns `runStatus.md`. ### Run-Scope Sequence Overrides The generated coordinator must let the user change which children run, and in what order, for a single run — without editing the family. Build this into the parent so it can follow plain-language direction such as "run only research and publish", "skip the audit step", "do draft before research this time", or "stop after design". The coordinator must: - Treat the `linkages.md` Chain as the default order, then parse any reorder, skip, subset, or stop-early directives from the brief into an effective order for this run. - Check dependency safety before applying: if a skipped or moved-earlier step normally produces inputs a later step needs, and those inputs are not already present in `runStatus.md` or safely derivable, warn the user and either ask how to proceed or mark the dependent step `blocked`. Respect each child's documented skip conditions. - Record both the default order and the effective order in `runStatus.md`, with a one-line reason for every skipped or reordered step. Mark un-run steps `skipped`. - Apply the override to this run only. Never write run-scope changes into `linkages.md`. To make an ordering change permanent (a new default order, or a step that should be skipped by default), the change must go through `/workflow-create update`, which re-syncs `linkages.md` and bumps the version. If the user asks the coordinator to make a sequence change "permanent" or "always", the coordinator should say so and route them to the update lifecycle rather than silently persisting it. ## Phase 7: Validate Run static validation before finishing: - Frontmatter names match folder names and the `linkages.md` registry. - Every `SKILL.md` starts at byte 1 with literal `---` and has no UTF-8 BOM before frontmatter. - Exactly one family skill is named `-workflow`. - Every family skill name starts with the workflow prefix. - Parent `linkages.md` lists every member and matches actual paths. - No `-*` skill exists on disk that is missing from `linkages.md` (orphan check); if found, ask the user whether it belongs. - Every child has an orchestration linkage note and points back to `/-workflow`. - Parent `SKILL.md` references `linkages.md` and `runStatus.md`. - Coordinator `README.md` exists and names the command, modes, child sequence, and runStatus location. - Every child includes standalone-mode instructions and does not require a previous sibling run. - Every generated skill (coordinator and children) carries the `metadata.generator: workflow-create` signature and matching footer. - The coordinator describes how it accepts run-scope sequence overrides and records the effective order in `runStatus.md`. - Linkage paths use placeholders for distributable workflows instead of creator-specific absolute paths. Run `scripts/validate_workflow_family.py --skills-root ` after creating or updating a family. If validation fails, fix the generated files and rerun it. This validator checks family structure (linkages, orphans, watermark, prefix discipline), not behavior. When available, also run the **`skills-ref` reference validator** on each generated skill folder as a spec-conformance sanity check (frontmatter, naming rules, directory layout): ```bash skills-ref validate skills-ref validate ``` `skills-ref` is the Agent Skills standard's reference library — a Python CLI from `agentskills/agentskills/skills-ref`, installed with `pip install -e .` or `uv sync` from that subdirectory (it is not on npm). Its README notes it is a demonstration reference, not a production tool, so treat its result as a spec sanity-check and keep `scripts/validate_workflow_family.py` as the enforced gate. The two are complementary: `skills-ref` checks the open-standard skill format, `validate_workflow_family.py` enforces the family/coordinator contract. If `skills-ref` is not installed, do not block on it — the family validator already covers the harness-fatal cases. A structurally valid family can still have semantic handoff gaps, so also run the forward test below. For forward validation, run the generated parent on a small example in plan-only mode. Prove that the parent can derive inputs, initialize `runStatus.md`, hand off to children, record status, and summarize completion or blockers. Add a validation section to the generated parent covering triggering tests (obvious request, paraphrased request, unrelated non-trigger), functional tests (valid output, expected artifacts, child handoff, error handling, edge cases), how the workflow improves over manual prompting, and stop criteria for iterative workflows. For workflows with external tools or MCPs, include connection/auth checks, fallback behavior, and rollback for each irreversible step. ## Phase 8: Prepare Distribution When the workflow is public, team-facing, or package-like: - Keep human-facing docs at the repository root, not inside child skill folders. - Include install instructions that explain the selected skills root. - Include portability instructions: the family is plain Markdown, and the coordinator `README.md` lists the member folders to copy. - Explain the outcome the workflow enables, not only the files it creates. - Package only after validation passes when packaging is requested. ## Update Lifecycle Use when the user wants to change an existing family (add, edit, or remove a child; reorder the default sequence; mark a step default-skipped or optional; repair drift; extend phases). 1. Locate the family by its `-workflow` coordinator and read its `linkages.md`. 2. Run the orphan and drift checks: compare `linkages.md` against the `-*` skills on disk. For any orphan, ask the user whether it belongs in the workflow or is a separate standalone skill; never absorb or delete it without confirmation. 3. Apply the change following `references/skill-standards.md`: add a new child folder, edit an existing child, remove a child, or change the default run order (reorder steps, or mark a step default-skipped/optional in the Chain). 4. Re-sync `linkages.md` (run order, paths, frontmatter names, previous/next) and `README.md`. For a reorder, also update each affected child's Previous/Next orchestration note. 5. Bump the version stamp in `linkages.md`, update the `generator-version` in every touched skill's signature to match, and append a change-log line. 6. Re-run validation (Phase 7). Confirm with the user before any change that alters the default run order or removes a child, since those can change behavior. Permanent ordering changes belong here; one-off ordering changes for a single run are handled by the coordinator at run time (see Run-Scope Sequence Overrides) and must not be written into `linkages.md`. ## Compose Lifecycle Use when the user wants to wire skills they already own into a workflow, rather than have every step authored from scratch. Triggered by the explicit `compose` verb, or auto-detected from `create` when the request names existing skills to chain (for example, "wire `a`, `b`, and `c` into a workflow"). This reuses the normal flow (Phase 1 intake, Phase 4 contracts, Phase 5–7 generation, wiring, validation) with these differences: 1. **Resolve the named skills.** Locate each referenced skill on disk by name across the skills root(s). If a named skill cannot be found, list what was and wasn't resolved and ask the user to confirm names or paths before continuing. Do not invent a skill that does not exist. 2. **Confirm the rename up front (required).** Composed skills are adopted into the family and re-prefixed to `-` so the family is uniform, groupable, and passes validation. This changes how the user invokes them. Before touching anything, state plainly which skills will be renamed and to what (for example, `my-voice-it → nichesite-voice`), and that the old invocation names will no longer work. Proceed only on confirmation. If the user declines, do not force the rename — explain that a family member must carry the prefix, then either pick a different skill, author that step as a fresh child instead, or stop. (A skill the user wants to keep callable under its original name across many contexts is better left standalone and simply referenced from the README, not adopted.) 3. **Adopt each confirmed skill.** Rename the skill folder and its frontmatter `name` to `-`, move any references/scripts/assets it owns with it, add the Workflow Creator signature (frontmatter `metadata` + footer) with `role: child` and `adopted: true`, add an Orchestration Linkage block, and bring its description up to family standards (state what it does, include "use when" triggers, and direct full-workflow requests to `/-workflow`). Register it in `linkages.md` as a normal member. Do not delete or overwrite the skill's actual capability — only rename, relocate, and annotate. 4. **Fill the gaps.** Author any missing phases as normal new child skills (full generation, full signature) so the chain is complete. 5. **Wire and validate.** Build the coordinator, `linkages.md`, and `README.md` over the combined set, then run Phase 7 validation. Adopted members look identical to generated ones to the validator, so the standard checks apply unchanged. Safety: renaming or moving a skill the user already relies on is the one irreversible step here — always confirm it explicitly (step 2), and never delete or overwrite an existing skill's capability during composition. ## Delete Lifecycle Deleting a family removes files; treat it as destructive. 1. Read the `-workflow` coordinator's `linkages.md` to get the exact member list. 2. Show the user the full list of folders that will be removed and confirm before deleting anything. 3. Delete only skills listed in `linkages.md`. Never auto-delete a `-*` skill that is not in the ledger; surface it as an orphan and ask first. 4. Ask whether to remove the coordinator's `linkages.md` and `README.md` as well, or leave them as a tombstone. 5. Note that project `runStatus.md` files live in the user's projects, not the skill family; do not delete those unless the user explicitly asks. ## Reference Patterns Read [`references/workflow-patterns.md`](references/workflow-patterns.md) when writing generated parent skills, child skills, the linkage ledger, run ledgers, or validation prompts. Read [`references/examples.md`](references/examples.md) for named, validated example families to offer during intake (Phase 1) or borrow a decomposition shape from (Phase 3). Worked, runnable versions of those families were generated into an isolated local sandbox (`testing/`, not shipped with the published skill) so simulating a run never touches installed skills. ## Finish Criteria Finish only when the requested verb and mode are complete and the user can see: - Coordinator skill path and child skill paths (or, for delete, the removed paths). - Linkage ledger path and version. - README path. - runStatus location or pattern. - Validation result. - Trigger and functional test plan. - Distribution notes when relevant. - Any assumptions or unresolved decisions.

workflow-create

Install this skill

Comments