/manage-skill-flavors

name: manage-skill-flavors
description: "Maintain build-time skill flavors in the UiPath skills repository. Use when adding or editing skill-flavor marker blocks, sparse flavor overrides, generic flavor discovery, marker-free default or custom npm packages, package inspection, flavor CI, or composer/package tests. Preserve SKILL.md as the complete default, keep overrides exceptional, and validate finished trees and tarballs."

Manage Skill Flavors

Maintain one complete canonical skill while building reviewed host-specific exceptions before packaging. Consumers receive finished files and never interpret markers.

Start With the Complete Context

1. Confirm the repository root contains `skills/`, `skill-flavors/`, and `scripts/compose-skill-flavor.mjs`. 2. Read the complete canonical file being changed. 3. Read the matching relative file under every existing `skill-flavors/<flavor>/` directory, when present. No override means that flavor intentionally inherits the canonical file. 4. Read [references/flavor-test-matrix.md](references/flavor-test-matrix.md) completely when adding a flavor or changing discovery, composition, packaging, publishing, or CI.

Classify the Change

| Change | Correct source edit | |---|---| | Behavior is valid in every host | Edit only the canonical file. | | A host capability changes one instruction | Mark the smallest complete canonical passage and add one sparse replacement block. | | An existing skill is safe unchanged for a flavor | Make no flavor edit; it is included automatically. | | A new canonical skill is added | Review it against every flavor; add sparse overrides only where canonical guidance is unsafe. | | A new flavor is added | Add its first real sparse override, or a `.canonical` pin, under `skill-flavors/<flavor>/`; generic build and CI must discover it without another registry edit. |

Do not create an exception merely to reword shared guidance.

Author the Smallest Exception

Keep the canonical `SKILL.md` or reference complete. Put standalone boundaries around only the passage that differs:

<!--skill-flavor:project-creation:start-->
Create the project with the default local workflow.
<!--skill-flavor:project-creation:end-->

Mirror the canonical path below the flavor root and write only complete replacement blocks plus whitespace:

skills/uipath-example/references/setup.md
skill-flavors/studioweb/uipath-example/references/setup.md

<!--skill-flavor:project-creation:start-->
Create the project with the host project-creation tool.
<!--skill-flavor:project-creation:end-->

Marker names must be lowercase kebab-case, unique within a file, unnested, and identical in canonical and override files. An override cannot add an unmarked introduction, heading, or note.

Use the compact marker form with no whitespace inside the HTML comment, and start every boundary at column 1 with no leading or trailing spaces or tabs. Keep the Markdown indentation on the content inside the block instead. For example, wrap a nested list item like this:

<!--skill-flavor:connector-registration:start-->
    - Nested host-specific instruction.
<!--skill-flavor:connector-registration:end-->

If a new flavor needs a smaller exception than an existing multi-paragraph block, split that block into adjacent sibling blocks. Update every existing override that used the old block, and compare its complete built file before and after the refactor—the existing flavor's consumer text must remain unchanged. Never nest a narrower block inside the old one.

Prefer Additive Extension Points

Do not replace a complete shared table, list, or navigation section merely to add host guidance. A replacement freezes that whole passage for the flavor, so later canonical additions inside it no longer propagate. Keep the shared content unmarked and put an empty extension block next to it:

| Shared reference | Shared purpose |
|---|---|
| references/common.md | Used by every host |
<!--skill-flavor:reference-navigation-extra:start-->

<!--skill-flavor:reference-navigation-extra:end-->

Fill only that extension in the sparse override. The default emits nothing at the extension point; the flavor receives the complete shared section plus its addition. If one existing row genuinely differs, mark only that row instead of copying the whole table. Whenever a canonical marked passage changes, read every override for that block because those flavors do not inherit the edit.

Treat Missing Overrides as Intentional Inheritance

Every custom flavor package contains every canonical skill. Sparse files only replace passages that differ for that host.

• Add no flavor file when canonical guidance is correct for the host.
• Add the smallest replacement block when canonical guidance is wrong for the host.
• Review every new or materially changed canonical skill against every existing flavor because inclusion is automatic. Update or add the smallest necessary sparse override wherever the canonical guidance is not correct for that flavor.
• Do not create an empty flavor. A flavor needs at least one sparse override or `.canonical` pin; if a host has no exceptions, it should consume the default package.

Pin a Skill to Its Previous Generation (Rare)

Use this only when a canonical skill was replaced by a new generation that a host cannot run yet, so no set of sparse overrides can make it correct there.

• Keep the previous tree at `classic/skills/<skill>/` (same layout as `skills/`, no symlinks). It is not in the root npm package or any plugin catalog.
• Add `skill-flavors/<flavor>/<skill>/.canonical` containing exactly `classic`. That flavor then composes `<skill>` from the classic tree, and its overrides for that skill target classic paths and markers.
• A pin may only swap the source of a skill `skills/` already ships. `npm run skills:validate` fails on a pin to an unknown skill, a pin to a missing classic tree, and a