@sagargupta1610/skillcheck 0.2.0 → 0.2.2

package/README.md

@@ -1,68 +1,90 @@
 # skillcheck
 
+[![npm](https://img.shields.io/npm/v/%40sagargupta1610%2Fskillcheck?label=npm)](https://www.npmjs.com/package/@sagargupta1610/skillcheck)
+[![CI](https://github.com/Sagargupta16/skillcheck/actions/workflows/ci.yml/badge.svg)](https://github.com/Sagargupta16/skillcheck/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node >= 22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](package.json)
+
 Conformance suite for [Agent Skills](https://agentskills.io) (`SKILL.md`).
 
-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.
+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.
+
+```
+$ skillcheck lint ./skills
+
+commit-helper  ./skills/commit-helper
+  ERR  [SC013 name-invalid-chars] Skill name 'commit_helper' contains invalid characters. Only letters, digits, and hyphens are allowed.
+  WARN [SC301 extension-field] `model` is a client extension (claude-code), not in the Agent Skills spec
+  WARN [SC101 broken-relative-reference] referenced file `references/style.md` does not exist in the skill directory
+
+16 skill(s) checked: 1 error(s), 2 warning(s), 0 info
+```
 
 ## Why
 
-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.
+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.
 
 skillcheck is the only linter that models both tiers:
 
-- **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)
-- **warning** = client-guide lenient tier + beyond-parity checks (broken references, hidden unicode, portability)
-- **info** = advisory, never gates CI
+| Tier | Meaning |
+| --- | --- |
+| **error** | skills-ref 0.1.0 strict parity: exact messages, exact check order, exact i18n semantics |
+| **warning** | client-guide lenient tier + beyond-parity checks (broken references, hidden unicode, portability) |
+| **info** | advisory; never gates CI |
 
-## Install
+## Quick start
 
 ```bash
+# no install
+npx -y @sagargupta1610/skillcheck lint ./skills
+
+# or as a dev dependency
 pnpm add -D @sagargupta1610/skillcheck
-# or run directly
-pnpm dlx @sagargupta1610/skillcheck lint ./skills
 ```
 
-## Usage
-
 ```bash
 skillcheck lint ./my-skill                 # one skill
 skillcheck lint ./skills                   # every SKILL.md under a tree
 skillcheck lint . --profile lenient        # client-guide severities
-skillcheck lint . --format concise        # one line per finding
-skillcheck lint . --format json
-skillcheck lint . --format github         # Actions inline annotations
-skillcheck lint . --format sarif          # SARIF 2.1.0 to stdout
-skillcheck lint . --sarif report.sarif    # sidecar SARIF alongside any format
-skillcheck lint . --fail-on warning       # stricter CI gate
+skillcheck lint . --format concise         # one line per finding
+skillcheck lint . --format json            # machine-readable
+skillcheck lint . --format sarif           # SARIF 2.1.0 to stdout
+skillcheck lint . --sarif report.sarif     # sidecar SARIF alongside any format
+skillcheck lint . --fail-on warning        # stricter CI gate
 skillcheck lint . --max-warnings 10
 
 skillcheck eval init ./my-skill            # scaffold evals/evals.json
 skillcheck eval check ./my-skill           # validate it
 ```
 
-Exit codes: `0` clean, `1` findings at/above `--fail-on`, `2` usage/internal error.
+Exit codes: `0` clean, `1` findings at or above `--fail-on`, `2` usage or internal error.
 
 ## GitHub Action
 
 ```yaml
-- uses: Sagargupta16/skillcheck@v0.2.0
-  with:
-    path: skills/
-    fail-on: error
-    sarif-file: skillcheck.sarif   # optional
-
-# optional: upload to code scanning (needs security-events: write)
-- uses: github/codeql-action/upload-sarif@v4
-  with:
-    sarif_file: skillcheck.sarif
-    category: skillcheck
+jobs:
+  skills:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: Sagargupta16/skillcheck@v0.2.0
+        with:
+          path: skills/
+          fail-on: error
+          sarif-file: skillcheck.sarif   # optional
+
+      # optional: upload to code scanning (needs security-events: write)
+      - uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: skillcheck.sarif
+          category: skillcheck
 ```
 
-Inline PR annotations come free via `--format github`; a full report lands in the job summary automatically.
+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`.
 
 ## Rules
 
-36 rules with stable codes (never renumbered or recycled) -- see [docs/rules.md](docs/rules.md) for the full table.
+36 rules with stable codes (never renumbered or recycled). Full reference: [docs/rules.md](docs/rules.md).
 
 | Range | Category | Examples |
 | --- | --- | --- |
@@ -80,9 +102,9 @@ Parity details worth knowing:
 - Strict-YAML semantics are enforced on top of the JS parser: flow collections, tags, and duplicate keys are rejected, like `strictyaml`.
 - 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).
 
-## Config
+## Configuration
 
-Optional `skillcheck.config.json`:
+Optional `skillcheck.config.json` in your project root:
 
 ```json
 {
@@ -93,16 +115,16 @@ Optional `skillcheck.config.json`:
 }
 ```
 
-Codes and aliases are interchangeable. Zero-config works.
+Codes and kebab-case aliases are interchangeable. Zero-config works.
 
 ## Evals (trigger tests)
 
-`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.
+`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.
 
 ## Roadmap
 
 - [x] **v0.1** -- static lint, two-tier severity
-- [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
+- [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
 - [ ] **v0.3** -- runtime execution: run trigger tests against Claude Code / OpenCode / Codex headlessly in Docker; `--fix` for safe fixes
 - [ ] **v1.0** -- public caniuse-style compatibility matrix + README badges
 
@@ -116,6 +138,8 @@ pnpm lint        # biome
 node dist/cli.js lint fixtures/valid-skill
 ```
 
+Contributions welcome -- see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## License
 
 [MIT](LICENSE)

package/dist/{chunk-MGSKVMAQ.js → chunk-X3UHBJW7.js}

@@ -1029,6 +1029,9 @@ async function lintSkillDir(dir, options = {}) {
       bundledFiles
     })
   );
+  findings.push(
+    ...await deepReferenceChains(skillDir, parsed.body, bundledFiles)
+  );
   const skillName = parsed.frontmatter && typeof parsed.frontmatter.name === "string" ? parsed.frontmatter.name.trim().normalize("NFKC") : null;
   return summarize(skillDir, skillName, applyOverrides(findings, options));
 }
@@ -1071,6 +1074,50 @@ function applyOverrides(findings, options) {
   }
   return out;
 }
