skillox lint

Author-time scan of one or more local SKILL.md files. CI-friendly exit codes, multi-file support, configurable failure threshold. Same engine as skillox audit and the hosted scanner at skillox.io.

Usage

# Lint ./SKILL.md (default)
skillox lint

# Lint a specific file
skillox lint ./my-skill/SKILL.md

# Lint multiple files (shell-expanded glob)
skillox lint ./**/SKILL.md

# In CI — exit non-zero on any high/crit finding
skillox lint --ci

# Tune the threshold (default: high)
skillox lint --ci --fail-at med

# Machine-readable output for pipelines
skillox lint --ci --format json

lint vs audit — which one to use

Both wrap the same engine. The difference is positioning:

skillox audit <target> — consumer-facing. One target (URL or file). Built around "is this safe to install?" Exit codes tied to the grade (0 for A/B, 1 for C, 2 for D, 3 for F).
skillox lint [paths…] — author-facing. Multiple local files. Built around the dev loop and CI. Exit codes signal whether the threshold was breached (not the grade itself).

Exit codes

0 — all files loaded, no breach (or no --ci)
1 — at least one file has a finding at or above --fail-at (only in --ci mode)
2 — load error (file missing, invalid flag); distinct from a breach so your pipeline can branch

Flags

--ci                      exit non-zero on any finding at/above --fail-at
--fail-at <level>         severity threshold: low | med | high | crit  (default: high)
--format <kind>           output format: human | json                  (default: human)
--no-color                strip ANSI color codes

CI example — GitHub Actions

# .github/workflows/skillox-lint.yml
name: Lint SKILL.md files
on:
  pull_request:
    paths:
      - '**/SKILL.md'

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm install -g skillox
      - run: skillox lint "./**/SKILL.md" --ci --fail-at high

CI example — Forgejo Actions

# .forgejo/workflows/skillox-lint.yml
name: Lint SKILL.md files
on: [pull_request]

jobs:
  lint:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g skillox
      - run: skillox lint "./**/SKILL.md" --ci --fail-at high

More providers + a pre-commit hook — GitLab CI, CircleCI, and a local .git/hooks/pre-commit shell script ship in the CLI's examples/ci/ folder (installed with the npm package, also browsable at git.skillox.io · examples/ci).

JSON output

For pipelines that need to parse results or report findings into another system (Sentry, Datadog, internal dashboards), use --format json. Shape:

{
  "files": [
    {
      "path": "./SKILL.md",
      "ok": true,
      "grade": "C",
      "score": 55,
      "findingsCount": 4,
      "findings": [
        {
          "ruleId": "filesystem-overreach",
          "severity": "high",
          "title": "...",
          "line": 12,
          "excerpt": "...",
          "cwe": "CWE-552"
        }
      ],
      "thresholdBreached": true
    }
  ],
  "ci": true,
  "failLevel": "high",
  "exitCode": 1
}

The hosted scan is canonical

skillox lint runs the same engine as the hosted scanner at skillox.io — same rules, same weights, same grade calculation. When you publish via the creator portal, the server-side scan is the canonical one (so a malicious creator can't fake an A locally), but for every honest author the local result matches what the portal will see. Lint clean → publish clean.

skillox init — scaffold a SKILL.md before you lint it
skillox audit — consumer-side scanner for a single target (URL or file)
skillox policy — org-wide policy overlay applied on top of the grade
All scanner rules — the 12 rules that produce the findings lint surfaces