skill-check

skill-check validates agent skills with clear diagnostics, auto-fix support, quality scoring, and optional security scanning.

Quick Start

npx skill-check .

Features

• Validates SKILL.md structure, frontmatter, description quality, body limits, and local references.
• Scores skills from 0-100 so teams can track quality improvements over time.
• Supports deterministic --fix for safe formatting and metadata corrections.
• Runs an integrated security scan (agent-scan) in the same CLI pipeline.
• Accepts local paths and GitHub URLs (https://github.com/<owner>/<repo>).
• Exports text, JSON, SARIF, HTML, and GitHub annotation formats.

Install Options

Global install via curl:

curl -fsSL https://raw.githubusercontent.com/thedaviddias/skill-check/main/scripts/install.sh | bash

Install via Homebrew:

brew tap thedaviddias/skill-check https://github.com/thedaviddias/skill-check
brew install skill-check

Commands

check options

Output Formats

HTML reports are written to skill-check-report.html (or output.reportPath). In an interactive terminal the report opens in your browser automatically; use --no-open to skip.

View locally: npx skill-check . --format html or open the file directly: open skill-check-report.html (macOS).

The text formatter includes quality score bars per skill, colorized severity badges, and a share-friendly shield card with the exact runnable npx skill-check ... command (including GitHub URL targets when used). An ASCII CLI banner is shown in interactive text mode; set SKILL_CHECK_NO_BANNER=1 to disable it.

Quality Scores

Every check run computes a quality score (0-100) per skill based on five weighted categories:

Scores appear in text, html, and json output.

Duplicate Detection

When multiple skills share the same name or identical description, check emits duplicates.name / duplicates.description warnings so agents can reliably differentiate skills.

Baseline Comparison

Save a JSON run as a baseline and compare later:

npx skill-check check . --format json --no-security-scan > baseline.json
# ... make changes ...
npx skill-check check . --baseline baseline.json --no-security-scan

Output shows how many diagnostics are new, fixed, or unchanged.

Development Quick Start

pnpm install
pnpm run check
pnpm run report

Generate real CLI outputs from multi-skill fixtures:

pnpm run smoke:cli

Smoke output files are written to reports/smoke/. Smoke includes a real security scan run by default. Smoke also includes a real --fix run on a temp copy of the failing mixed fixture. You can control smoke output colors with SMOKE_COLOR=always|auto|never. You can set SMOKE_SECURITY_SCAN=0 to skip security smoke and SMOKE_SECURITY_SCAN_RUNNER=auto|local|uvx|pipx to choose the runner (default: pipx). Use SMOKE_SECURITY_SCAN_SKILLS=/path/to/skills to override the skills path scanned in smoke mode.

Create config with guided setup:

npx skill-check init --interactive

Security Scan

skill-check can validate repos or direct skills directories:

npx skill-check /path/to/repo
npx skill-check check ~/.claude/skills

check runs the security scan by default. If dependencies are missing, skill-check automatically installs scanner dependencies by default. Use --no-installs to hard-block automatic installs. By default, skill-check prints a compact security summary; use --security-scan-verbose for full scanner details.

Run security scan without UV by forcing pipx:

npx skill-check security-scan . --security-scan-runner pipx

Run validation + security scan in one pipeline step with explicit runner:

npx skill-check check . --security-scan-runner pipx

Skip security scan for local/offline linting:

npx skill-check check . --no-security-scan

Apply safe auto-fixes and then re-run validation:

npx skill-check check . --fix --no-security-scan

Interactively choose which fixes to apply:

npx skill-check check . --fix --interactive --no-security-scan

Scaffold a new skill:

npx skill-check new my-skill

Watch for changes during development:

npx skill-check watch . --no-security-scan

Compare two skill directories:

npx skill-check diff skills/ other-skills/

Use GitHub annotations in CI:

npx skill-check check . --format github --no-security-scan

Generate a screenshot-friendly share card:

npx skill-check https://github.com/thedaviddias/skill-check --share --no-security-scan

By default this also writes skill-check-share.png in your current directory. Set a custom output path with --share-out path/to/card.png.

Hard-block dependency installs:

npx skill-check check . --no-installs

Remote GitHub URLs

skill-check supports scanning GitHub repos directly without a manual clone:

npx skill-check https://github.com/thedaviddias/skill-check --no-security-scan
npx skill-check https://github.com/thedaviddias/skill-check/tree/main/skills --no-security-scan

Remote URL scanning behavior:

• Creates an ephemeral shallow clone (git clone --depth 1) in a temp directory.
• Cleans up the checkout automatically after the command finishes.
• Shows remote preparation progress on stderr (spinner in TTY, [remote] status lines in non-TTY/CI).
• Keeps security scan enabled by default (same as local path behavior).
• Does not support --fix for URL targets (read-only workflow).
• watch and diff are local-path only in this version.

Auto-fix Coverage

--fix currently handles deterministic formatting/metadata issues:

• frontmatter.required
• frontmatter.name_required
• frontmatter.description_required
• frontmatter.name_matches_directory
• frontmatter.name_slug_format
• frontmatter.field_order
• description.use_when_phrase
• description.min_recommended_length
• file.trailing_newline_single

Rules requiring human intent (content quality, max-length trimming, broken links, or oversized bodies) remain manual and are reported after fixes are applied.

Use --fix --interactive for per-diagnostic approval prompts (requires TTY).

Split Oversized Skill Bodies

When body.max_lines fails, use split-body to extract ## sections into references/*.md.

Preview first (no writes):

npx skill-check split-body <skill-dir-or-file>

Apply changes:

npx skill-check split-body <skill-dir-or-file> --write

Notes:

• Split is deterministic and section-based (## headings).
• If a long body has no ## headings, the command reports a blocked plan and explains what to add.
• split-body is local-path only (no GitHub URL mutation flow in v1).
• After writing, run npx skill-check check <skill-dir-or-file> --no-security-scan.
• For editorial cleanup, use docs/skills/split-into-references/SKILL.md or the published copy.

GitHub Action

Use skill-check directly in workflows:

Marketplace status: not listed in GitHub Marketplace yet. Supported usage today is direct repo tags (uses: thedaviddias/skill-check@v1 or @v1.x.y). See docs/github-action-publishing.md for the publication playbook.

name: skill-check

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: thedaviddias/skill-check@v1
        with:
          path: .

Use --format github for inline annotations on PRs:

      - run: npx skill-check check . --format github --no-security-scan

Enable security scan explicitly (default is disabled in the action):

name: skill-check-security

on:
  pull_request:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: thedaviddias/skill-check@v1
        with:
          path: .
          security-scan: "true"
          security-scan-install-policy: allow
          security-scan-runner: pipx

Emit SARIF and upload to GitHub Code Scanning:

name: skill-check-sarif

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  security-events: write

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: skillcheck
        uses: thedaviddias/skill-check@v1
        with:
          path: .
          format: sarif
          sarif-file: reports/skill-check.sarif.json
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: ${{ steps.skillcheck.outputs.sarif-file }}

The action outputs:

• exit-code: CLI exit code
• sarif-file: absolute path to SARIF file when format=sarif
• command: full command used for execution

format=sarif cannot be combined with security-scan=true in the action because security scan output is not SARIF.

Action Release Checklist

1. Ensure main contains the desired action.yml and github-action/index.js.
2. Create and push an immutable version tag (example: v1.2.0).
3. Move the major tag to the latest stable release (v1 -> v1.2.0 commit).
4. Verify a workflow using uses: thedaviddias/skill-check@v1 resolves the updated action.

Rules Reference

Run skill-check rules to see all built-in rules with severity and fixable status. Run skill-check rules <id> for detail on a specific rule.

All rules emit actionable suggestion text to guide fixes.

Releasing

Releases are automated with semantic-release. Pushing to main (after CI passes) runs the release workflow: commits are analyzed for Conventional Commits (fix:, feat:, BREAKING CHANGE:), the version is bumped, CHANGELOG.md is updated, the package is published to npm, and a GitHub release is created.

• Commit messages are validated locally by commitlint (enforced by the commit-msg hook). Use fix:, feat:, docs:, chore:, etc.
• npm auth: Use npm Trusted Publishing (OIDC) so you don’t need NPM_TOKEN. On npmjs.com go to the skill-check package → Settings → Trusted publishing → add a GitHub Actions publisher with workflow filename publish.yml (exact name, including extension). Then the workflow can publish without any npm token. Alternatively, set the NPM_TOKEN repository secret for token-based publish.

To simulate a release locally (without publishing): pnpm run release:dry-run. It will fail verifyConditions without NPM_TOKEN and GITHUB_TOKEN; in CI both are set.

Docs

• docs/quickstart.md
• docs/github-action-publishing.md
• docs/config.md
• docs/rules.md
• docs/plugins.md
• docs/migration-from-agent-forge.md

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

Contributors

Thanks goes to these people (emoji key):

David Dias 💻 📖 🚧

This project follows the all-contributors specification.

License

MIT - see LICENSE.