@weareikko/eslint-plugin-skill 0.0.1 → 0.1.1

package/docs/rules/description-has-trigger.md

@@ -0,0 +1,28 @@
+# skill/description-has-trigger
+
+Require the `description` to express *when* the skill applies, not just what it is.
+
+An agent routes to a skill purely from its description. A description that only states what the skill does, with no cue about when to reach for it, routes poorly. This rule checks for a trigger phrase such as "use when", "when the user", or "trigger". It is a `warn` by default because the phrasing is heuristic.
+
+## Fails
+
+```yaml
+description: A tool that formats code nicely.
+```
+
+## Passes
+
+```yaml
+description: Formats code. Use when the user asks to format a file.
+description: Runs the deploy. Trigger on deploy requests.
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `patterns` | string[] | `["use when", "use this when", "use for", "used when", "used for", "when the user", "when you", "when asked", "trigger", "invoke", "for when"]` | Case-insensitive substrings; the description must contain at least one. |
+
+```js
+"skill/description-has-trigger": ["warn", { patterns: ["use when", "trigger"] }]
+```

package/docs/rules/description-length.md

@@ -0,0 +1,27 @@
+# skill/description-length
+
+Cap the length of the skill `description`.
+
+The description is loaded into context for every routing decision. A bloated description wastes tokens and buries the signal that tells an agent when to use the skill. The default ceiling of 1024 characters mirrors the documented frontmatter budget.
+
+## Fails
+
+```yaml
+description: <a description longer than the configured maximum…>
+```
+
+## Passes
+
+```yaml
+description: Formats code. Use when the user asks to format a file.
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `max` | integer ≥ 1 | `1024` | Maximum allowed character count. |
+
+```js
+"skill/description-length": ["error", { max: 800 }]
+```

package/docs/rules/description-no-html.md

@@ -0,0 +1,22 @@
+# skill/description-no-html
+
+Disallow HTML/XML tags in the skill `description`.
+
+Descriptions are consumed as plain routing text. Embedded tags such as `<b>` or `<role>` add noise and can interfere with how the description is parsed and displayed. Plain comparisons like `3 < 5` are fine — the rule only flags actual tags (`<` immediately followed by a letter or `/`).
+
+## Fails
+
+```yaml
+description: Uses <b>bold</b> text. Use when needed.
+description: Self-closing <br/> tag.
+```
+
+## Passes
+
+```yaml
+description: Compares values where 3 < 5. Use when needed.
+```
+
+## Options
+
+None.

package/docs/rules/descriptive-reference-filenames.md

@@ -0,0 +1,26 @@
+# skill/descriptive-reference-filenames
+
+Require reference files (`.md` under `references/`) to have descriptive names.
+
+Claude decides whether to open a reference file partly from its filename, so a generic name like `doc2.md` or `untitled.md` carries no signal. Official guidance: name files descriptively — `form_validation_rules.md`, not `doc2.md`.
+
+Flags generic stems (`doc`, `ref`, `reference`, `file`, `page`, `untitled`, `temp`, `tmp`, `new`, `copy`, `note(s)`, `document`, optionally numbered) and bare numeric names (`1.md`).
+
+## Fails
+
+```
+references/doc2.md
+references/untitled.md
+references/1.md
+```
+
+## Passes
+
+```
+references/form_validation_rules.md
+references/ga4-setup.md
+```
+
+## Options
+
+None.

package/docs/rules/h1-matches-name.md

@@ -0,0 +1,36 @@
+# skill/h1-matches-name
+
+Require the body H1 to correspond to the skill `name`.
+
+> **Opt-in.** This rule is not part of the `recommended` or `strict` presets. The standard skill format does not require an H1, and the frontmatter `name` is a display label rather than the body title, so this convention is left to teams that deliberately adopt it.
+
+The title a reader sees should match the skill's identity. The comparison is normalized — lowercased, with runs of non-alphanumeric characters treated as spaces — so both `# my-skill` and `# My Skill` satisfy `name: my-skill`. Enable it explicitly:
+
+```js
+"skill/h1-matches-name": "warn"
+```
+
+## Fails
+
+```yaml
+name: my-skill
+```
+```md
+# Totally Different Title
+```
+
+## Passes
+
+```yaml
+name: my-skill
+```
+```md
+# my-skill
+```
+```md
+# My Skill
+```
+
+## Options
+
+None.

package/docs/rules/large-reference-toc.md

