@sagargupta1610/skillcheck 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +59 -35
  2. package/dist/cli.js +1 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,68 +1,90 @@
1
1
  # skillcheck
2
2
 
3
+ [![npm](https://img.shields.io/npm/v/%40sagargupta1610%2Fskillcheck?label=npm)](https://www.npmjs.com/package/@sagargupta1610/skillcheck)
4
+ [![CI](https://github.com/Sagargupta16/skillcheck/actions/workflows/ci.yml/badge.svg)](https://github.com/Sagargupta16/skillcheck/actions/workflows/ci.yml)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
+ [![Node >= 22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](package.json)
7
+
3
8
  Conformance suite for [Agent Skills](https://agentskills.io) (`SKILL.md`).
4
9
 
5
- Linters check syntax. skillcheck checks reality: 36 rules with exact [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) parity (verified against the reference validator's source, message for message), client-extension awareness across 6 runtimes, structure/reference validation, trigger-test scaffolding, SARIF, and a drop-in GitHub Action.
10
+ Linters check syntax. skillcheck checks reality: 36 rules with exact [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) parity (verified against the reference validator's source, message for message), client-extension awareness across 6 runtimes, structure and reference validation, trigger-test scaffolding, SARIF output, and a drop-in GitHub Action.
11
+
12
+ ```
13
+ $ skillcheck lint ./skills
14
+
15
+ commit-helper ./skills/commit-helper
16
+ ERR [SC013 name-invalid-chars] Skill name 'commit_helper' contains invalid characters. Only letters, digits, and hyphens are allowed.
17
+ WARN [SC301 extension-field] `model` is a client extension (claude-code), not in the Agent Skills spec
18
+ WARN [SC101 broken-relative-reference] referenced file `references/style.md` does not exist in the skill directory
19
+
20
+ 16 skill(s) checked: 1 error(s), 2 warning(s), 0 info
21
+ ```
6
22
 
7
23
  ## Why
8
24
 
9
- The Agent Skills standard is adopted by 40+ runtimes (Claude Code, Codex, Gemini CLI, Copilot, Cursor, OpenCode, ...), and its ecosystem has a built-in tension: the official reference validator (`skills-ref`) is **strict** -- unknown frontmatter fields fail -- while real clients are **lenient** -- they warn and load anyway. Claude Code alone ships 18 extension fields that fail strict validation.
25
+ The Agent Skills standard is adopted by 40+ runtimes (Claude Code, Codex, Gemini CLI, Copilot, Cursor, OpenCode, ...) and its ecosystem has a built-in tension: the official reference validator (`skills-ref`) is **strict** -- unknown frontmatter fields fail -- while real clients are **lenient** -- they warn and load anyway. Claude Code alone ships 18 extension fields that fail strict validation.
10
26
 
11
27
  skillcheck is the only linter that models both tiers:
12
28
 
13
- - **error** = skills-ref 0.1.0 strict parity (exact messages, exact check order, exact i18n semantics -- Chinese and lowercase-Cyrillic names are valid, `skill_name` is not)
14
- - **warning** = client-guide lenient tier + beyond-parity checks (broken references, hidden unicode, portability)
15
- - **info** = advisory, never gates CI
29
+ | Tier | Meaning |
30
+ | --- | --- |
31
+ | **error** | skills-ref 0.1.0 strict parity: exact messages, exact check order, exact i18n semantics |
32
+ | **warning** | client-guide lenient tier + beyond-parity checks (broken references, hidden unicode, portability) |
33
+ | **info** | advisory; never gates CI |
16
34
 
17
- ## Install
35
+ ## Quick start
18
36
 
19
37
  ```bash
38
+ # no install
39
+ npx -y @sagargupta1610/skillcheck lint ./skills
40
+
41
+ # or as a dev dependency
20
42
  pnpm add -D @sagargupta1610/skillcheck
21
- # or run directly
22
- pnpm dlx @sagargupta1610/skillcheck lint ./skills
23
43
  ```
24
44
 
25
- ## Usage
26
-
27
45
  ```bash
28
46
  skillcheck lint ./my-skill # one skill
29
47
  skillcheck lint ./skills # every SKILL.md under a tree
30
48
  skillcheck lint . --profile lenient # client-guide severities
31
- skillcheck lint . --format concise # one line per finding
32
- skillcheck lint . --format json
33
- skillcheck lint . --format github # Actions inline annotations
34
- skillcheck lint . --format sarif # SARIF 2.1.0 to stdout
35
- skillcheck lint . --sarif report.sarif # sidecar SARIF alongside any format
36
- skillcheck lint . --fail-on warning # stricter CI gate
49
+ skillcheck lint . --format concise # one line per finding
50
+ skillcheck lint . --format json # machine-readable
51
+ skillcheck lint . --format sarif # SARIF 2.1.0 to stdout
52
+ skillcheck lint . --sarif report.sarif # sidecar SARIF alongside any format
53
+ skillcheck lint . --fail-on warning # stricter CI gate
37
54
  skillcheck lint . --max-warnings 10
38
55
 
39
56
  skillcheck eval init ./my-skill # scaffold evals/evals.json
40
57
  skillcheck eval check ./my-skill # validate it
41
58
  ```
42
59
 
43
- Exit codes: `0` clean, `1` findings at/above `--fail-on`, `2` usage/internal error.
60
+ Exit codes: `0` clean, `1` findings at or above `--fail-on`, `2` usage or internal error.
44
61
 
45
62
  ## GitHub Action
46
63
 
47
64
  ```yaml
48
- - uses: Sagargupta16/skillcheck@v0.2.0
49
- with:
50
- path: skills/
51
- fail-on: error
52
- sarif-file: skillcheck.sarif # optional
53
-
54
- # optional: upload to code scanning (needs security-events: write)
55
- - uses: github/codeql-action/upload-sarif@v4
56
- with:
57
- sarif_file: skillcheck.sarif
58
- category: skillcheck
65
+ jobs:
66
+ skills:
67
+ runs-on: ubuntu-latest
68
+ steps:
69
+ - uses: actions/checkout@v7
70
+ - uses: Sagargupta16/skillcheck@v0.2.0
71
+ with:
72
+ path: skills/
73
+ fail-on: error
74
+ sarif-file: skillcheck.sarif # optional
75
+
76
+ # optional: upload to code scanning (needs security-events: write)
77
+ - uses: github/codeql-action/upload-sarif@v4
78
+ with:
79
+ sarif_file: skillcheck.sarif
80
+ category: skillcheck
59
81
  ```
60
82
 
61
- Inline PR annotations come free via `--format github`; a full report lands in the job summary automatically.
83
+ Inline PR annotations come free via workflow commands; a full report table lands in the job summary automatically. Action outputs: `error-count`, `warning-count`, `sarif-file`.
62
84
 
63
85
  ## Rules
64
86
 
65
- 36 rules with stable codes (never renumbered or recycled) -- see [docs/rules.md](docs/rules.md) for the full table.
87
+ 36 rules with stable codes (never renumbered or recycled). Full reference: [docs/rules.md](docs/rules.md).
66
88
 
67
89
  | Range | Category | Examples |
68
90
  | --- | --- | --- |
@@ -80,9 +102,9 @@ Parity details worth knowing:
80
102
  - Strict-YAML semantics are enforced on top of the JS parser: flow collections, tags, and duplicate keys are rejected, like `strictyaml`.
81
103
  - The 18-field extension registry knows which runtimes read each field (`model` is Claude Code only; `paths` is Claude Code + Cursor; OpenCode and Gemini ignore all of them) and validates values (`effort: extreme` flags SC302).
82
104
 
83
- ## Config
105
+ ## Configuration
84
106
 
85
- Optional `skillcheck.config.json`:
107
+ Optional `skillcheck.config.json` in your project root:
86
108
 
87
109
  ```json
88
110
  {
@@ -93,16 +115,16 @@ Optional `skillcheck.config.json`:
93
115
  }
94
116
  ```
95
117
 
96
- Codes and aliases are interchangeable. Zero-config works.
118
+ Codes and kebab-case aliases are interchangeable. Zero-config works.
97
119
 
98
120
  ## Evals (trigger tests)
99
121
 
100
- `skillcheck eval init` scaffolds `evals/evals.json` -- a strict superset of Anthropic skill-creator's format (anything skill-creator writes, skillcheck validates unchanged), plus a `triggers` array covering the four trigger classes: explicit, implicit, contextual, and negative (the near-misses that catch over-triggering). `skillcheck lint` validates the file automatically when present. Runtime execution of these tests lands in v0.3.
122
+ `skillcheck eval init` scaffolds `evals/evals.json` -- a strict superset of Anthropic skill-creator's format (anything skill-creator writes, skillcheck validates unchanged) plus a `triggers` array covering four trigger classes: explicit, implicit, contextual, and negative (the near-misses that catch over-triggering). `skillcheck lint` validates the file automatically when present. Runtime execution of these tests lands in v0.3.
101
123
 
102
124
  ## Roadmap
103
125
 
104
126
  - [x] **v0.1** -- static lint, two-tier severity
105
- - [x] **v0.2** -- skills-ref parity (verified message-for-message), rule codes, i18n names, structure/reference rules, extension registry with value validation, SARIF 2.1.0, evals scaffold + validation, GitHub Action, profiles, config
127
+ - [x] **v0.2** -- skills-ref parity (verified message for message), rule codes, i18n names, structure/reference rules, extension registry with value validation, SARIF 2.1.0, evals scaffold + validation, GitHub Action, profiles, config
106
128
  - [ ] **v0.3** -- runtime execution: run trigger tests against Claude Code / OpenCode / Codex headlessly in Docker; `--fix` for safe fixes
107
129
  - [ ] **v1.0** -- public caniuse-style compatibility matrix + README badges
108
130
 
@@ -116,6 +138,8 @@ pnpm lint # biome
116
138
  node dist/cli.js lint fixtures/valid-skill
117
139
  ```
118
140
 
141
+ Contributions welcome -- see [CONTRIBUTING.md](CONTRIBUTING.md).
142
+
119
143
  ## License
120
144
 
121
145
  [MIT](LICENSE)
package/dist/cli.js CHANGED
@@ -12,7 +12,7 @@ import { appendFile, readFile, stat, writeFile } from "fs/promises";
12
12
  import { join } from "path";
13
13
  import { Command } from "commander";
14
14
  import { glob } from "glob";
15
- var VERSION = "0.2.0";
15
+ var VERSION = "0.2.1";
16
16
  var program = new Command();
17
17
  program.name("skillcheck").description("Conformance suite for Agent Skills (SKILL.md)").version(VERSION);
18
18
  program.command("lint").description(
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sagargupta1610/skillcheck",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "Conformance suite for Agent Skills: lint SKILL.md against the spec, run it against real agent runtimes, publish a compatibility matrix",
5
5
  "keywords": [
6
6
  "agent-skills",