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

skill-flavors/<flavor>/

Do not create an exception merely to reword shared guidance.

Keep the canonical 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.

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.

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

Every direct lowercase kebab-case directory under is a flavor. Never hardcode in the composer, npm build scripts, generic validation loop, or reusable flavor publisher. Publication is intentionally different: each released flavor must opt in through an explicit reviewed caller so its registry policy cannot expand implicitly.

Package names derive mechanically from the root package:

default

@uipath/skills

studioweb

@uipath/skills-studioweb

<flavor>

@uipath/skills-<flavor>

Do not add an allowlist, , a flavor registry, or per-flavor package metadata. The directory name and sparse overrides are the source contract.

Run the repository commands in order:

npm run skills:validate
npm run skills:build
npm run skills:pack
npm run skills:test
git diff --check

must produce complete marker-free trees under . must rebuild those trees, stage packages under , run real , and verify tarballs under . Flavor publishing jobs must select one verified by manifest identity and publish only that exact path; they must never publish a wildcard containing the default or another flavor.

Normal and at the repository root remain backward compatible default-package commands. Their lifecycle transactionally activates a marker-free default tree, and restores the exact canonical source tree before the command finishes. They produce or publish only ; they do not replace , which builds every discovered flavor. If npm fails or is interrupted between those lifecycle steps and remains, first confirm the original npm process has ended, then run before retrying. Recovery restores canonical sources; if it finds unexpected overlay edits, it preserves them under and exits nonzero so they cannot be missed. Never use for root source packaging because it intentionally bypasses this composition lifecycle.

Inspect the final package contract, not only sparse sources:

Clarify what "available" means before release work: a successful makes a local tarball available; registry availability requires an explicit publisher. When publication is in scope, read completely and confirm the target registry and channel. Keep 's established default jobs root-only. Give each published flavor an isolated, reviewed caller that passes its flavor and channel to . The reusable workflow validates the flavor, derives its package name, and publishes one selected tarball to GitHub Packages only. Studio Web callers pass ; never add Studio Web to the default npmjs path. A future flavor is automatically buildable, not automatically publishable, until an explicit caller is added. The reusable publisher also requires the repository variable ; leave it absent or false until an operator has confirmed that every explicitly published custom package has been bootstrapped as Internal, does not inherit access from the public repository, and grants Actions write access. Registry routing and GitHub package visibility are separate controls, and this variable is an enablement switch rather than a live visibility check. Follow the one-time procedure in , and disable the global gate again before adding a caller for another not-yet-bootstrapped flavor.