Initialize Target Platform

Overview

This skill authors a new target-platform profile YAML — the write-side of the contract in ../../context/target-platform-contract.md. It uses ../../references/bsp-platforms-catalogue.md as the canonical product / flash-config catalogue and ../../references/platform_template.yaml as the field schema.

Flow is linear: pick a reference product + flash config, then optionally add custom-carrier details. The two contract cases — reference-only vs reference + custom carrier — are distinguished only by whether the user provides custom-carrier details; there is no up-front mode prompt.

Scope is reference_devkit: and custom_carrier: only. Sibling skills own the other blocks: bsp_image: → jetson-init-image; source: → jetson-init-source; documents: → jetson-link-docs.

Outputs: a new target-platform/<name>.yaml and (by default) an updated active_target.yml pointing at it. To switch among already-authored profiles, use sibling jetson-set-target.

When to invoke

• The user asks to create / author / add a new target platform profile.
• A downstream skill refused with "no active target" and

target-platform/ contains no profile YAML files yet (otherwise prefer jetson-set-target).

• The user wants a target whose profile does not yet exist on disk.

Procedure

Quick-start prefill mapping

Follow the shared quick_start_prefill contract. This skill consumes:

• quick_start_prefill.target.active_platform as the selected catalogue

row when it resolves to exactly one product.

• quick_start_prefill.target.custom_carrier as the custom-carrier

intent.

If active_platform resolves to one catalogue row, use it directly. Do not re-ask reference-product or flash-config questions; use the row's default flash config unless the prefill names a catalogue variant. Ask only when the prefill is missing, invalid, ambiguous, or names an unknown variant.

How the skill consumes the template

Load ../../references/platform_template.yaml once at skill startup and treat it as the schema for prompted blocks. Each placeholder value carries one of three sentinel markers:

| Marker | Behavior | |---|---| | <REQUIRED: description> | Prompt the user. Value must be provided; NA is accepted with a warning that downstream skills may refuse. | | <OPTIONAL: description> | Prompt the user. Value may be skipped (Enter or NA); skipped fields are omitted from the written profile (no empty key, no NA placeholder). | | <DERIVED: description> | Filled programmatically from bsp-platforms-catalogue.md and the user's product / flash-config choice in the "Pick the reference product" and "Pick the flash config" steps. Not prompted. |

Use the marker description as the prompt text verbatim. Match markers with the regex ^<(REQUIRED|OPTIONAL|DERIVED):\s*(.*)>$ after YAML parsing strips the surrounding quotes.

Block-level inclusion (custom_carrier) is decided by the skill flow, not by markers — adding/removing fields inside a block is a template-only change.

Survey current state

1. If target-platform/ does not exist, create it and copy

../../references/active_target_template.yaml to target-platform/active_target.yml (note .yml extension).

