| name | ciPreflight |
| description | Use when: running pre-commit or pre-push CI-equivalent checks in any workspace — discovers the project's CI workflow commands using workspace tools, filters for local executability, scopes to staged changes, and runs checks cheapest-first before delegating failures. |
| version | 1.2 |
| license | MIT |
CI Preflight
Skill metadata: version "1.2"; tags [commit, preflight, ci, workflow, generic]; recommended tools [file_search, read_file, grep_search, run_in_terminal, vscode_askQuestions].
Discover and execute a workspace's CI checks locally before commit or push,
using workspace tools to read actual workflow definitions rather than assuming
knowledge of the project's specific tooling or conventions.
When to use
- Before any commit or push when CI check coverage is needed
- When the project's CI checks are unknown, vary by workspace, or may have changed
- When the workspace may use any language, framework, or build system
When NOT to use
- When the workspace has a project-specific preflight skill — prefer that skill
over this generic one (it will know the project's exact commands and repair
steps)
- When the user has explicitly asked to forgo verification
- When there is nothing staged and no proposed file list to verify against
Module 1 — Discover And Scope Checks
0. Discover CI workflow files
Use workspace file search tools to list files under .github/workflows/.
For each file found, read its full contents with file-reading tools.
Keep a file if its on: key includes push or pull_request.
Exclude a file that only triggers on schedule, workflow_dispatch,
release, or deployment events — those require infrastructure or secrets that
cannot be reproduced locally.
1. Extract locally-executable run steps
For each kept workflow file, collect every jobs.<id>.steps[] entry that has
a run: key.
Include a step only when its run: block is a self-contained interpreter or
tool invocation that operates on local files (e.g. python3 ..., npm test,
make check, go test ./..., cargo test, ./gradlew test).
Omit a step when its run: block meets any of these conditions:
- References
${{ secrets.* }} — requires external credentials
- References environment variables only available on GitHub Actions runners
(e.g.
GITHUB_RUN_ID, RUNNER_TOOL_CACHE)
- Invokes upload-artifact, download-artifact, or any step that publishes or
transfers artefacts
- Calls a deployment or release tool (
gh release, npm publish,
docker push, etc.)
2. Scope to staged changes
If Step 1 found no usable run steps, proceed directly to Step 3.
Run git diff --cached --name-only with a terminal tool to get the staged file
list.
Narrow the extracted check list by that scope:
- Exclude Python-specific checks when no
.py files or test-config files are staged
- Exclude Node checks when no
.js, .ts, or package.json are staged
- Keep any check whose scope cannot be narrowed (e.g. a global lint or a
manifest freshness gate that affects the whole repo)
3. Fall back to project-structure detection
If Step 1 found no usable run steps (no workflow files, or all steps were
excluded), detect the verification command from workspace files using workspace
search and file-reading tools:
| Signal file or folder | Inferred command |
|---|
tests/ with test_*.py files | python3 -m unittest discover -s tests -p 'test_*.py' |
pytest.ini, pyproject.toml with [tool.pytest] | python3 -m pytest |
package.json with a test script | npm test |
Makefile with a test target | make test |
go.mod | go test ./... |
Cargo.toml | cargo test |
Gemfile with rspec | bundle exec rspec |
If fallback detection finds nothing credible, stop and report that no
locally-executable CI-equivalent command could be derived from the workspace.
Module 2 — Execute And Report
4. Order checks cheapest-first
Group extracted commands into tiers and run in this order, stopping at the
first blocker before running later tiers:
- Static / format / lint — fastest, no side effects
(e.g.
ruff check, eslint, golangci-lint, budget/LOC scripts)
- Type checks — moderate cost (e.g.
mypy, tsc --noEmit)
- Unit tests — moderate to expensive
- Integration / e2e tests — most expensive; exclude if not in scope of
staged changes
When tier assignment is ambiguous, prefer the order commands appear in the
workflow file — the project author likely ordered them by cost already.
5. Execute and handle each result
Run each command with a terminal tool. For each result:
| Outcome | Action |
|---|
| Exit 0 | Continue to the next check |
Stale generated artifact (exit nonzero and the output includes an explicit invocation of the form python3 …generate, npm run generate, or a similar regen tool) | Re-run the generator, explicitly git add regenerated outputs, then re-run the check |
| Unit or lint failure | Delegate to debugger with the exact failure output and staged file list; apply the minimal fix returned; re-run the failing check. If debugger cannot isolate a fix, surface the raw failure output to the user and ask whether to block the commit or accept residual risk. |
| Budget / LOC / format violation | Surface the exact violation output to the user; ask whether to fix now or accept residual risk before proceeding |
Template-safety violation (unresolved {{}} tokens in a template file) | Block the commit until resolved |
| Step requires secrets or infra (detected mid-run) | Note in summary — not a blocker |
| Any other nonzero exit | Surface exact stdout + stderr; use vscode_askQuestions if user input is required |
6. Return a summary to the caller
Return:
- The workflow files read and the commands extracted from them (or "detected
from project structure" if Step 3 was used)
- Which checks were excluded and why; whether any artifacts were regenerated and staged
- A clear pass, block, or residual-risk outcome for the caller to
act on
Verify
