write-recipe

name	write-recipe
description	Generate YAML recipes for .autoskillit/recipes/. Use when user says "make script skill", "generate script", "script a workflow", "write a script", "create a script", "new recipe", "write a pipeline", or when loaded by other skills for script formatting.
hooks	{"PreToolUse":[{"matcher":"*","hooks":[{"type":"command","command":"echo '[SKILL: write-recipe] Writing recipe...'","once":true}]}]}

Make Script Skill

Format a workflow into a YAML recipe following the workflow schema.

When to Use

• Standalone: User wants to create a new recipe from scratch
• Loaded by another skill: Another skill (e.g., setup-project) loads this via the Skill tool to format a workflow it has already discovered.

Arguments (standalone mode)

/autoskillit:write-recipe

No positional arguments. The skill prompts interactively for workflow details.

Critical Constraints

NEVER:

• Create SKILL.md files (not in .claude/commands/, .claude/skills/, or anywhere else)
• Create Markdown companion files alongside the YAML script
• Create files outside .autoskillit/recipes/ directory
• Tell the user to run a script with /autoskillit:<name> syntax

ALWAYS:

• Save the script to .autoskillit/recipes/{name}.yaml as the ONLY output
• Call validate_recipe after saving and fix any errors
• Use "recipe" terminology (not "skill script")

Output Path Isolation (Required)

Every recipe that produces output files MUST scope its write destinations through a per-run context variable captured in the init step:

• Use init to create a unique timestamped directory and capture its path as ${{ context.work_dir }}, ${{ context.planner_dir }}, or similar.
• All downstream steps reference their output directories via ${{ context.<var> }}/subdir/ — never via bare {{AUTOSKILLIT_TEMP}}/name/....
• The non-unique-output-path lint rule (severity: ERROR) rejects any recipe step that uses a bare {{AUTOSKILLIT_TEMP}}/ path without a context-variable prefix.

Valid patterns:

• ${{ context.planner_dir }}/phases/ (run-scoped via captured unique dir)
• ${{ context.work_dir }}/output/ (clone-scoped)

Invalid pattern (rejected by lint):

• {{AUTOSKILLIT_TEMP}}/myrecipe/data/ (bare — shared across runs, causes stale artifacts)

How Scripts Are Loaded

Recipes have their own discovery and invocation mechanism — completely separate from the skill system. You do not need to create anything else for the script to be usable. The lifecycle is:

1. You save the YAML file to .autoskillit/recipes/{name}.yaml
2. The user discovers it via list_recipes MCP tool (lists all scripts in that directory)
3. The user loads it via load_recipe("{name}") MCP tool (returns raw YAML)
4. An agent executes it by interpreting the YAML steps and calling MCP tools directly

No SKILL.md, no slash command registration, no Markdown companion file — the YAML file in .autoskillit/recipes/ is the only artifact needed. The MCP tools handle everything else.

The Script Format

Every generated script MUST follow the workflow YAML schema:

name: {script-name}
autoskillit_version: "{version}"  # from kitchen_status.package_version
description: {One line description.}
summary: {Concise pipeline chain, e.g. "plan > verify > implement > test > merge"}

ingredients:
  var_name:
    description: {What this input is for}
    required: true          # or false
    default: {value}        # optional

steps:
  step_name:
    tool: {mcp_tool_name}
    with:
      arg1: "${{ inputs.var_name }}"
      arg2: "literal value"
    capture:                # optional — extract values for later steps
      var_name: "${{ result.field_name }}"
    on_success: next_step
    on_failure: escalate
    retry:                  # optional
      max_attempts: 3
      on: needs_retry
      on_exhausted: escalate
  done:
    action: stop
    message: "Pipeline complete."
  escalate:
    action: stop
    message: "Failed — human intervention needed."

Format Rules

