Skip to content
Back to search

skill-check

Linter for agent skill files

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/thedaviddias--skill-check/badge.svg)](/listings/thedaviddias--skill-check)

HTML

<a href="/listings/thedaviddias--skill-check"><img src="/api/listings/thedaviddias--skill-check/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx skill-check .

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 464 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # skill-check
  2. [![npm version](https://img.shields.io/npm/v/skill-check)](https://www.npmjs.com/package/skill-check)
  3. [![CI](https://github.com/thedaviddias/skill-check/actions/workflows/ci.yml/badge.svg)](https://github.com/thedaviddias/skill-check/actions/workflows/ci.yml)
  4. [![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
  5. `skill-check` validates agent skills with clear diagnostics, auto-fix support, quality scoring, and optional security scanning.
  6. ![skill-check demo](docs/assets/skill-check-demo.gif)
  7. ## Quick Start
  8. ```bash
  9. npx skill-check .
  10. ```
  11. ## Features
  12. - Validates `SKILL.md` structure, frontmatter, description quality, body limits, and local references.
  13. - Scores skills from 0-100 so teams can track quality improvements over time.
  14. - Supports deterministic `--fix` for safe formatting and metadata corrections.
  15. - Runs an integrated security scan (`agent-scan`) in the same CLI pipeline.
  16. - Accepts local paths and GitHub URLs (`https://github.com/<owner>/<repo>`).
  17. - Exports text, JSON, SARIF, HTML, and GitHub annotation formats.
  18. ## Install Options
  19. Global install via curl:
  20. ```bash
  21. curl -fsSL https://raw.githubusercontent.com/thedaviddias/skill-check/main/scripts/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 31 on GitHub
  22. ```
  23. Install via Homebrew:
  24. ```bash
  25. brew tap thedaviddias/skill-check https://github.com/thedaviddias/skill-check
  26. brew install skill-check
  27. ```
  28. ## Commands
  29. | Command | Description |
  30. |---|---|
  31. | `skill-check [path\|github-url]` | Shorthand for `skill-check check [path\|github-url]` |
  32. | `skill-check check [path\|github-url]` | Run validation (and optional security scan) |
  33. | `skill-check split-body [path]` | Preview/apply section-based body split into `references/*.md` |
  34. | `skill-check new <name>` | Scaffold a new skill directory with SKILL.md template |
  35. | `skill-check watch [path]` | Watch local paths for changes and re-run validation on save |
  36. | `skill-check diff <a> <b>` | Compare diagnostics between two skill directories |
  37. | `skill-check report [path\|github-url]` | Generate a markdown health report |
  38. | `skill-check rules [id]` | List all rules, or show detail for a specific rule |
  39. | `skill-check security-scan [path\|github-url]` | Run security scan via agent-scan (mcp-scan) |
  40. | `skill-check init` | Create `skill-check.config.json` template |
  41. ### check options
  42. | Flag | Description |
  43. |---|---|
  44. | `--fix` | Apply safe automatic fixes for supported findings |
  45. | `--fix --interactive` | Prompt before applying each fix (TTY only) |
  46. | `--baseline <path>` | Compare against a previous JSON run and show new/fixed counts |
  47. | `--format <fmt>` | Output format (see below) |
  48. | `--share` | Render a share card (text format only) |
  49. | `--share-out <path>` | Save a share image file (default: `./skill-check-share.png`) |
  50. | `--no-open` | Skip auto-opening HTML reports |
  51. | `--no-security-scan` | Skip the security scan |
  52. | `--security-scan-verbose` | Show full raw `agent-scan` output (default is compact summary) |
  53. | `--strict` | Treat warnings as errors |
  54. | `--lenient` | Relax selected strict rules |
  55. | `--fail-on-warning` | Exit non-zero when warnings exist |
  56. ## Output Formats
  57. | Format | Description |
  58. |---|---|
  59. | `text` | Colorized terminal output with ASCII tables, severity badges, and quality scores (default) |
  60. | `json` | Machine-readable output including quality scores and optional baseline diff |
  61. | `sarif` | SARIF format for security tooling and GitHub Code Scanning |
  62. | `html` | Self-contained HTML report with scores, filtering, and dark mode |
  63. | `github` | `::error` / `::warning` annotations for GitHub Actions |
  64. **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.
  65. **View locally:** `npx skill-check . --format html` or open the file directly: `open skill-check-report.html` (macOS).
  66. 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).
  67. An ASCII CLI banner is shown in interactive text mode; set `SKILL_CHECK_NO_BANNER=1` to disable it.
  68. ## Quality Scores
  69. Every `check` run computes a quality score (0-100) per skill based on five weighted categories:
  70. | Category | Weight | What it measures |
  71. |---|---|---|
  72. | Frontmatter | 30% | Required fields, naming, ordering |
  73. | Description | 30% | Length, "Use when" phrasing |
  74. | Body | 20% | Line/token limits |
  75. | Links | 10% | Broken local and reference links |
  76. | File | 10% | Trailing newlines, formatting |
  77. Scores appear in `text`, `html`, and `json` output.
  78. ## Duplicate Detection
  79. When multiple skills share the same `name` or identical `description`, `check` emits `duplicates.name` / `duplicates.description` warnings so agents can reliably differentiate skills.
  80. ## Baseline Comparison
  81. Save a JSON run as a baseline and compare later:
  82. ```bash
  83. npx skill-check check . --format json --no-security-scan > baseline.json
  84. # ... make changes ...
  85. npx skill-check check . --baseline baseline.json --no-security-scan
  86. ```
  87. Output shows how many diagnostics are new, fixed, or unchanged.
  88. ## Development Quick Start
  89. ```bash
  90. pnpm install
  91. pnpm run check
  92. pnpm run report
  93. ```
  94. Generate real CLI outputs from multi-skill fixtures:
  95. ```bash
  96. pnpm run smoke:cli
  97. ```
  98. Smoke output files are written to `reports/smoke/`.
  99. Smoke includes a real security scan run by default.
  100. Smoke also includes a real `--fix` run on a temp copy of the failing mixed fixture.
  101. You can control smoke output colors with `SMOKE_COLOR=always|auto|never`.
  102. 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`).
  103. Use `SMOKE_SECURITY_SCAN_SKILLS=/path/to/skills` to override the skills path scanned in smoke mode.
  104. Create config with guided setup:
  105. ```bash
  106. npx skill-check init --interactive
  107. ```
  108. ## Security Scan
  109. `skill-check` can validate repos or direct skills directories:
  110. ```bash
  111. npx skill-check /path/to/repo
  112. npx skill-check check ~/.claude/skills
  113. ```
  114. `check` runs the security scan by default.
  115. If dependencies are missing, `skill-check` automatically installs scanner dependencies by default.
  116. Use `--no-installs` to hard-block automatic installs.
  117. By default, `skill-check` prints a compact security summary; use `--security-scan-verbose` for full scanner details.
  118. Run security scan without UV by forcing `pipx`:
  119. ```bash
  120. npx skill-check security-scan . --security-scan-runner pipx
  121. ```
  122. Run validation + security scan in one pipeline step with explicit runner:
  123. ```bash
  124. npx skill-check check . --security-scan-runner pipx
  125. ```
  126. Skip security scan for local/offline linting:
  127. ```bash
  128. npx skill-check check . --no-security-scan
  129. ```
  130. Apply safe auto-fixes and then re-run validation:
  131. ```bash
  132. npx skill-check check . --fix --no-security-scan
  133. ```
  134. Interactively choose which fixes to apply:
  135. ```bash
  136. npx skill-check check . --fix --interactive --no-security-scan
  137. ```
  138. Scaffold a new skill:
  139. ```bash
  140. npx skill-check new my-skill
  141. ```
  142. Watch for changes during development:
  143. ```bash
  144. npx skill-check watch . --no-security-scan
  145. ```
  146. Compare two skill directories:
  147. ```bash
  148. npx skill-check diff skills/ other-skills/
  149. ```
  150. Use GitHub annotations in CI:
  151. ```bash
  152. npx skill-check check . --format github --no-security-scan
  153. ```
  154. Generate a screenshot-friendly share card:
  155. ```bash
  156. npx skill-check https://github.com/thedaviddias/skill-check --share --no-security-scan
  157. ```
  158. By default this also writes `skill-check-share.png` in your current directory.
  159. Set a custom output path with `--share-out path/to/card.png`.
  160. Hard-block dependency installs:
  161. ```bash
  162. npx skill-check check . --no-installs
  163. ```
  164. ## Remote GitHub URLs
  165. `skill-check` supports scanning GitHub repos directly without a manual clone:
  166. ```bash
  167. npx skill-check https://github.com/thedaviddias/skill-check --no-security-scan
  168. npx skill-check https://github.com/thedaviddias/skill-check/tree/main/skills --no-security-scan
  169. ```
  170. Remote URL scanning behavior:
  171. - Creates an ephemeral shallow clone (`git clone --depth 1`) in a temp directory.
  172. - Cleans up the checkout automatically after the command finishes.
  173. - Shows remote preparation progress on stderr (spinner in TTY, `[remote]` status lines in non-TTY/CI).
  174. - Keeps security scan enabled by default (same as local path behavior).
  175. - Does not support `--fix` for URL targets (read-only workflow).
  176. - `watch` and `diff` are local-path only in this version.
  177. ## Auto-fix Coverage
  178. `--fix` currently handles deterministic formatting/metadata issues:
  179. - `frontmatter.required`
  180. - `frontmatter.name_required`
  181. - `frontmatter.description_required`
  182. - `frontmatter.name_matches_directory`
  183. - `frontmatter.name_slug_format`
  184. - `frontmatter.field_order`
  185. - `description.use_when_phrase`
  186. - `description.min_recommended_length`
  187. - `file.trailing_newline_single`
  188. Rules requiring human intent (content quality, max-length trimming, broken links, or oversized bodies) remain manual and are reported after fixes are applied.
  189. Use `--fix --interactive` for per-diagnostic approval prompts (requires TTY).
  190. ## Split Oversized Skill Bodies
  191. When `body.max_lines` fails, use `split-body` to extract `##` sections into `references/*.md`.
  192. Preview first (no writes):
  193. ```bash
  194. npx skill-check split-body <skill-dir-or-file>
  195. ```
  196. Apply changes:
  197. ```bash
  198. npx skill-check split-body <skill-dir-or-file> --write
  199. ```
  200. Notes:
  201. - Split is deterministic and section-based (`##` headings).
  202. - If a long body has no `##` headings, the command reports a blocked plan and explains what to add.
  203. - `split-body` is local-path only (no GitHub URL mutation flow in v1).
  204. - After writing, run `npx skill-check check <skill-dir-or-file> --no-security-scan`.
  205. - For editorial cleanup, use `docs/skills/split-into-references/SKILL.md` or [the published copy](https://github.com/thedaviddias/skill-check/blob/main/docs/skills/split-into-references/SKILL.md).
  206. ## GitHub Action
  207. Use `skill-check` directly in workflows:
  208. Marketplace status: not listed in GitHub Marketplace yet.
  209. Supported usage today is direct repo tags (`uses: thedaviddias/skill-check@v1` or `@v1.x.y`).
  210. See `docs/github-action-publishing.md` for the publication playbook.
  211. ```yaml
  212. name: skill-check
  213. on:
  214. pull_request:
  215. push:
  216. branches: [main]
  217. jobs:
  218. validate:
  219. runs-on: ubuntu-latest
  220. steps:
  221. - uses: actions/checkout@v4
  222. - uses: thedaviddias/skill-check@v1
  223. with:
  224. path: .
  225. ```
  226. Use `--format github` for inline annotations on PRs:
  227. ```yaml
  228. - run: npx skill-check check . --format github --no-security-scan
  229. ```
  230. Enable security scan explicitly (default is disabled in the action):
  231. ```yaml
  232. name: skill-check-security
  233. on:
  234. pull_request:
  235. jobs:
  236. validate:
  237. runs-on: ubuntu-latest
  238. steps:
  239. - uses: actions/checkout@v4
  240. - uses: thedaviddias/skill-check@v1
  241. with:
  242. path: .
  243. security-scan: "true"
  244. security-scan-install-policy: allow
  245. security-scan-runner: pipx
  246. ```
  247. Emit SARIF and upload to GitHub Code Scanning:
  248. ```yaml
  249. name: skill-check-sarif
  250. on:
  251. pull_request:
  252. push:
  253. branches: [main]
  254. permissions:
  255. contents: read
  256. security-events: write
  257. jobs:
  258. validate:
  259. runs-on: ubuntu-latest
  260. steps:
  261. - uses: actions/checkout@v4
  262. - id: skillcheck
  263. uses: thedaviddias/skill-check@v1
  264. with:
  265. path: .
  266. format: sarif
  267. sarif-file: reports/skill-check.sarif.json
  268. - uses: github/codeql-action/upload-sarif@v3
  269. with:
  270. sarif_file: ${{ steps.skillcheck.outputs.sarif-file }}
  271. ```
  272. The action outputs:
  273. - `exit-code`: CLI exit code
  274. - `sarif-file`: absolute path to SARIF file when `format=sarif`
  275. - `command`: full command used for execution
  276. `format=sarif` cannot be combined with `security-scan=true` in the action because security scan output is not SARIF.
  277. ## Action Release Checklist
  278. 1. Ensure `main` contains the desired `action.yml` and `github-action/index.js`.
  279. 2. Create and push an immutable version tag (example: `v1.2.0`).
  280. 3. Move the major tag to the latest stable release (`v1` -> `v1.2.0` commit).
  281. 4. Verify a workflow using `uses: thedaviddias/skill-check@v1` resolves the updated action.
  282. ## Rules Reference
  283. Run `skill-check rules` to see all built-in rules with severity and fixable status.
  284. Run `skill-check rules <id>` for detail on a specific rule.
  285. | Rule | Default | Fixable |
  286. |---|---|---|
  287. | `frontmatter.required` | error | yes |
  288. | `frontmatter.name_required` | error | yes |
  289. | `frontmatter.description_required` | error | yes |
  290. | `frontmatter.name_matches_directory` | error | yes |
  291. | `frontmatter.name_slug_format` | error | yes |
  292. | `frontmatter.name_max_length` | error | no |
  293. | `frontmatter.field_order` | error | yes |
  294. | `frontmatter.unknown_fields` | warn | no |
  295. | `frontmatter.compatibility_max_length` | warn | no |
  296. | `frontmatter.metadata_string_values` | warn | no |
  297. | `frontmatter.allowed_tools_format` | warn | no |
  298. | `description.non_empty` | error | no |
  299. | `description.max_length` | error | no |
  300. | `description.use_when_phrase` | warn | yes |
  301. | `description.min_recommended_length` | warn | yes |
  302. | `body.max_lines` | error | no |
  303. | `body.max_tokens` | warn | no |
  304. | `file.trailing_newline_single` | warn | yes |
  305. | `links.local_markdown_resolves` | warn | no |
  306. | `links.references_resolve` | warn | no |
  307. | `duplicates.name` | warn | no |
  308. | `duplicates.description` | warn | no |
  309. All rules emit actionable `suggestion` text to guide fixes.
  310. ## Releasing
  311. Releases are automated with [semantic-release](https://github.com/semantic-release/semantic-release). Pushing to `main` (after CI passes) runs the release workflow: commits are analyzed for [Conventional Commits](https://www.conventionalcommits.org/) (`fix:`, `feat:`, `BREAKING CHANGE:`), the version is bumped, `CHANGELOG.md` is updated, the package is published to npm, and a GitHub release is created.
  312. - **Commit messages** are validated locally by [commitlint](https://commitlint.js.org/) (enforced by the `commit-msg` hook). Use `fix:`, `feat:`, `docs:`, `chore:`, etc.
  313. - **npm auth:** Use [npm Trusted Publishing (OIDC)](https://docs.npmjs.com/trusted-publishers) so you don’t need `NPM_TOKEN`. On [npmjs.com](https://www.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.
  314. 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.
  315. ## Docs
  316. - `docs/quickstart.md`
  317. - `docs/github-action-publishing.md`
  318. - `docs/config.md`
  319. - `docs/rules.md`
  320. - `docs/plugins.md`
  321. - `docs/migration-from-agent-forge.md`
  322. ## Contributing
  323. Contributions are welcome. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) before opening a pull request.
  324. ## Contributors
  325. Thanks goes to these people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
  326. <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
  327. <!-- prettier-ignore-start -->
  328. <!-- markdownlint-disable -->
  329. <table>
  330. <tbody>
  331. <tr>
  332. <td align="center"><a href="https://github.com/thedaviddias"><img src="https://avatars.githubusercontent.com/u/5763274?v=4?s=100" width="100px;" alt="thedaviddias"/><br /><sub><b>David Dias</b></sub></a><br /><a href="https://github.com/thedaviddias/skill-check/commits?author=thedaviddias" title="Code">💻</a> <a href="https://github.com/thedaviddias/skill-check/commits?author=thedaviddias" title="Documentation">📖</a> <a href="#maintenance-thedaviddias" title="Maintenance">🚧</a></td>
  333. </tr>
  334. </tbody>
  335. </table>
  336. <!-- markdownlint-restore -->
  337. <!-- prettier-ignore-end -->
  338. <!-- ALL-CONTRIBUTORS-LIST:END -->
  339. This project follows the [all-contributors](https://allcontributors.org) specification.
  340. ## License
  341. MIT - see [`LICENSE`](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.