---
title: "Build Scopes"
description: "Build scopes select generated destinations for preview, writing, inspection, and isolated builds."
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus.focal.host/llms.txt
> Use this file to discover all available pages before exploring further.

# Build Scopes

<a id="build-scopes"></a>

<!-- skillset:generated:start feature-support -->
| Feature | Feature status | claude | codex | cursor |
| --- | --- | --- | --- | --- |
| `workflows` | `implemented` | `not_applicable` | `not_applicable` | `not_applicable` |
<!-- skillset:generated:end feature-support -->

Registry feature: `workflows`

Support vocabulary: [Feature Reference](/skillset/reference/features/#support-vocabulary)

A build scope filters the [destinations](/skillset/glossary/#destination) that Skillset previews, writes, or inspects. It does not change [canonical source](/skillset/glossary/#canonical-source), provider meaning, source-change coverage, or which standard profiles are adopted and applicable.

## Choose a Build Mode

Root `skillset.yaml` sets the default mode:

```yaml
compile:
  build: updated
```

`updated` is the default and selects missing, changed, or stale managed output. `all` selects every configured generated file. `--updated` and `--all` override the manifest for one command and cannot be combined.

`skillset build` is plan-first. It writes only after interactive confirmation or `--yes`:

```bash
skillset build
skillset build --yes
```

The generated [`build` reference](/skillset/reference/cli/build/) owns the exact flags. The [development loop](/skillset/guides/development-loop/) shows the normal preview, write, and check sequence.

## Filter Destinations

`--scope` filters destination classes for `build`, `diff`, `list`, and `explain`:

| Scope     | Selected destination                              |
| --------- | ------------------------------------------------- |
| `repo`    | Agent Skills and provider standalone skill roots  |
| `plugins` | Agent Plugins packages and provider plugin bundles |
| `project` | Agent Instructions, project agents, and provider source |
| `user`    | Reserved; no build output exists today            |
| `all`     | Every configured destination                      |

Scopes are not entity or standards selectors. They cannot substitute for plugin or skill ids, enable or disable a standard profile, or change provider targets. `change status` and `change check` reject them because those commands measure source coverage rather than generated destinations.

`compile.targets: []` requests no provider output. It is valid only when the selected scopes still contain at least one applicable adopted Agent standard projection; otherwise the build fails with an actionable no-projections diagnostic.

## Use an Isolated Mirror

`--isolated` on `build`, `diff`, or `check --only outputs` reroots the complete [projection](/skillset/glossary/#projection) under the logical `.skillset/cache/latest/` mirror in the repository's XDG cache bucket. Reports and locks retain repository-relative paths, while live generated roots remain untouched.

Writes, [drift](/skillset/glossary/#drift) checks, stale-file removal, collision backups, and locks operate against the mirror. This is useful for inspection and tests; it does not install or activate the result.

## Read the Result

| Command | Result | Writes |
| --- | --- | --- |
| `skillset build` | Planned additions, changes, missing files, and removals | Only after confirmation or `--yes` |
| `skillset diff` | Content and state differences | Never |
| `skillset list` | Lock-backed generated inventory | Never |
| `skillset explain <path>` | Source, destination, provenance, and [render-result](/skillset/glossary/#render-result) facts | Never |
| `skillset check --only outputs` | Whether checked-in output matches source | Never |

Missing managed output appears separately from newly [generated output](/skillset/glossary/#generated-output). Unsupported or lossy destinations fail unless the [workspace](/skillset/glossary/#workspace) has an explicit visible policy that permits the result.

## Errors and Recovery

| Problem | Result | Recovery |
| --- | --- | --- |
| Unknown scope | Command fails instead of guessing | Choose a scope from the table or omit `--scope` |
| Conflicting build modes | Command fails | Pass only `--updated` or `--all` |
| Missing lock | Preview derives the configured projection; a confirmed build writes a new baseline | Review the full plan before confirming |
| Corrupt lock | Build and inspection fail because ownership is unsafe to infer | Repair or regenerate the lock from trusted source |
| Missing managed file | Diff and output check report the missing path | Preview and confirm a build |
| Unmanaged collision or edited output | Confirmed build creates a recovery snapshot before replacement | Follow [Output Safety](/skillset/reference/features/output-safety/) |

Dry-run commands never write generated files, locks, [target](/skillset/glossary/#target) configuration, or user-level settings.

## Provenance

Nearby `skillset.lock` files record the configured build mode, source and generated hashes, target state, preprocessing dependencies, warnings, and skipped or unsupported facts. One-off `--all` and `--updated` flags select the current operation without changing that persisted workspace default. Generated frontmatter remains lightweight; use [`status`](/skillset/reference/cli/status/) or [`explain`](/skillset/reference/cli/explain/) to inspect the lock-backed decision.

Source: https://nimbus.focal.host/skillset/reference/features/build-scopes/index.mdx