• Top-level fields: name, autoskillit_version (stamped), description, summary (required), inputs, steps
• Inputs: each with description, optional required (default false) and default
• Steps: each has either tool (MCP tool call) or action (terminal: stop)
• Tool steps: use with: for arguments, on_success/on_failure for routing
• Terminal steps: have action: stop and a message:
• Routing targets: must reference other step names defined in the same file
• Variable substitution: use ${{ inputs.var_name }} for declared inputs and ${{ context.var_name }} for values captured by preceding steps
• Retry blocks: optional, specify max_attempts, on (condition field), on_exhausted (step name)
• Summary: one line, use > to chain steps (e.g., "plan > verify > implement > test > merge")

Complete Schema Reference

Top-Level Fields

Field	Required	Type	Notes
name	Yes	string	Unique identifier; validation fails if empty
autoskillit_version	No	string	Package version that generated this script. Set from kitchen_status.package_version. Used by migration system to detect outdated scripts.
description	Yes	string	Human-readable, shown in listings
summary	Yes	string	Pipeline chain shown in list_recipes output
inputs	No	mapping	Omit if the script has no configurable values
kitchen_rules	Yes	list[str]	Orchestrator discipline rules. Must enumerate forbidden native tools (Read, Grep, Glob, Edit, Write, Bash, Task, Explore, WebFetch, WebSearch, NotebookEdit).
steps	Yes	mapping	At least one step required

Input Fields

Field	Required	Default	Notes
description	No	""	What this input is for
required	No	false	Whether the agent must prompt for it
default	No	null	Value used when not provided

Tool Step Fields

Field	Required	Notes
tool	Yes (xor action)	MCP tool name (see Tool Reference below)
with	No	Arguments passed to the tool; values support ${{ inputs.X }} and ${{ context.X }}
on_success	No	Step name to route to on success, or "done"
on_failure	No	Step name to route to on failure
capture	No	Map of context_var → ${{ result.field }} expressions. Captured values available to later steps via ${{ context.var }}
retry	No	Retry block (see below)
note	No	Human-readable annotation for the agent; not executed

Terminal Step Fields

Field	Required	Notes
action	Yes (xor tool)	Must be "stop"
message	Yes	Displayed to the agent when this step is reached

Retry Block Fields

Field	Default	Notes
max_attempts	3	How many times to retry before giving up
on	null	Response field to check. Valid values: exit_code, is_error, needs_retry, result, retry_reason, session_id, subtype
on_exhausted	"escalate"	Step name to jump to when retries run out

Capture Field

Extracts values from tool results into a pipeline-scoped context dict. Subsequent steps reference captured values via ${{ context.var_name }}.

Field	Type	Notes
capture	mapping	Keys are context variable names; values must be ${{ result.field }} expressions

Rules:

• Values must contain ${{ result.* }} expressions (literals and other namespaces are rejected)
• Dotted result paths are valid (e.g., ${{ result.data.path }})
• Captured variables become available to steps that appear after the capturing step
• A step cannot reference its own capture — only preceding steps' captures

Example:

steps:
  implement:
    tool: run_skill
    with:
      skill_command: "/autoskillit:implement-worktree-no-merge ${{ context.plan_path }}"
      cwd: "."
    capture:
      worktree_path: "${{ result.worktree_path }}"
    on_success: test
  test:
    tool: test_check
    with:
      worktree_path: "${{ context.worktree_path }}"

Validation Rules

The system validates scripts against these rules:

1. name must be non-empty
2. steps must contain at least one step
3. Each step must have exactly one of tool or action (not both, not neither)
4. Terminal steps (action: stop) must have a message
5. on_success and on_failure targets must reference a step name defined in the file, or the literal "done"
6. retry.on_exhausted must reference a defined step name
7. retry.on must be one of the valid response fields listed above
8. All ${{ inputs.X }} references must match a declared input name
9. capture values must contain ${{ result.* }} expressions
10. capture values must only use the result.* namespace
11. ${{ context.X }} references must point to a variable captured by a preceding step
12. run_skill steps should have a capture: block to explicitly wire outputs (warning: IMPLICIT_HANDOFF)
13. All captured variables should be consumed by at least one reachable downstream step via ${{ context.X }} (warning: DEAD_OUTPUT)