@@ -0,0 +1,26 @@
+# skill/large-reference-toc
+
+Require large reference files to include a table of contents.
+
+Official guidance: reference files over ~300 lines should carry a table of contents so Claude can jump to the relevant section instead of reading (or partially reading) the whole file.
+
+A file satisfies the rule if it has a `Contents` / `Table of Contents` heading **or** a cluster of in-page anchor links (≥ 3 links to `#...`).
+
+## Fails
+
+A `references/*.md` file longer than `maxLines` with no ToC heading and fewer than 3 anchor links.
+
+## Passes
+
+- A reference file at or under `maxLines`.
+- A large file with a `## Contents` heading or an anchor-link ToC.
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `maxLines` | integer ≥ 1 | `300` | Line count above which a ToC is required. |
+
+```js
+"skill/large-reference-toc": ["warn", { maxLines: 250 }]
+```

package/docs/rules/meta-prefers-dispatch-table.md

@@ -0,0 +1,30 @@
+# skill/meta-prefers-dispatch-table
+
+Suggest a markdown table for a `meta`-kind skill's dispatch/routing list.
+
+> **Opt-in, and evidence-lighter than the plugin's other rules.** Not part of any preset. Backed by a single empirical test — see [`docs/research/meta-dispatch-table-vs-prose.md`](../research/meta-dispatch-table-vs-prose.md) — not the multiply-corroborated evidence behind most other rules here.
+
+This rule only fires when the skill declares itself explicitly:
+
+```yaml
+metadata:
+  kind: meta
+```
+
+A meta (router) skill exists to dispatch requests to other skills. A one-scenario test (5 fictional skills, a fictional router, 6 blind trials) found a markdown table cost **~21% fewer tokens** than equivalent prose for this kind of dispatch content, with no measured routing-accuracy difference. This rule only checks whether the body contains a markdown table at all — it does not try to judge whether a table is semantically "needed," to avoid the false-positive risk of guessing at content meaning.
+
+## Fails
+
+A `metadata.kind: meta` skill whose body has no markdown table anywhere.
+
+## Passes
+
+A `metadata.kind: meta` skill whose body contains at least one markdown table.
+
+## Options
+
+None.
+
+## Why this rule is opt-in
+
+Every other kind-specific rule in this plugin traces to either an official, multiply-corroborated source or a comprehension test with an adversarial, multi-trial design. This one rests on a single router scenario in one domain pairing — real signal, but not yet replicated. Treat it as a cost-saving suggestion worth trying, not an established convention.

package/docs/rules/multi-domain-has-variants.md

@@ -0,0 +1,26 @@
+# skill/multi-domain-has-variants
+
+Expect a `multi-domain`-kind skill to carry at least two variant reference files.
+
+> **Opt-in.** Not part of any preset — see [Skill kinds](../design/skill-taxonomy-and-rules.md) for the taxonomy this rule is part of.
+
+This rule only fires when the skill declares itself explicitly:
+
+```yaml
+metadata:
+  kind: multi-domain
+```
+
+The multi-domain pattern (`SKILL.md` holding selection logic over `references/{aws,gcp,azure}.md`) only earns its complexity when there is more than one variant to select between. Fewer than two reference files means there's nothing to select — it's just a `reference` skill.
+
+## Fails
+
+A skill with `metadata.kind: multi-domain` and fewer than 2 files under `references/`.
+
+## Passes
+
+A skill with `metadata.kind: multi-domain` and 2 or more files under `references/` (e.g. `aws.md`, `gcp.md`).
+
+## Options
+
+None.

package/docs/rules/name-kebab-case.md