+function extractReferences(body) {
+  const refs = /* @__PURE__ */ new Set();
+  for (const m of body.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
+    const target = (m[1] ?? "").split(/[#?]/)[0]?.trim() ?? "";
+    if (target) refs.add(target);
+  }
+  for (const m of body.matchAll(
+    /`((?:scripts|references|assets)\/[^\s`]+)`/g
+  )) {
+    refs.add((m[1] ?? "").trim());
+  }
+  return [...refs].filter(
+    (t) => !/^[a-z][a-z0-9+.-]*:\/\//i.test(t) && !t.startsWith("#") && !t.startsWith("mailto:") && !t.includes("${") && !t.includes("{{") && !/^(\/|[A-Za-z]:[\\/]|~\/)/.test(t)
+  );
+}
+async function deepReferenceChains(skillDir, body, bundledFiles) {
+  const findings = [];
+  const bundled = new Set(bundledFiles.map((f) => f.replace(/\\/g, "/")));
+  for (const ref of extractReferences(body)) {
+    const normalized = ref.replace(/^\.\//, "").replace(/\\/g, "/");
+    if (!normalized.endsWith(".md") || !bundled.has(normalized)) continue;
+    let childBody;
+    try {
+      childBody = await readFile2(join2(skillDir, normalized), "utf8");
+    } catch {
+      continue;
+    }
+    const childRefs = extractReferences(childBody).filter((t) => {
+      const childDir = normalized.includes("/") ? normalized.slice(0, normalized.lastIndexOf("/")) : "";
+      const resolved = t.startsWith("./") || !t.includes("/") ? `${childDir ? `${childDir}/` : ""}${t.replace(/^\.\//, "")}` : t;
+      return bundled.has(resolved.replace(/\\/g, "/"));
+    });
+    if (childRefs.length > 0) {
+      findings.push({
+        code: "SC103",
+        alias: "deep-reference-chain",
+        severity: "info",
+        message: `\`${normalized}\` references further bundled files (${childRefs.slice(0, 3).join(", ")}${childRefs.length > 3 ? ", ..." : ""}) -- spec recommends keeping references one level deep from SKILL.md`,
+        file: normalized
+      });
+    }
+  }
+  return findings;
+}
 async function listBundledFiles(skillDir) {
   const files = [];
   async function walk(dir, depth) {

package/dist/cli.js

@@ -5,14 +5,14 @@ import {
   initEvals,
   lintSkillDir,
   toSarif
-} from "./chunk-MGSKVMAQ.js";
+} from "./chunk-X3UHBJW7.js";
 
 // src/cli.ts
 import { appendFile, readFile, stat, writeFile } from "fs/promises";
 import { join } from "path";
 import { Command } from "commander";
 import { glob } from "glob";
-var VERSION = "0.2.0";
+var VERSION = "0.2.2";
 var program = new Command();
 program.name("skillcheck").description("Conformance suite for Agent Skills (SKILL.md)").version(VERSION);
 program.command("lint").description(
@@ -32,14 +32,27 @@ program.command("lint").description(
   "--fail-on <severity>",
   "minimum severity that fails: error | warning | never",
   "error"
-).option("--sarif <path>", "also write a SARIF 2.1.0 report to this path").option("--max-warnings <n>", "fail when warnings exceed this count").action(async (paths, opts) => {
-  const skillDirs = await expandSkillDirs(paths);
+).option("--sarif <path>", "also write a SARIF 2.1.0 report to this path").option("--max-warnings <n>", "fail when warnings exceed this count").option(
+  "--ignore-pattern <glob...>",
+  "glob(s) to exclude during discovery (adds to config ignore)"
+).action(async (paths, opts) => {
+  if (opts.strict && opts.profile === "lenient") {
+    console.error("--strict conflicts with --profile lenient; pick one");
+    process.exit(2);
+  }
+  if (opts.strict) {
+    console.error(
+      "warning: --strict is deprecated; strict is the default (use --profile)"
+    );
+  }
+  const config = await loadConfig();
+  const ignore = [...config?.ignore ?? [], ...opts.ignorePattern ?? []];
+  const skillDirs = await expandSkillDirs(paths, ignore);
   if (skillDirs.length === 0) {
     console.error("no SKILL.md found under the given paths");
     process.exit(2);
   }
   const profile = opts.profile === "lenient" ? "lenient" : "strict";
-  const config = await loadConfig();
   const results = [];
   for (const dir of skillDirs) {
     const result = await lintSkillDir(dir, {
@@ -103,7 +116,7 @@ async function loadConfig() {
     return null;
   }
 }
-async function expandSkillDirs(paths) {
+async function expandSkillDirs(paths, extraIgnore = []) {
   const dirs = /* @__PURE__ */ new Set();
   for (const p of paths) {
     if (await exists(join(p, "SKILL.md")) || await exists(join(p, "skill.md"))) {
@@ -112,7 +125,7 @@ async function expandSkillDirs(paths) {
     }
     const matches = await glob("**/{SKILL,skill}.md", {
       cwd: p,
-      ignore: ["**/node_modules/**", "**/.git/**"],
+      ignore: ["**/node_modules/**", "**/.git/**", ...extraIgnore],
       absolute: true
     });
     for (const m of matches) {

package/dist/index.js

@@ -10,7 +10,7 @@ import {
   lintSkillDir,
   parseSkillMd,
   toSarif
-} from "./chunk-MGSKVMAQ.js";
+} from "./chunk-X3UHBJW7.js";
 export {
   KNOWN_EXTENSIONS,
   RULES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagargupta1610/skillcheck",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Conformance suite for Agent Skills: lint SKILL.md against the spec, run it against real agent runtimes, publish a compatibility matrix",
   "keywords": [
     "agent-skills",