MCP Tool Reference

Available tools for use in tool: fields:

Tool	Arguments (with:)	Purpose
run_skill	skill_command, cwd, model (optional), step_name (optional)	Run a Claude Code headless session with a skill
test_check	worktree_path	Run test suite, returns PASS/FAIL
merge_worktree	worktree_path, base_branch	Merge after test gate
reset_test_dir	test_dir, force (optional, default false)	Clear test directory (requires reset guard marker)
classify_fix	worktree_path, base_branch	Analyze diff for restart scope (full vs partial)
reset_workspace	test_dir	Reset workspace, preserving configured directories
run_cmd	cmd, cwd, timeout (optional)	Execute arbitrary shell command
validate_recipe	script_path	Validate a script file against the workflow schema

Bundled AutoSkillit Skills

These skills ship with the autoskillit plugin and are invoked as /autoskillit:<name>:

analyze-prs, arch-lens-c4-container, arch-lens-concurrency, arch-lens-data-lineage, arch-lens-deployment, arch-lens-development, arch-lens-error-resilience, arch-lens-module-dependency, arch-lens-operational, arch-lens-process-flow, arch-lens-repository-access, arch-lens-scenarios, arch-lens-security, arch-lens-state-lifecycle, audit-arch, audit-bugs, audit-claims, audit-cohesion, audit-defense-standards, audit-docs, audit-feature-gates, audit-friction, audit-impl, audit-review-decisions, audit-tests, build-execution-map, bundle-local-report, close-kitchen, collapse-issues, compose-pr, compose-research-pr, design-guards, diagnose-ci, dry-walkthrough, elaborate-phase, enrich-issues, exp-lens-benchmark-representativeness, exp-lens-causal-assumptions, exp-lens-comparator-construction, exp-lens-error-budget, exp-lens-estimand-clarity, exp-lens-exploratory-confirmatory, exp-lens-fair-comparison, exp-lens-governance-risk, exp-lens-iterative-learning, exp-lens-measurement-validity, exp-lens-pipeline-integrity, exp-lens-randomization-blocking, exp-lens-reproducibility-artifacts, exp-lens-sensitivity-robustness, exp-lens-severity-testing, exp-lens-unit-interference, exp-lens-validity-threats, exp-lens-variance-stability, implement-experiment, implement-worktree, implement-worktree-no-merge, investigate, issue-splitter, make-arch-diag, make-campaign, make-experiment-diag, make-groups, make-plan, make-req, merge-pr, mermaid, migrate-recipes, open-integration-pr, open-kitchen, pipeline-summary, plan-experiment, plan-visualization, planner-analyze, planner-assess-review-approach, planner-consolidate-wps, planner-elaborate-assignments, planner-elaborate-phase, planner-elaborate-wps, planner-extract-domain, planner-generate-phases, planner-reconcile-deps, planner-refine, planner-refine-assignments, planner-refine-phases, planner-refine-wps, planner-validate-task-alignment, prepare-issue, prepare-pr, prepare-research-pr, process-issues, promote-to-main, rectify, reload-session, report-bug, resolve-claims-review, resolve-design-review, resolve-failures, resolve-merge-conflicts, resolve-research-review, resolve-review, retry-worktree, review-approach, review-design, review-pr, review-research-pr, run-experiment, scope, setup-environment, setup-project, smoke-task, stage-data, triage-issues, troubleshoot-experiment, validate-audit, validate-review-decisions, validate-test-audit, verify-diag, vis-lens-always-on, vis-lens-antipattern, vis-lens-caption-annot, vis-lens-chart-select, vis-lens-color-access, vis-lens-methodology-norms, vis-lens-figure-table, vis-lens-multi-compare, vis-lens-reproducibility, vis-lens-story-arc, vis-lens-temporal, vis-lens-uncertainty, generate-report, write-recipe

Skill Reference Disambiguation

When the user describes a workflow using bare skill names (e.g., "use make-plan", "then run investigate"), you MUST resolve each name before writing it into the YAML.

