---
title: "Verify Skillset in Continuous Integration"
description: "Adds Skillset readiness checks to CI and limits automatic repair to safe source-driven generated-output drift."
---

> 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.

# Verify Skillset in Continuous Integration

<a id="verify-skillset-in-continuous-integration"></a>

Continuous integration checks a Skillset [workspace](/skillset/glossary/#workspace), its authored source, committed [generated output](/skillset/glossary/#generated-output), and required release intent against a Git baseline. It does not publish, install, trust, or prove [activation](/skillset/glossary/#activation).

## Scaffold the Workflow

Preview the optional GitHub Actions scaffold without allowing an interactive write:

```bash
skillset init --include ci --json
```

Then authorize the reviewed addition:

```bash
skillset init --include ci --yes
```

When you start a new workspace instead, `skillset create <name> --include ci --yes` writes the same workflow as part of the new scaffold.

Either route creates `.github/workflows/skillset-ci.yml`. The workflow is user-owned after creation: later `init` runs report it as existing and do not replace your edits. Review its permissions and consider pinning the Skillset version before relying on it as a required check.

The scaffold comments preserve the configuration boundary: `compile.targets` selects providers, adopted applicable Agent standards render inherently, `.skillset/subagents/` is project-agent source, and `defaults.<provider>.agents` is provider configuration. CI validates the resulting source and generated state; it does not introduce a standards opt-out.

The generated [`init`](/skillset/reference/cli/init/) and [`create`](/skillset/reference/cli/create/) references own the complete option inventories.

## Choose the CI Distribution

The scaffold uses the complete `@skillset/cli` Bun distribution because its JavaScript payload is smaller than the native executable package. Its check step runs:

```bash
bunx @skillset/cli check --ci --report "$RUNNER_TEMP/skillset-ci-report.md"
```

Same-repository pull requests add `--fix`. The scaffold passes no `--since`, so the check selects its baselines automatically: source-change coverage starts from the committed `skillset.lock` and release state when they exist and otherwise falls back to the merge base with `origin/main`, then `main`; package Changesets compare against the merge base with `origin/HEAD`, then `origin/main`, then `main`. If none of those refs exist, the Changesets comparison falls back to `HEAD` and sees no package changes, so make sure CI fetches the trunk. Pass `--since <ref>` to name the baseline explicitly.

This route requires Bun 1.4.0 or newer at command runtime. It exposes the same command surface as the native distribution; it is not a reduced CI product.

If a runner already provides Node 18 and npm, the native route is also supported:

```bash
npm install --global skillset
skillset check --ci --since origin/main
```

The npm-installed command uses Node only for the launcher and does not require Bun. Pin either package to the intended release version in a production workflow. The [installation guide](/skillset/start/installation/) owns the complete route and runtime matrix.

## Reproduce the Check Locally

Run the same branch-aware readiness mode against your trunk ref:

```bash
skillset check --ci --since origin/main
```

To create the same Markdown report used by job summaries and pull-request comments, request a report file explicitly:

```bash
skillset check --ci --since origin/main --report skillset-ci-report.md
```

Without `--fix`, the check does not rewrite source or generated output. The requested report is its only repository-facing write. See the generated [`check` reference](/skillset/reference/cli/check/) for exact syntax.

## Decide Whether CI May Repair Drift

`--fix` is a write request. It repairs [drift](/skillset/glossary/#drift) only when source-driven generated output is the sole blocker and the managed files still match their recorded ownership hashes:

```bash
skillset check --ci --fix --since origin/main
```

It does not overwrite [target-side](/skillset/glossary/#target) edits or unmanaged collisions. It also does not repair lint failures, invent missing source-change reasons or package Changesets, resolve an unavailable Git baseline, perform provider-format migrations, or hide [build](/skillset/glossary/#build) failures. Mixed blockers remain report-only until each owning workflow resolves them.

Use [troubleshooting](/skillset/troubleshooting/) for recovery by symptom. The exhaustive [CI feature reference](/skillset/reference/features/ci/) owns the diagnostic and repair contract.

## Understand the Scaffolded Job

The GitHub Actions scaffold checks out full history so its default baselines can be resolved. On a same-repository pull request it may run `--fix`, commit a mechanical rebuild, push it to the pull-request branch, and update a report comment. On a fork pull request it remains read-only and writes the report only to the job summary because the default token cannot push to or comment on the fork.

A fix pushed with `GITHUB_TOKEN` does not retrigger workflows automatically. If branch protection requires checks on that new commit, choose and review an authentication policy appropriate for the repository rather than adding credentials to Skillset source.

## Keep Release Intent Separate

Skillset checks two independent records:

- `.skillset/changes/` records [source-unit](/skillset/glossary/#source-unit) and workspace release provenance.
- `.changeset/*.md` records npm package release intent when a workspace has opted into Changesets with `.changeset/config.json` and package-facing code changes.

A root package manifest or generated plugin package does not opt an authoring repository into npm Changesets policy. Skills-only, plugin-output, and mixed authored/generated repositories without `.changeset/config.json` keep using the Skillset change ledger for their source units and may run the aggregate CI check without dummy package Changesets. One ledger does not satisfy the other when both policies apply. See [Changes](/skillset/reference/features/changes/), [Releases](/skillset/reference/features/releases/), and [publishing](/skillset/guides/publishing/) for their respective workflows.

Source: https://nimbus.focal.host/skillset/guides/continuous-integration/index.mdx