@@ -0,0 +1,31 @@
+# skill/name-kebab-case
+
+Require the skill `name` to be a valid Agent Skills identifier:
+
+- **Kebab-case**, matching `^[a-z][a-z0-9]*(-[a-z0-9]+)*$` (letter-start, lowercase, no underscores, no leading/trailing/consecutive hyphens).
+- **At most 64 characters** (the spec's hard limit).
+- **No reserved words** — the name must not contain `anthropic` or `claude`.
+
+Skill names double as directory names and identifiers. Keeping them lowercase-hyphenated makes them portable across filesystems and predictable to reference; the length and reserved-word limits come from the Agent Skills standard.
+
+## Fails
+
+```yaml
+name: Bad_Name          # underscores, uppercase
+name: 1-leading         # starts with a digit
+name: trailing-         # trailing hyphen
+name: claude-helper     # contains a reserved word
+name: aaaaaa…(>64)      # exceeds 64 characters
+```
+
+## Passes
+
+```yaml
+name: my-skill
+name: skill2-v2
+name: a
+```
+
+## Options
+
+None.

package/docs/rules/name-matches-dir.md

@@ -0,0 +1,29 @@
+# skill/name-matches-dir
+
+Require the skill `name` to equal the name of the directory that contains its `SKILL.md`.
+
+Claude Code discovers a skill by its folder. If the frontmatter `name` and the folder disagree, tooling and humans reference two different identities for the same skill.
+
+The rule is a no-op when the file has no resolvable directory (e.g. a bare `SKILL.md` with no parent folder).
+
+## Fails
+
+```
+skills/my-skill/SKILL.md
+```
+```yaml
+name: other-name
+```
+
+## Passes
+
+```
+skills/my-skill/SKILL.md
+```
+```yaml
+name: my-skill
+```
+
+## Options
+
+None.

package/docs/rules/no-broken-relative-links.md

@@ -0,0 +1,25 @@
+# skill/no-broken-relative-links
+
+Flag relative links and images in the body whose target does not exist on disk, relative to the skill's directory.
+
+Skills rely on referenced files for progressive disclosure. A dead relative link means the agent will try to open something that isn't there. Absolute URLs (`https:`, `mailto:`, `//host`) and pure anchors (`#section`) are ignored; URL fragments and query strings are stripped before the file is resolved.
+
+This is the only rule that touches the filesystem (`node:fs`), and it is a no-op when the file has no resolvable path.
+
+## Fails
+
+```md
+See [the guide](./missing.md).
+![diagram](./assets/gone.png)
+```
+
+## Passes
+
+```md
+See [the guide](./reference.md).
+[external](https://example.com) and [jump](#steps).
+```
+
+## Options
+
+None.

package/docs/rules/no-multiple-h1.md

@@ -0,0 +1,31 @@
+# skill/no-multiple-h1
+
+Disallow more than one top-level `#` H1 in the skill body.
+
+The standard skill format does **not** require an H1 — the official examples use `##`-first bodies — so this rule does not demand a title. What it catches is *two or more* `#` H1s in one body, which usually means separate documents were merged or headings were over-leveled. Each H1 after the first is reported.
+
+## Fails
+
+```md
+# one
+
+# two
+```
+
+## Passes
+
+```md
+# my-skill
+
+## a section
+```
+
+```md
+## Overview
+
+No H1 at all is fine.
+```
+
+## Options
+
+None.

package/docs/rules/no-orphan-references.md

@@ -0,0 +1,25 @@
+# skill/no-orphan-references
+
+Flag `.md` files under `references/` that nothing in `SKILL.md` links to.
+
+Claude loads reference files by following the pointers in `SKILL.md`, so a file in `references/` that isn't linked is never read — dead weight. It's usually a leftover, a rename that broke the link, or a pointer someone forgot to add. This is the inverse of [`no-broken-relative-links`](no-broken-relative-links.md) (which flags links with no file); this flags files with no link.
+
+Only runs when the skill has a `references/` directory on disk and a resolvable path.
+
+## Fails
+
+```
+my-skill/
+├── SKILL.md            # links references/setup.md only
+└── references/
+    ├── setup.md        # ok
+    └── leftover.md     # flagged — never linked
+```
+
+## Passes
+
+Every file under `references/` is linked from `SKILL.md`.
+
+## Options
+
+None.

package/docs/rules/no-unknown-frontmatter-keys.md

@@ -0,0 +1,37 @@
+# skill/no-unknown-frontmatter-keys
+
+Flag unknown top-level frontmatter keys on a skill.
+
+The Agent Skills standard defines a fixed set of frontmatter fields. An unexpected key is almost always a typo (`descriptoin:`) or a misplaced field — and because the runtime silently ignores unknown keys, the mistake never takes effect and is easy to miss. This rule surfaces it.
+
+Recognized keys: `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`, `when_to_use`, `disable-model-invocation`, plus the Claude Code extensions `argument-hint`, `model`, `context`.
+
+## Fails
+
+```yaml
+---
+name: demo
+descriptoin: a thing   # typo — silently ignored by the runtime
+---
+```
+
+## Passes
+
+```yaml
+---
+name: demo
+description: Does a thing. Use when needed.
+allowed-tools: [Bash]
+disable-model-invocation: true
+---
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `allow` | string[] | `[]` | Additional frontmatter keys to permit (e.g. a house-style field). |
+
+```js
+"skill/no-unknown-frontmatter-keys": ["error", { allow: ["audience"] }]
+```

package/docs/rules/procedural-has-steps.md

@@ -0,0 +1,43 @@
+# skill/procedural-has-steps
+
+Expect a `procedural`-kind skill's body to contain ordered steps.
+
+> **Opt-in.** Not part of any preset — see [Skill kinds](../design/skill-taxonomy-and-rules.md) for the taxonomy this rule is part of.
+
+This rule only fires when the skill declares itself explicitly:
+
+```yaml
+metadata:
+  kind: procedural
+```
+
+A procedural (task/workflow) skill exists to walk the agent through a sequence of actions. A declared procedural skill whose body has no ordered (numbered) list at all is either mis-declared or missing its steps — a bullet list doesn't count, since order matters for a procedure.
+
+## Fails
+
+```yaml
+metadata:
+  kind: procedural
+```
+```md
+# demo
+
+Just prose, no steps.
+```
+
+## Passes
+
+```yaml
+metadata:
+  kind: procedural
+```
+```md
+# demo
+
+1. Do the first thing.
+2. Do the second thing.
+```
+
+## Options
+
+None.

package/docs/rules/reference-has-content.md

@@ -0,0 +1,26 @@
+# skill/reference-has-content
+
+Expect a `reference`-kind skill to carry at least one reference file.
+
+> **Opt-in.** Not part of any preset — see [Skill kinds](../design/skill-taxonomy-and-rules.md) for the taxonomy this rule is part of.
+
+This rule only fires when the skill declares itself explicitly:
+
+```yaml
+metadata:
+  kind: reference
+```
+
+A reference (domain-knowledge) skill exists to supply background material on demand. A declared reference skill with an empty or missing `references/` directory has nothing to supply.
+
+## Fails
+
+A skill with `metadata.kind: reference` and no `.md` files under `references/`.
+
+## Passes
+
+A skill with `metadata.kind: reference` and at least one file under `references/`.
+
+## Options
+
+None.

package/docs/rules/refs-one-level-deep.md

@@ -0,0 +1,26 @@
+# skill/refs-one-level-deep
+
+Require reference links in `SKILL.md` to stay one level deep.
+
+Official guidance: every reference file should link **directly** from `SKILL.md` and live at most one directory below it. Deeply nested reference chains are an anti-pattern — when Claude reaches a file indirectly it may only partially read it (e.g. `head -100`), so it can act on incomplete information.
+
+Only relative links/images are checked; external URLs and `#anchors` are ignored.
+
+## Fails
+
+```md
+[deep](references/sub/setup.md)   # more than one directory deep
+[up](../shared/setup.md)          # points outside the skill directory
+```
+
+## Passes
+
+```md
+[ref](references/setup.md)
+[sibling](./notes.md)
+[external](https://example.com)
+```
+
+## Options
+
+None.

package/docs/rules/require-frontmatter.md

@@ -0,0 +1,34 @@
+# skill/require-frontmatter
+
+Require every `SKILL.md` to begin with YAML frontmatter that defines a non-empty `name` and `description`.
+
+These two fields are the contract of a skill: `name` identifies it and `description` is the only text an agent reads when deciding whether to load it. A skill missing either can't be routed to reliably.
+
+## Fails
+
+```md
+# just a heading, no frontmatter
+```
+
+```md
+---
+name: my-skill
+---
+
+# my-skill
+```
+
+## Passes
+
+```md
+---
+name: my-skill
+description: Formats code. Use when the user asks to format a file.
+---
+
+# my-skill
+```
+
+## Options
+
+None.

package/docs/rules/valid-allowed-tools.md

@@ -0,0 +1,27 @@
+# skill/valid-allowed-tools
+
+Validate the shape of the optional `allowed-tools` frontmatter field (a Claude Code extension to the Agent Skills standard).
+
+When present, `allowed-tools` must be a non-empty array of non-empty strings. An empty array grants the skill no tools at all — almost certainly not the intent, and easy to fix by just omitting the field. A non-array value is silently ignored by the runtime.
+
+## Fails
+
+```yaml
+allowed-tools: Bash        # not an array
+allowed-tools: []          # empty — grants nothing
+allowed-tools: [Bash, ""]  # empty entry
+```
+
+## Passes
+
+```yaml
+allowed-tools: [Bash, Read]
+```
+
+```yaml
+# field omitted entirely — unrestricted
+```
+
+## Options
+
+None.

package/package.json

@@ -1,15 +1,67 @@
 {
   "name": "@weareikko/eslint-plugin-skill",
-  "version": "0.0.1",
-  "description": "Placeholder release to set up npm trusted publishing. The first real release is 0.1.0.",
+  "version": "0.1.1",
+  "description": "ESLint plugin that lints Claude Code Agent Skills (SKILL.md) for quality — portable to oxlint.",
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "oxlint",
+    "claude",
+    "claude-code",
+    "skills",
+    "skill",
+    "markdown"
+  ],
+  "homepage": "https://github.com/weareikko/motto/tree/main/packages/eslint-plugin-skill#readme",
+  "bugs": {
+    "url": "https://github.com/weareikko/motto/issues"
+  },
   "license": "MIT",
   "author": "weareikko",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/weareikko/motto.git",
+    "url": "git+ssh://git@github.com/weareikko/motto.git",
     "directory": "packages/eslint-plugin-skill"
   },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./dedup": {
+      "types": "./dist/dedup/index.d.ts",
+      "default": "./dist/dedup/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "skill-check-refs": "dist/dedup/cli.js"
+  },
+  "files": [
+    "dist",
+    "configs",
+    "docs",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json --emitDeclarationOnly && chmod +x dist/dedup/cli.js",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "prepublishOnly": "npm run build && npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  },
+  "dependencies": {
+    "@eslint/markdown": "^8.0.3",
+    "yaml": "^2.9.0"
   }
 }