Resolution procedure

For each bare skill name the user mentions:

1. Check local: Does .claude/skills/<name>/SKILL.md exist in the project directory?
2. Check bundled: Is <name> in the Bundled AutoSkillit Skills list above?
3. Resolve:
   • Local only → use /<name> (bare slash command)
   • Bundled only → use /autoskillit:<name>
   • Both exist → prompt the user:

     "I see <name> exists as both a local project skill (/<name>) and a bundled AutoSkillit skill (/autoskillit:<name>). Which should this script use? The local version is recommended since it's tailored to your project."

   • Neither exists → warn the user that the skill wasn't found and ask them to clarify the correct name or path

Defaults

• Local always takes priority when the user doesn't express a preference.
• Only prompt when both sources provide the same name. Don't prompt for names that exist in only one source.

Example: Standard Implementation Pipeline

This is the reference format. All generated scripts should match this style:

name: implementation
description: Plan, verify, implement, test, and merge a task.
summary: make-plan > dry-walk > implement > test > merge

kitchen_rules:
  - "NEVER use native Claude Code tools (Read, Grep, Glob, Edit, Write,
    Bash, Task, Explore, WebFetch, WebSearch, NotebookEdit) from the
    orchestrator. All work is delegated through run_skill."
  - "Route to on_failure when a step fails — do not investigate directly."

ingredients:
  task:
    description: What to implement
    required: true
  project_dir:
    description: Path to the project
    required: true
  work_dir:
    description: Working directory (can be same as project_dir)
    default: "."
  base_branch:
    description: Branch to merge into
    default: develop

steps:
  plan:
    tool: run_skill
    with:
      skill_command: "/autoskillit:make-plan ${{ inputs.task }}"
      cwd: "${{ inputs.work_dir }}"
    capture:
      plan_path: "${{ result.plan_path }}"
    on_success: verify
    on_failure: escalate
  verify:
    tool: run_skill
    with:
      skill_command: "/autoskillit:dry-walkthrough ${{ context.plan_path }}"
      cwd: "${{ inputs.work_dir }}"
    on_success: implement
    on_failure: escalate
  implement:
    tool: run_skill
    with:
      skill_command: "/autoskillit:implement-worktree-no-merge ${{ context.plan_path }}"
      cwd: "${{ inputs.work_dir }}"
    capture:
      worktree_path: "${{ result.worktree_path }}"
    retries: 0
    on_context_limit: retry_worktree
    on_success: test
    on_failure: escalate
  retry_worktree:
    tool: run_skill
    with:
      skill_command: "/autoskillit:retry-worktree ${{ context.plan_path }} ${{ context.worktree_path }}"
      cwd: "${{ context.worktree_path }}"
    on_success: test
    on_failure: escalate
  test:
    tool: test_check
    with:
      worktree_path: "${{ context.worktree_path }}"
    on_success: merge
    on_failure: fix
  merge:
    tool: merge_worktree
    with:
      worktree_path: "${{ context.worktree_path }}"
      base_branch: "${{ inputs.base_branch }}"
    on_success: done
    on_failure: escalate
  fix:
    tool: run_skill
    with:
      skill_command: "/autoskillit:resolve-failures ${{ context.worktree_path }} ${{ context.plan_path }} ${{ inputs.base_branch }}"
      cwd: "${{ inputs.work_dir }}"
    on_success: done
    on_failure: escalate
  done:
    action: stop
    message: "Implementation complete."
  escalate:
    action: stop
    message: "Failed — human intervention needed."

Example: Loop with Fix Step

A condensed bugfix loop showing retry, classify, and routing patterns:

name: example-loop
description: Test, fix, and merge with automatic retry.
summary: test > investigate > plan > implement > verify > merge

kitchen_rules:
  - "NEVER use native Claude Code tools (Read, Grep, Glob, Edit, Write,
    Bash, Task, Explore, WebFetch, WebSearch, NotebookEdit) from the
    orchestrator. All work is delegated through run_skill."
  - "Route to on_failure when a step fails — do not investigate directly."

