Programmatic Reference

Every skills-check command supports --json for machine-readable output and --ci for strict exit codes. This page documents the exit code conventions, JSON output shapes, and practical scripting patterns for integrating skills-check into your CI pipelines and automation.

Exit Codes

All commands follow a consistent exit code convention. Use these in CI to gate deployments, fail PR checks, or trigger downstream workflows.

Code	Meaning	When It Happens
`0`	Success	No findings, all checks pass
`1`	Findings detected	Findings above the configured threshold (`--fail-on` severity)
`2`	Configuration error	Invalid registry, missing required files, bad options

Use --fail-on <severity> to control the threshold that triggers exit code 1. For example, --fail-on medium exits 1 only when medium or higher severity findings are present.

JSON Output Schemas

Pass --json (or --format json) to any command to get structured output. Below are the shapes for key commands.

`check --json`

{
  "results": [
    {
      "file": "SKILL.md",
      "product": "react",
      "currentVersion": "18.2.0",
      "latestVersion": "19.1.0",
      "status": "stale"
    }
  ]
}

`audit --format json`

{
  "findings": [
    {
      "file": "SKILL.md",
      "checker": "registry",
      "severity": "critical",
      "message": "Package 'react-utils-pro' not found on npm",
      "line": 42
    }
  ],
  "summary": { "critical": 1, "high": 0, "medium": 2, "low": 0 }
}

`budget --format json`

{
  "skills": [
    {
      "file": "SKILL.md",
      "tokens": 2450,
      "sections": [{ "heading": "Installation", "tokens": 320 }]
    }
  ],
  "redundancy": [
    { "fileA": "a.md", "fileB": "b.md", "similarity": 0.73 }
  ]
}

`lint --format json`

{
  "findings": [
    {
      "file": "SKILL.md",
      "rule": "required-field",
      "severity": "error",
      "field": "product-version",
      "message": "Missing required field: product-version"
    }
  ]
}

Scripting Examples

Combine --json output with jq for powerful CI integrations.

Fail CI if any critical audit findings

npx skills-check audit --json | jq -e '.summary.critical == 0'

Get list of stale skills

npx skills-check check --json | jq -r '.results[] | select(.status == "stale") | .file'

Budget report as markdown for PR comment

npx skills-check budget --reporter markdown > budget-report.md

Enforce max token budget per skill

npx skills-check budget --max-tokens 5000 --ci

Run audit with SARIF output for GitHub Security tab

npx skills-check audit --reporter sarif > results.sarif

SARIF Integration

The audit command supports SARIF 2.1.0 output, which integrates directly with GitHub Code Scanning and the Security tab. Upload SARIF results to see audit findings as code annotations in pull requests and track them alongside other security tools.

GitHub Action workflow

- uses: voodootikigod/skills-check@v1
  with:
    commands: audit
    audit-reporter: sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: skills-check-audit.sarif

This uploads hallucinated package detections, prompt injection warnings, and other audit findings to the GitHub Security tab where they appear alongside CodeQL and other SARIF-compatible scanners.