| name | profile-5-recipes |
| description | Extract usage recipes and step-by-step configuration tasks from an LCC node's CDI XML and PDF manual. Keywords -- CDI, recipe, configuration, howto, step-by-step, wiring, setup, profile extraction. |
Extract Usage Recipes
Identify common configuration tasks described in the node's manual and produce structured recipes — each listing the fields to set, the values to use, and why each setting is needed.
When to Use
Use this skill when you need to create step-by-step configuration guides for common real-world tasks (e.g., "Configure a push button input", "Set up a blinking LED output"). These recipes populate the guided configuration panel. This is typically the fifth and final extraction step when building a node profile.
Required Inputs
- manual-outline.json — the structured index produced by
profile-0-manual-outline. Contains cdiFile (path to CDI XML), pdfFile (path to PDF manual), and topics that identify pages with examples/recipes.
- event-roles.json — from
profile-1-event-roles (optional but recommended). Helps recipes correctly reference producer vs consumer events.
- relevance-rules.json — from
profile-2-relevance-rules (optional but recommended). Helps recipes avoid configuring sections that would be irrelevant for the task.
- section-descriptions.json — from
profile-3-section-descriptions (optional but recommended). Provides context about what each section does.
- field-descriptions.json — from
profile-4-field-descriptions (optional but recommended). Provides field-level detail including valid options and their meanings.
No other file paths needed — read the CDI XML and PDF file paths from manual-outline.json, then use the pdf-utilities read_pdf tool with pageRange parameter to extract pages with "example", "recipe", "step-by-step", or "howto" topics (identified in the outline).
Task
Identify every common configuration task described in the manual. For each task, produce a structured recipe that lists the fields to set, the values to use, and why each setting is needed.
What to Look For
- Step-by-step configuration examples in the manual
- Wiring diagrams that correspond to specific field settings
- "How to" or "Getting Started" sections
- Common use cases mentioned in section introductions (e.g., "To configure a push button...", "For a blinking LED output...")
- Tables that show recommended settings for different scenarios
- Conditional logic examples (timer setups, AND/OR conditions)
Output Format
Produce a YAML file with embedded Markdown text. The file should be saved as recipes.yaml in your profile directory.
nodeType:
manufacturer: "RR-CirKits"
model: "Tower-LCC"
recipes:
- name: "Push Button Input"
scope: "Port I/O/Line"
description: |
Configure a physical push-button switch to send an event when pressed.
This is the foundation for operator controls and sensor inputs.
prerequisites: |
* Wire a normally-open push button to a digital input pin (lines 0–15)
* Ground the other side of the button, or wire to +5V depending on desired polarity
steps:
- order: 1
field: "Port I/O/Line/Input Function"
value: "Active Hi"
rawValue: 1
rationale: |
Enables the input to read the button state. "Active Hi" means the line reads
high (1) when pressed, low (0) when released. Choose based on your wiring polarity.
- order: 2
field: "Port I/O/Line/Event[0]/Command"
value: "<copy your desired EventID from the Node ID section>"
rawValue: null
rationale: |
Assign the event that fires when the button is pressed. This event can trigger
other nodes or conditionals. Copy the EventID from your node's ID assignment.
- order: 3
field: "Port I/O/Line/Event[0]/Action"
Guidelines
- Each recipe should be a complete, self-contained set of steps — a user following them should achieve the described result
description, prerequisites, and rationale fields support Markdown — use **bold** for emphasis, *italic* for alternatives, and bullet lists for multi-step requirements- Field paths must reference actual fields in the CDI XML
- For enum fields,
value is the human-readable label and rawValue is the integer <property> value from the CDI <map>
- For non-enum fields,
rawValue can be null
- Steps should be ordered logically (set the mode first, then configure events, then timing)
- Include at least the physical/wiring prerequisites if the manual mentions them
- Prioritize the most common use cases — aim for 3–5 recipes for the main I/O segment, 1–2 for conditional logic if applicable
- If relevance-rules.json is available, ensure recipes don't include steps for sections that would be irrelevant given the recipe's own settings
- If field-descriptions.json is available, use it to verify field paths and option values are correct
Important
- All field paths and enum values must exist in the CDI XML — do not reference fields or values that aren't in the CDI
- Recipes describe what to configure and why — they do NOT auto-fill values. The user makes the changes guided by the recipe
- Write for model railroad hobbyists — avoid protocol jargon
- YAML formatting: Use
| for multiline text (descriptions, prerequisites, rationales). Use - for bullet lists within these fields (supports Markdown). Preserve indentation for readability.
Verifying paths and enum values as you draft
While drafting, you can spot-check any field path or enum rawValue against the CDI without waiting for profile-6:
uv run .github/skills/_lib/profile_tools.py check profile-extractions/<node-name> "<cdiPath>" [--value N]
The command prints the resolved node's kind, children, and enum map, and (with --value) confirms the integer is in the map. Run profile-6-validate once you're done drafting to cross-check every step in bulk.
Output File
Save the output as profile-extractions/<node-name>/recipes.yaml (e.g., profile-extractions/tower-lcc/recipes.yaml). The .yaml extension enables easy rendering of Markdown content in the UX.