ingredients:
  test_dir:
    description: Directory containing the project to test
    required: true
  base_branch:
    description: Branch to merge fixes into
    default: develop
  helper_dir:
    description: Directory for helper agent sessions
    required: true

steps:
  test:
    tool: test_check
    with:
      worktree_path: "${{ inputs.test_dir }}"
    on_success: done
    on_failure: investigate

  investigate:
    tool: run_skill
    with:
      skill_command: "/autoskillit:investigate the test failures"
      cwd: "${{ inputs.helper_dir }}"
    on_success: plan
    on_failure: escalate

  plan:
    tool: run_skill
    with:
      skill_command: "/autoskillit:rectify the investigation findings"
      cwd: "${{ inputs.helper_dir }}"
    capture:
      plan_path: "${{ result.plan_path }}"
    on_success: implement
    on_failure: escalate

  implement:
    tool: run_skill
    with:
      skill_command: "/autoskillit:implement-worktree-no-merge ${{ context.plan_path }}"
      cwd: "${{ inputs.helper_dir }}"
    retries: 0
    on_context_limit: escalate
    on_success: verify
    on_failure: escalate

  verify:
    tool: test_check
    with:
      worktree_path: "${{ inputs.test_dir }}"
    on_success: merge
    on_failure: classify
    note: Re-test after implementation. If still failing, classify the fix scope.

  classify:
    tool: classify_fix
    with:
      worktree_path: "${{ inputs.test_dir }}"
      base_branch: "${{ inputs.base_branch }}"
    note: If full_restart, go back to investigate. If partial_restart, go back to implement.
    on_success: merge
    on_failure: escalate

  merge:
    tool: merge_worktree
    with:
      worktree_path: "${{ inputs.test_dir }}"
      base_branch: "${{ inputs.base_branch }}"
    on_success: done
    on_failure: escalate

  done:
    action: stop
    message: "All tests passing. Fix merged successfully."

  escalate:
    action: stop
    message: "Human intervention needed. Review the latest output for details."

Converting Legacy Markdown Commands to YAML

When converting old .claude/commands/ or .claude/skills/ Markdown recipes to YAML:

Mapping Table

Markdown Pattern	YAML Equivalent
SETUP: block with var = value	inputs: block with description, required, default
Hardcoded paths in SETUP	required: true inputs (never hardcode paths)
PIPELINE: numbered steps	steps: keyed by descriptive name
run_skill("/skill-name ...", cwd=...)	tool: run_skill with with: {skill_command: "...", cwd: "..."}
run_skill(...) with retry	tool: run_skill with retries: field
→ ESCALATE / prose failure routing	on_failure: escalate
PASS → next step	on_success: next_step
FAIL → fix attempt	on_failure: fix
Repeat up to 3x, then ESCALATE	retry: {max_attempts: 3, on: needs_retry, on_exhausted: escalate}
IF condition: branching	Multiple steps with on_success/on_failure routing
FOR each part: loops	Not representable in YAML schema — add a note: explaining the loop for the agent
Prose Notes: section	note: field on individual steps, or comments in YAML
AskUserQuestion prompts	Not in schema — the agent handles prompting before executing the script
review_approach = false (optional)	Input with required: false and default: "false"
Local skill refs (bare skill-name)	Follow the Skill Reference Disambiguation procedure above to resolve

What Cannot Be Directly Represented

Some Markdown patterns require agent interpretation rather than YAML structure:

• Multi-part plan loops (FOR each plan_part): Add a note: to the implement step explaining that the agent should glob for plan parts and iterate
• Conditional steps (IF review_approach == true): Use an input with a default and add a note: explaining the conditional

Conversion Checklist

1. Extract inputs from SETUP: block — remove hardcoded paths, make them required: true
2. Map each numbered pipeline step to a named YAML step
3. Resolve skill references — for each skill name, follow the Skill Reference Disambiguation procedure
4. Identify which MCP tool each step calls (see Tool Reference above)
5. Set on_success / on_failure routing for every tool step
6. Add retry: blocks where the Markdown says "repeat" or "retry"
7. Add terminal done and escalate steps
8. Write a summary: line capturing the pipeline chain
9. Add note: fields for agent-interpreted logic (loops, conditionals)

