Use the Development Loop

Edits canonical Skillset source, previews and verifies generated output, and routes target-side changes through explicit recovery workflows.

Daily Skillset work moves in one direction: edit canonical source, preview the derived projection, confirm writes, and review the generated output diff.

Edit, preview, write, verify

After changing skillset.yaml or .skillset/, run:

skillset check
skillset diff
skillset build
skillset build --yes
skillset check --only outputs

The comprehensive check includes source and generated-output readiness, so it may report expected drift before regeneration. diff and bare build preview without writing. The confirmed build refreshes owned destinations, and the output-only check proves they are current.

Use skillset explain <path> when you need the source, target, ownership, or provenance behind one file. Use skillset status for a broader repository summary. Exact syntax belongs to the generated CLI reference.

Watch while you work

skillset dev is a foreground, preview-only loop. It watches workspace configuration and canonical source, reruns diagnostics, and reports pending output changes.

skillset dev

Use continuous writes only when that is what you intend:

skillset dev --write

Generated output, caches, locks, and backups are not watch inputs, so output churn cannot create a feedback loop. The Dev Watch reference owns the detailed behavior.

Keep authority explicit

Ordinary work is source-to-output. Do not edit a generated file and expect build or check --write to treat it as source truth.

If a managed target file contains an intentional edit, preview bounded reconciliation:

skillset reconcile <generated-path> --use output

Confirm only a clean, understandable mapping with --yes. Use --use source when canonical source should win. Skillset may refuse provider-native, metadata-owned, multi-source, unmanaged, or unsafe reverse mappings; the reconcile reference explains the boundary.

Provider-format migrations belong to skillset update, not ordinary build or reconciliation. Recoverable collision and target-edit backups belong to skillset restore; list and preview a restore before confirming it. See Output Safety.

Recover generated output

When generated output itself is damaged rather than edited on purpose, use the dedicated recovery routes instead of rebuilding by hand:

• skillset check --write rebuilds output when drift from current source is the only blocking condition.
• skillset build --repair [path...] restores deleted output and reports hand edits without discarding them; add --discard-edits only when those edits should be dropped.
• skillset resolve regenerates and stages generated-output conflicts during a rebase or merge.
• A rebuild-only (pre-v4) lock needs the one-time generated-state rebuild.

build --repair and resolve preview first and write only with --yes; check --write writes directly, so review skillset diff before using it. Troubleshooting covers the symptoms that lead to each one.

Record meaningful source changes

When the workspace uses Skillset’s change ledger, run skillset change status after a source change and add the required reason before shipping. The Changes reference owns ledger and release details.

Review before committing

• Source checks pass.
• The build preview matches the intended destinations.
• check --only outputs passes after the confirmed build.
• Generated files and locks changed only where expected.
• Unsupported or degraded outcomes are understood, not hidden.
• No build result is mistaken for runtime activation.

When the loop does not behave as expected, start with troubleshooting.