You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .claude/skills/render-recipe/SKILL.md
+61-76Lines changed: 61 additions & 76 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,7 +18,10 @@ Produce a compact, structured overview of an AutoSkillit recipe. Reads the recip
18
18
- Modify any source code or recipe files
19
19
- Invent steps, ingredients, or routing not in the YAML
20
20
- Add decorative flair, emoji, or unnecessary commentary
21
-
- Create files outside `temp/render-recipe/`
21
+
- Create files outside `temp/render-recipe/` and `recipes/diagrams/`
22
+
- Use Unicode characters, emoji, or non-ASCII symbols. ASCII only — use `*` for pass, `x` for fail, `?` for confirm, `|` for spine, `+` for joins. No box-drawing characters, no arrows like `→` or `↑`, no check marks, no crosses. Write `->` and `(up)` instead.
23
+
- Include HTML comments, hash markers, format version markers, or any metadata in the output. No `<!-- ... -->` lines.
24
+
- Include "Agent-managed" lines listing internal context variables. The user doesn't need to see plumbing state.
22
25
23
26
**ALWAYS:**
24
27
- Read the recipe YAML carefully and render exactly what exists
@@ -29,67 +32,77 @@ Produce a compact, structured overview of an AutoSkillit recipe. Reads the recip
29
32
30
33
## Rendering Specification
31
34
32
-
The output has exactly three sections. Follow this structure precisely.
35
+
The output has exactly two sections. Follow this structure precisely.
36
+
37
+
**Note:** The inputs table is NOT part of the diagram output. It is generated at runtime from the recipe YAML by `_format_ingredients_table` (single source of truth). Do not include an inputs table in the diagram file.
33
38
34
39
### Section 1: Header
35
40
36
41
```
37
42
## {name}
38
-
{description}
39
43
```
40
44
45
+
Just the name. No description — the user already chose the recipe from the picker.
46
+
41
47
### Section 2: Flow Diagram
42
48
43
49
Build an ASCII flow diagram showing the step graph. This is the core visual.
44
50
45
51
**Infrastructure steps to hide:**
46
-
Steps whose sole purpose is capturing a value via `run_cmd` (e.g., `capture_base_sha`, `set_merge_target`, shell one-liners that just `printf` or `git rev-parse`) should be **omitted** from the diagram. They are plumbing — the user does not need to see them. If in doubt: if a step uses `run_cmd` and its `note:` describes it as capturing/setting a value, hide it.
52
+
The diagram shows ONLY the *skill work* — `run_skill` invocations and `test_check`. Everything else is plumbing. Hide:
53
+
-**All `run_cmd` steps** — value capture, shell one-liners, branch computation. All plumbing.
-**All `action: route` steps** — pure routing nodes with no work.
63
+
64
+
If a hidden step is the *only* path between two visible steps, collapse the route — just connect the visible steps directly. The reader should see: "what skills run, in what order, and what happens on failure."
47
65
48
66
**Diagram layout:**
49
67
50
-
Use a vertical spine with `├──`branches. The structure reads top-to-bottom:
68
+
Use a vertical spine with `|` and `+--`branches. ASCII only — no Unicode.
51
69
52
70
1.**Main flow** runs down the left spine. Show meaningful steps in order.
53
-
2.**Optional steps**are shown in brackets `[step-name]` with a right-side annotation: `← only if {condition}`.
54
-
3.**Iteration loops** are wrapped in a `FOR EACH` block using box-drawing characters (`┌────┤` / `└────┘`). Only use this when `note:` fields indicate iteration over plan_parts or groups.
55
-
4.**Failure branches**are shown inline where they diverge: `fix ───┘ (on failure)`.
71
+
2.**Optional steps**always go on their own `+--` branch off the vertical spine: `+-- [step-name] (optional)`. They are never inlined on a horizontal chain. Never repeat the step name outside the brackets.
72
+
3.**Iteration loops** are wrapped in a `FOR EACH` block using `+----+` / `+----+`. Only use this when `note:` fields indicate iteration over plan_parts or groups.
73
+
4.**Self-loops**go on the same line with a bidirectional arrow: `step <-> [x fail -> handler]`.
56
74
5.**Multi-way routing** (`on_result`) is shown with labeled paths on separate lines.
57
-
6.**Retry blocks** are noted parenthetically on the step: `(retry ×N)`. Use `×∞` for `max_attempts: 0`.
58
-
7.**Back-edges** use `↑` suffix: `→ verify↑`, `→ plan↑`.
59
-
8.**Terminal steps** go at the bottom after a separator line.
60
-
9. Do **not** show model annotations (e.g., `[sonnet]`) in the diagram.
75
+
6.**Back-edges** use brackets: `-> plan [-> dry_walkthrough]`.
76
+
7.**Terminal steps** are omitted. The last visible step is the end of the diagram.
77
+
8. Do **not** show retry counts, model annotations, or other per-step metadata.
78
+
9.**`test_check` steps** display as `test`.
79
+
10.**Use the skill name, not the step key** for `run_skill` steps. But apply these short display names:
80
+
-`implement-worktree-no-merge` -> `implement`
81
+
-`audit-impl` -> `audit`
82
+
-`resolve-failures` -> `fix`
83
+
-`open-integration-pr` -> `open-pr`
84
+
- Everything else: use the skill name as-is (e.g., `make-plan`, `dry-walkthrough`, `rectify`)
85
+
11.**FOR EACH loop routing** (more parts? / all done?) is implicit — omit it. The loop block itself conveys iteration. The first step inside the loop connects directly to the `+----+` box — no extra `|` line needed between them.
86
+
12.**Context limit recovery** (`retry_worktree`, `on_context_limit`) is automatic plumbing — omit it.
87
+
13.**Consistent failure language.** Always use `x fail` for failure branches. Never use "NO GO", "FAIL", "failure", or other variants.
88
+
14.**Back-edge targets must be the actual destination, not an intermediate optional step.** When a back-edge (e.g. audit fail) routes to a step that then passes through an optional step before reaching the real target, show the back-edge pointing to the real target directly. Example: if audit fail routes to `make_plan` and `make_plan.on_success` is `dry_walkthrough`, show `x fail [-> make-plan]` with the arrow going to `make-plan`, not to `review-approach`. The optional step is only reachable from its primary path, not from back-edges that happen to pass through the same chain.
89
+
15.**Center step names on the vertical spine.** When a step name appears on the main spine (not on a branch), center the text relative to the `|` character column. All spine-level step names should align to the same visual center.
61
90
62
91
**Reference example for implementation:**
63
92
64
93
```
65
-
clone
66
-
│
67
-
├── [create_branch] ← only if open_pr=true
68
-
│
69
-
├── [group] ← only if make_groups=true
70
-
│
71
-
┌────┤ FOR EACH GROUP:
72
-
│ │
73
-
│ plan ─── [review] ─── verify ─── implement (retry ×∞) ─── test ─── merge ─── push
@@ -98,33 +111,6 @@ Use a vertical spine with `├──` branches. The structure reads top-to-botto
98
111
- Very simple recipes (under 8 meaningful steps) can use a single horizontal chain.
99
112
- Always adapt the shape to the recipe — do not force a complex layout on a simple recipe.
100
113
101
-
### Section 3: Inputs Table
102
-
103
-
Render all ingredients as a single Markdown table.
104
-
105
-
```
106
-
### Inputs
107
-
108
-
| Name | Description | Default |
109
-
|------|-------------|---------|
110
-
| task | What to implement | — |
111
-
| source_dir | Repository path | auto-detect |
112
-
| base_branch | Merge target | main |
113
-
| run_name | Run name prefix | impl |
114
-
| make_groups | Decompose into groups | off |
115
-
| review_approach | Research first | off |
116
-
| audit | Post-merge audit | on |
117
-
| open_pr | PR instead of direct merge | off |
118
-
```
119
-
120
-
**Rules:**
121
-
- Keep descriptions short — one phrase, not a sentence.
122
-
- Show `—` for no default (required inputs).
123
-
- Show `off`/`on` for boolean-like flags with `"false"`/`"true"` defaults.
124
-
- Show `auto-detect` for empty-string defaults that auto-resolve.
125
-
- If an ingredient is conditionally required (e.g., `task` required when `make_groups=false`), note it parenthetically: "What to implement (when no groups)".
126
-
- Omit agent-managed state (ingredients with no default that are populated by step captures). If any exist, add a brief line below the table: `Agent-managed: work_dir, worktree_path, plan_path, ...`
127
-
128
114
---
129
115
130
116
## Workflow
@@ -134,12 +120,11 @@ Render all ingredients as a single Markdown table.
134
120
Read the recipe YAML from the prompt context or from disk if a path is given. Identify:
135
121
- All ingredients and their properties
136
122
- All steps in declaration order
137
-
- Infrastructure steps to hide (run_cmd steps that just capture values)
123
+
- Infrastructure steps to hide (see expanded list in Section 2)
138
124
- The happy path (follow on_success chain from first step)
139
125
- Branch points (on_failure to non-terminal, on_result routing)
140
126
- Back-edges (on_success/on_failure targets that appear earlier in declaration order)
141
127
- Optional steps (optional: true)
142
-
- Retry blocks
143
128
- Terminal steps (action: stop)
144
129
145
130
### Step 2: Build the Flow Diagram
@@ -157,19 +142,19 @@ Before writing, check the diagram for alignment errors. Scan every line and veri
157
142
158
143
If any check fails, fix the diagram before proceeding. This is a mechanical check — count character positions, do not eyeball it.
159
144
160
-
### Step 4: Build the Inputs Table
161
-
162
-
Construct the table following the rules in Section 3.
145
+
### Step 4: Assemble and Write
163
146
164
-
### Step 5: Assemble and Write
147
+
Combine both sections and write to two locations:
148
+
1.`temp/render-recipe/{recipe-name}_{YYYY-MM-DD_HHMMSS}.md` — timestamped history copy
149
+
2. The recipe's diagram file — for bundled recipes: `src/autoskillit/recipes/diagrams/{recipe-name}.md`; for project recipes: `.autoskillit/recipes/diagrams/{recipe-name}.md`. This is the file that `load_recipe` serves to Claude.
165
150
166
-
Combine all three sections. Write to `temp/render-recipe/{recipe-name}_{YYYY-MM-DD_HHMMSS}.md` (timestamp ensures no overwrites). Print the full content to terminal.
151
+
Print the full content to terminal.
167
152
168
153
---
169
154
170
155
## Output Rules
171
156
172
157
| Content | Destination |
173
158
|---------|-------------|
174
-
| Rendered recipe overview |`temp/render-recipe/{recipe-name}_{YYYY-MM-DD_HHMMSS}.md` AND terminal |
175
-
| Validation warnings (if any) | Terminal only, as a brief note after the render|
0 commit comments