Standalone Invocation Flow

When called directly as /autoskillit:write-recipe:

1. Ask the user what workflow they want to script (name, what it does)
2. Ask whether it's a linear pipeline or a loop with a fix step
3. Ask for the tool calls and routing (which MCP tools, what order, what conditions)
4. Ask for inputs (what's configurable)
5. Generate the script in the YAML format above
6. Before saving, call kitchen_status to get package_version and stamp autoskillit_version: "{package_version}" as the second top-level field (after name). This is required for the migration system to track script age.
7. Save to .autoskillit/recipes/{name}.yaml (create the directory if needed)
8. Call validate_recipe with the saved file path. If errors are returned, fix them and re-validate until clean. Review the quality.warnings in the response:
   • DEAD_OUTPUT: A capture: key is never referenced by any reachable downstream step via ${{ context.X }}. Either add a ${{ context.X }} reference in the downstream step's with: block, or remove the unused capture.
   • IMPLICIT_HANDOFF: A run_skill step has no capture: block. Add a capture: block to explicitly wire outputs to downstream steps via ${{ context.X }}, or confirm the skill's output is intentionally unused.
   • Present the quality summary to the user and fix any warnings that indicate broken wiring.
9. After validation passes, generate the pipeline contract file by calling generate_recipe_card on the saved script. This creates .autoskillit/recipes/contracts/{name}.yaml alongside the recipe. Use run_python with autoskillit.recipe.contracts.generate_recipe_card passing the script path and scripts directory, or rely on load_recipe which auto-generates contracts on first load.
10. Tell the user: "Saved to .autoskillit/recipes/{name}.yaml. Load it with load_recipe("{name}") via the MCP tool."

After telling the user, emit the structured output token as the very last line of your text output:

IMPORTANT: Emit the structured output tokens as literal plain text with no markdown formatting on the token names. Do not wrap token names in **bold**, *italic*, or any other markdown. The adjudicator performs a regex match on the exact token name — decorators cause match failure.

recipe_path = {absolute_path_to_saved_recipe_file}

CRITICAL: Scripts Are NOT Skills

Recipes are YAML workflow files in .autoskillit/recipes/. They are:

• Loaded via the load_recipe MCP tool
• Executed by the agent interpreting the YAML steps

They are NOT:

• Slash commands (cannot be invoked as /autoskillit:<name>)
• Stored in .autoskillit/skills/ or any other directory
• Markdown files (they are .yaml files)

Never tell the user to run a script with /autoskillit:<name>. The correct invocation is always via load_recipe("<name>").

Loaded by Another Skill

When loaded via the Skill tool by another skill (e.g., setup-project), the calling agent already has all the workflow context in its conversation. Use that context directly:

• Workflow name and description are already known
• Tool calls and routing are already determined
• Inputs are already identified

Apply the format rules above to produce the YAML script. Do not re-ask for information the calling agent has already gathered.

Edit Mode (Loaded with Existing Script Content)

When the agent is given an existing script's YAML content and a requested change:

1. Parse the existing YAML to understand the current structure
2. Apply the requested modifications while preserving all existing fields
3. Resolve any skill references per the disambiguation procedure
4. Write the modified YAML to the target path — ask the user whether to:
   • Save changes to the original file
   • Save as a new script (prompt for name)
   • Use temporarily without saving
5. Call validate_recipe on the saved path
6. If errors, fix and re-validate until clean
7. Review quality warnings and fix data-flow issues before reporting changes
8. After validation passes, regenerate the pipeline contract file to reflect the changes. Use run_python with autoskillit.recipe.contracts.generate_recipe_card or rely on load_recipe auto-generation on next load.
9. Report the changes made

This edit mode is invoked when load_recipe routes the user's modification request through this skill. The skill receives the existing YAML as context.