1. Read target-platform/active_target.yml.
2. List target-platform/*.yaml (excluding active_target.yml).

| Situation | Action | |---|---| | No profile YAMLs exist | Proceed — this is the bootstrap case. The new profile will be set as active_target automatically in the "Write" step (no activation prompt in the "Confirm" step). | | Profiles exist, active: NA | Show the list of existing profiles and confirm the user wants to author a new one (rather than activate one of the existing profiles via jetson-set-target). | | Profiles exist, active: names a present file | Show the active profile and the full list. Ask whether the user wants to (a) author a new profile alongside, or (b) switch to one of the existing profiles via jetson-set-target. If (b), stop and tell the user to run jetson-set-target. | | active: names a missing file | Tell the user the pointer is broken; offer to author a new profile (and replace the pointer) or to fix the pointer manually. |

Read the platforms catalogue

Read ../../references/bsp-platforms-catalogue.md. Parse the "Product / Chip / SKU / Flash Config Mapping" table — that is the source of truth for product names, CVM/CVB SKUs, default flash confs, and variant suffixes. Do not scan Linux_for_Tegra/*.conf or parse conf filenames; the catalogue already collapses that.

Pick the reference product (baseline)

Print the full catalogue list before asking. Group rows by chip family and number every entry with stable indexes for this run. Build the list only from bsp-platforms-catalogue.md; do not copy platform rows from examples or other docs.

Build explicit shortcut choices from the printed list by taking the first row in each chip-family group. Each shortcut label must include the full-list index and product name, for example Index 1 — Jetson AGX Orin 64GB. Do not hard-code product names; derive shortcuts from the parsed catalogue rows. These shortcuts are the only explicit choices for this question. Manual index entry must use the tool's built-in Type something input; do not add a third custom choice for manual entry.

Prompt text:

> Pick a platform shortcut, or choose Type something and type the numeric > index from the full platform list printed above. If your hardware is a > custom carrier with one of these Jetson modules, pick the closest > matching reference devkit as the baseline. Type cancel to cancel this > run.

Do not show chip-family choices such as T234 / Orin family or T264 / Thor family. Do not show Type index, Manual entry, Other platform, or any custom manual-entry choice. The only manual-entry path is the tool-provided Type something row. Do not add Other as a choice or paraphrase Type something as Other in prompt text. Do not accept product-name substring matches in this step; typed input must be a numeric index from the printed full list or cancel. skip is not allowed because this skill cannot author a target profile without a reference platform.

Resolve the shortcut or typed index to exactly one catalogue row. If the typed index is out of range or invalid, show the valid index range and ask again. If the user types skip, explain that jetson-init-target requires a reference platform and ask again. If the user types cancel, stop without writing a profile.

Pick the flash config

From the catalogue row, the Default flash conf is option 1; the Variants column lists suffixes — option 2..N. Reconstruct each variant's full conf filename by appending the suffix to the default conf base. If a row says (same as <other>) in the Variants column, reuse the referenced row's variant list verbatim. Build this list only from the selected catalogue row.

Prompt:

> Pick a number, or press Enter to accept the default (1).

If the chosen row has no variants (— in the catalogue), proceed to the "Optional: add custom carrier details" step with the default conf.

Edge cases:

• Raw-conf variants (catalogue marks (raw)). For Orin Nano,

-a0-maxn (raw) → p3768-0000-p3767-0000-a0-maxn.conf. Use the raw filename verbatim.

• (same as <other>) placeholders. Reuse the referenced row's

variants verbatim.

Optional: add custom carrier details

After the baseline + flash config are chosen, resolve whether the profile should record a custom carrier on top. If quick_start_prefill.target.custom_carrier is a valid concrete intent, consume it directly:

• add_custom_carrier → record custom_carrier: and collect the missing

carrier metadata below.

• no_custom_carrier → omit custom_carrier: and proceed to the

"Confirm" step.

• keep_existing_custom_carrier is valid only when editing an existing

active profile that already has custom_carrier:. Because this skill authors a new profile, treat it as ambiguous and ask the custom-carrier intent question below.

• skip or a missing prefill value → ask the custom-carrier intent

question below.

When intent is not already concrete, ask the user whether they also want to record a custom carrier on top using the AskUserQuestions UI. This is a bounded choice; show add and skip only:

> Optionally add custom-carrier details for a customer-designed carrier > using this Jetson module? (add / skip, default skip)

If the resolved intent is skip, proceed to the "Confirm" step with the custom_carrier: block omitted.

If the resolved intent is add, collect every still-missing custom_carrier: value through the AskUserQuestions UI. Do not collect custom-carrier metadata with plain-text prompts, inline chat questions, freeform summary confirmation, inferred defaults, or example values presented as selectable options. Split the collection into multiple AskUserQuestions forms if the UI question limit would otherwise be exceeded.

For the first AskUserQuestions form, ask custom_carrier.name, custom_carrier.id, custom_carrier.sku, and custom_carrier.revision in template document order. For these four fields, the only selectable path shown to the user must be the tool's built-in Type something row. Do not add example values, "Other", guessed board IDs, guessed SKUs, common revision strings, or any explicit domain options. These are customer-provided metadata: preserve them exactly as entered and do not require or validate any naming convention, prefix, case, character set, digit count, or SKU format. Validate only that required fields are non-empty unless the user explicitly enters NA. NA is accepted per the contract for required fields; warn that downstream skills may refuse if a missing field is required for their edit.

After custom_carrier.name is known, collect custom_carrier.flash_config through a second AskUserQuestions form if it is still missing. Show the suggested default as the only explicit choice and allow the built-in Type something row for a custom .conf filename. Require a non-empty filename ending in .conf; do not derive it from board ID, SKU, or any guessed convention.

Field-specific behavior (defaults / suggestions not expressible via markers alone):

• custom_carrier.flash_config — suggest a default of kebab-cased

custom_carrier.name + ".conf" (e.g. "Acme Vision X1" → acme-vision-x1.conf).

• custom_carrier.name — prompt: "Type the customer-facing custom

carrier or product name exactly as you want it recorded. No format is required." Use Type something only.

• custom_carrier.id — prompt: "Type the custom carrier board ID or

project ID exactly as you want it recorded. No format is required." Use Type something only.

• custom_carrier.sku — prompt: "Type the custom carrier SKU or variant

identifier exactly as you want it recorded. No format is required." Use Type something only; quote in the written YAML so numeric-looking values and leading zeros survive.

• custom_carrier.revision — prompt: "Type the custom carrier revision

or build identifier exactly as you want it recorded, or press Enter to omit it. No format is required." Use Type something only; omit when skipped.

If the user does not know a value, suggest reading /proc/device-tree/chosen/ids on the booted target. If genuinely unavailable, accept NA for required fields or omit optional fields.

The template intentionally omits custom_carrier.module and custom_carrier.chip_family — module identity comes from reference_devkit.module (the same physical Jetson module plugs into both carriers). Don't add them back.

Confirm

Show the proposed YAML. Shape depends on whether the user added custom-carrier details in the "Optional: add custom carrier details" step. Example: see references/ui-samples.md for the reference-only and reference + custom-carrier YAML shapes, plus the note on which sibling skill appends which block.

Suggested filename:

• Reference-only: kebab-cased product name from the selected

catalogue row, with .yaml appended. E.g. Jetson AGX Thor T5000 → jetson-agx-thor-t5000.yaml; Jetson AGX Orin 32GB → jetson-agx-orin-32gb.yaml. Do not derive the filename from flash_config; multiple products can share one default conf.

• With custom carrier: kebab-cased custom_carrier.name. E.g.

"Acme Vision X1" → acme-vision-x1.yaml.

Use the suggested filename without asking when it is unique and was generated from the selected platform or custom-carrier name. Print the filename and continue. Ask only on collision, empty generated name, ambiguous input, or explicit custom-filename request. Then handle activation:

• Bootstrap case (no profile YAMLs existed at the "Survey current state" step): do not

prompt. The new profile is the first one, so it is auto-activated in the "Write" step. Tell the user this is happening so the auto-activation is not silent.

• Profiles already exist: ask whether to activate the new

profile (default: yes). Decline only if the user is authoring multiple profiles to choose from later — they can activate any of them with jetson-set-target.

Write (and optionally activate)

1. Write target-platform/<filename>.yaml. If the file already

exists, ask before overwriting; never silently clobber.

1. Edit target-platform/active_target.yml to set

active: <filename>.yaml when either of the following holds:

• This was the bootstrap case from the "Survey current state" step (no profile YAMLs existed

before this run) — activation is automatic, regardless of any prior user input.

• Profiles already existed and the user accepted activation in

the "Confirm" step.

Preserve the header comment block; only modify the active: line. If profiles already existed and the user declined activation, leave active_target.yml untouched.

Confirm

Print a summary: profile path, active pointer (or "unchanged" if activation was declined), Tegra family (T234 / T264), whether custom_carrier: was recorded, and a reminder that downstream skills will resolve to whichever profile is active. If the user authored multiple profiles without activating, point them at jetson-set-target to pick one.

Next steps (Setup → Customize chain):

1. /jetson-init-image — extract the BSP and append bsp_image:.
2. /jetson-init-source — clone the shared repos (and optionally

override <workspace>/Source if the user wants source.root_path written into the profile).

1. /jetson-link-docs (optional) — register paths to

pre-downloaded BSP / schematic / pinmux documents in the profile's documents: block.

Then, before any customize-* skill (Customize):

1. /jetson-generate-kb — KB that customize- skills consult for

target-specific file locations.

1. /jetson-derive-carrier (custom carriers only) — materialize the

custom carrier's flash conf + supporting DTSIs from the reference devkit. Required before per-knob customize- on a custom carrier.

If a downstream skill triggered this run, tell the user to re-issue their original request; do not silently re-trigger it.

Prerequisites

• bsp-platforms-catalogue.md and platform_template.yaml reachable

via the relative paths in the References section.

• Write access to target-platform/ (and target-platform/active_target.yml

if activation is requested).

• For "what module/carrier is this?" lookups: /proc/device-tree/chosen/ids

on the booted device.

Limitations

• Owns only reference_devkit:, custom_carrier:, and the

active_target.yml pointer; refuses to write bsp_image:, source:, or documents:.

• Will not invent SKUs, module IDs, custom carrier metadata, or flash

configs — records NA or aborts when the user does not know a required value.

Troubleshooting

• User asks to switch instead of author — refuse and route to

jetson-set-target; do not re-author an existing profile.

• Catalogue row not found for the product the user named —

add the row to bsp-platforms-catalogue.md first; do not patch the product list inside this skill.

• Required field stuck at NA — downstream customize-* skills

may refuse; capture the missing value (read /proc/device-tree/chosen/ids) and rerun.

• active_target.yml lost its comment block after activation — a

non-round-tripping YAML writer was used; switch to ruamel.yaml and restore from the template.

See references/gotchas.md for the full pitfalls list (catalogue/template separation, NA handling, conf collision rules, etc.).

References

• ../../references/bsp-platforms-catalogue.md — product / flash conf catalogue (the source of truth for the "Pick the reference product" and "Pick the flash config" steps).
• ../../context/target-platform-contract.md — the contract this skill writes to.
• ../../references/platform_template.yaml — schema starter for a target profile (the source of truth for the "Optional: add custom carrier details" step).
• ../../references/active_target_template.yaml — schema starter for the active-target pointer.
• ../jetson-set-target/SKILL.md — sibling skill: switch the active pointer among already-authored profiles.
• ../jetson-init-image/SKILL.md — sibling skill: extract BSP image and author the bsp_image: block.
• ../jetson-init-source/SKILL.md — sibling skill: clone shared repos and (optionally) author the source: block.
• ../jetson-link-docs/SKILL.md — sibling skill: author the documents: block by registering pre-downloaded files.