@weareikko/eslint-plugin-skill 0.0.1 → 0.1.1

package/dist/index.js

@@ -0,0 +1,1236 @@
+import markdown from "@eslint/markdown";
+import { parse } from "yaml";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+//#region src/utils/skill-file.ts
+/**
+* Helpers for recognizing and locating Claude Code skill files.
+*
+* Kept dependency-free and side-effect-free so the compiled output ports
+* cleanly to oxlint's ESLint-compatible JS plugin runtime.
+*/
+/**
+* The canonical filename of a Claude Code Agent Skill.
+*/
+var SKILL_FILENAME = "SKILL.md";
+/**
+* Extract the basename of a POSIX or Windows path without relying on `node:path`,
+* so the logic is identical regardless of the host runtime's path semantics.
+*/
+function basename$1(filename) {
+	if (typeof filename !== "string") return "";
+	const normalized = filename.replace(/\\/g, "/");
+	const trimmed = normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+	const slash = trimmed.lastIndexOf("/");
+	return slash === -1 ? trimmed : trimmed.slice(slash + 1);
+}
+/**
+* The name of the directory that directly contains the given file.
+*/
+function dirName(filename) {
+	if (typeof filename !== "string") return "";
+	const normalized = filename.replace(/\\/g, "/");
+	const trimmed = normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+	const slash = trimmed.lastIndexOf("/");
+	if (slash === -1) return "";
+	return basename$1(trimmed.slice(0, slash));
+}
+/**
+* Whether the linted file is a skill definition (`SKILL.md`).
+*
+* Rules call this first and no-op when it returns `false`, so the plugin is
+* safe even when its config globs every `*.md` file in a repository.
+*/
+function isSkillFile(filename) {
+	return basename$1(filename) === SKILL_FILENAME;
+}
+/**
+* Whether the linted file is a bundled reference document — a `.md` file
+* (other than `SKILL.md`) living under a `references/` directory.
+*/
+function isReferenceFile(filename) {
+	if (typeof filename !== "string" || !filename.endsWith(".md")) return false;
+	if (basename$1(filename) === "SKILL.md") return false;
+	return filename.replace(/\\/g, "/").split("/").includes("references");
+}
+//#endregion
+//#region src/utils/frontmatter.ts
+function parseFrontmatter(node) {
+	const raw = typeof node.value === "string" ? node.value : "";
+	const contentStartLine = (node.position?.start?.line ?? 1) + 1;
+	const nodeLoc = node.position ?? {
+		start: {
+			line: 1,
+			column: 1
+		},
+		end: {
+			line: 1,
+			column: 1
+		}
+	};
+	let data = null;
+	let error = null;
+	try {
+		const parsed = parse(raw);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) data = parsed;
+		else if (parsed === null || parsed === void 0) data = {};
+		else error = "frontmatter is not a key/value mapping";
+	} catch (e) {
+		error = e instanceof Error ? e.message : String(e);
+	}
+	const lines = raw.split("\n");
+	function keyLoc(key) {
+		const pattern = new RegExp(`^(\\s*)(${escapeRegExp(key)})\\s*:`);
+		for (let i = 0; i < lines.length; i++) {
+			const match = pattern.exec(lines[i]);
+			if (match) {
+				const line = contentStartLine + i;
+				const column = match[1].length + 1;
+				return {
+					start: {
+						line,
+						column
+					},
+					end: {
+						line,
+						column: column + key.length
+					}
+				};
+			}
+		}
+		return {
+			start: nodeLoc.start,
+			end: nodeLoc.end
+		};
+	}
+	return {
+		data,
+		error,
+		raw,
+		keyLoc
+	};
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+//#region src/utils/ast.ts
+/**
+* The frontmatter `yaml` node, if present as a direct child of root.
+*/
+function findFrontmatter(root) {
+	return root.children.find((child) => child.type === "yaml");
+}
+/**
+* All nodes of a given type anywhere in the tree, in document order.
+*/
+function collect(node, type) {
+	const out = [];
+	const walk = (current) => {
+		if (current.type === type) out.push(current);
+		if ("children" in current) for (const child of current.children) walk(child);
+	};
+	walk(node);
+	return out;
+}
+/**
+* Concatenated text content of a node's subtree.
+*/
+function textContent(node) {
+	if ("value" in node && typeof node.value === "string") return node.value;
+	if ("children" in node) return node.children.map((child) => textContent(child)).join("");
+	return "";
+}
+//#endregion
+//#region src/rules/require-frontmatter.ts
+var TOP$5 = {
+	start: {
+		line: 1,
+		column: 1
+	},
+	end: {
+		line: 1,
+		column: 1
+	}
+};
+var rule$19 = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Require `name` and `description` frontmatter on a skill",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/require-frontmatter.md"
+		},
+		schema: [],
+		messages: {
+			missingFrontmatter: "SKILL.md must start with YAML frontmatter containing `name` and `description`.",
+			invalidFrontmatter: "Skill frontmatter is not valid YAML: {{reason}}",
+			missingKey: "Skill frontmatter is missing a `{{key}}` field.",
+			emptyKey: "Skill frontmatter field `{{key}}` must not be empty."
+		}
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		return { root(root) {
+			const node = findFrontmatter(root);
+			if (!node) {
+				context.report({
+					loc: TOP$5,
+					messageId: "missingFrontmatter"
+				});
+				return;
+			}
+			const { data, error, keyLoc } = parseFrontmatter(node);
+			if (error || !data) {
+				context.report({
+					loc: node.position ?? TOP$5,
+					messageId: "invalidFrontmatter",
+					data: { reason: error ?? "unknown error" }
+				});
+				return;
+			}
+			for (const key of ["name", "description"]) {
+				if (!(key in data)) {
+					context.report({
+						loc: node.position ?? TOP$5,
+						messageId: "missingKey",
+						data: { key }
+					});
+					continue;
+				}
+				const value = data[key];
+				if (typeof value !== "string" || value.trim() === "") context.report({
+					loc: keyLoc(key),
+					messageId: "emptyKey",
+					data: { key }
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/rules/name-kebab-case.ts
+var KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+var MAX_LENGTH = 64;
+var RESERVED = ["anthropic", "claude"];
+var rule$18 = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Require the skill `name` to be a valid Agent Skills identifier",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/name-kebab-case.md"
+		},
+		schema: [],
+		messages: {
+			notKebab: "Skill `name` must be letter-start kebab-case (e.g. `my-skill`), got `{{name}}`.",
+			tooLong: "Skill `name` must be at most {{max}} characters; got {{length}}.",
+			reservedWord: "Skill `name` must not contain the reserved word `{{word}}`."
+		}
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		return { root(root) {
+			const node = findFrontmatter(root);
+			if (!node) return;
+			const { data, keyLoc } = parseFrontmatter(node);
+			if (!data || typeof data.name !== "string" || data.name === "") return;
+			const name = data.name;
+			const loc = keyLoc("name");
+			if (!KEBAB.test(name)) context.report({
+				loc,
+				messageId: "notKebab",
+				data: { name }
+			});
+			if (name.length > MAX_LENGTH) context.report({
+				loc,
+				messageId: "tooLong",
+				data: {
+					max: MAX_LENGTH,
+					length: name.length
+				}
+			});
+			const lowered = name.toLowerCase();
+			const reserved = RESERVED.find((word) => lowered.includes(word));
+			if (reserved) context.report({
+				loc,
+				messageId: "reservedWord",
+				data: { word: reserved }
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/rules/name-matches-dir.ts
+var rule$17 = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Require the skill `name` to match its containing directory",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/name-matches-dir.md"
+		},
+		schema: [],
+		messages: { mismatch: "Skill `name` (`{{name}}`) must match its directory name (`{{dir}}`)." }
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		const dir = dirName(context.filename);
+		if (!dir) return {};
+		return { root(root) {
+			const node = findFrontmatter(root);
+			if (!node) return;
+			const { data, keyLoc } = parseFrontmatter(node);
+			if (!data || typeof data.name !== "string" || data.name === "") return;
+			if (data.name !== dir) context.report({
+				loc: keyLoc("name"),
+				messageId: "mismatch",
+				data: {
+					name: data.name,
+					dir
+				}
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/rules/description-length.ts
+var DEFAULT_MAX = 1024;
+var rule$16 = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Cap the length of the skill `description`",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/description-length.md"
+		},
+		schema: [{
+			type: "object",
+			properties: { max: {
+				type: "integer",
+				minimum: 1
+			} },
+			additionalProperties: false
+		}],
+		messages: { tooLong: "Skill `description` is {{length}} characters; keep it at or under {{max}}." }
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		const max = context.options[0]?.max ?? DEFAULT_MAX;
+		return { root(root) {
+			const node = findFrontmatter(root);
+			if (!node) return;
+			const { data, keyLoc } = parseFrontmatter(node);
+			if (!data || typeof data.description !== "string") return;
+			const length = data.description.length;
+			if (length > max) context.report({
+				loc: keyLoc("description"),
+				messageId: "tooLong",
+				data: {
+					length,
+					max
+				}
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/rules/description-has-trigger.ts
+var DEFAULT_PATTERNS = [
+	"use when",
+	"use this when",
+	"use for",
+	"used when",
+	"used for",
+	"when the user",
+	"when you",
+	"when asked",
+	"trigger",
+	"invoke",
+	"for when"
+];
+var rule$15 = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Require the `description` to express when the skill applies",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/description-has-trigger.md"
+		},
+		schema: [{
+			type: "object",
+			properties: { patterns: {
+				type: "array",
+				items: { type: "string" },
+				minItems: 1
+			} },
+			additionalProperties: false
+		}],
+		messages: { noTrigger: "Skill `description` should state when to use the skill (e.g. a phrase like {{examples}})." }
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		const patterns = context.options[0]?.patterns ?? DEFAULT_PATTERNS;
+		const lowered = patterns.map((p) => p.toLowerCase());
+		return { root(root) {
+			const node = findFrontmatter(root);
+			if (!node) return;
+			const { data, keyLoc } = parseFrontmatter(node);
+			if (!data || typeof data.description !== "string" || data.description.trim() === "") return;
+			const haystack = data.description.toLowerCase();
+			if (!lowered.some((p) => haystack.includes(p))) context.report({
+				loc: keyLoc("description"),
+				messageId: "noTrigger",
+				data: { examples: patterns.slice(0, 2).map((p) => `"${p}"`).join(", ") }
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/rules/description-no-html.ts
+var TAG = /<\/?[a-zA-Z][^>]*>/;
+var rule$14 = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Disallow HTML/XML tags in the skill `description`",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/description-no-html.md"
+		},
+		schema: [],
+		messages: { hasTag: "Skill `description` must not contain HTML/XML tags (found `{{tag}}`)." }
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		return { root(root) {
+			const node = findFrontmatter(root);
+			if (!node) return;
+			const { data, keyLoc } = parseFrontmatter(node);
+			if (!data || typeof data.description !== "string") return;
+			const match = TAG.exec(data.description);
+			if (match) context.report({
+				loc: keyLoc("description"),
+				messageId: "hasTag",
+				data: { tag: match[0] }
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/rules/no-multiple-h1.ts
+var rule$13 = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Disallow more than one top-level H1 in the skill body",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/no-multiple-h1.md"
+		},
+		schema: [],
+		messages: { multiple: "Skill body must have at most one `#` H1 title; found {{count}}." }
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		return { root(root) {
+			const h1s = collect(root, "heading").filter((h) => h.depth === 1);
+			if (h1s.length > 1) {
+				for (const extra of h1s.slice(1)) if (extra.position) context.report({
+					loc: extra.position,
+					messageId: "multiple",
+					data: { count: h1s.length }
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/rules/h1-matches-name.ts
+function normalize(value) {
+	return value.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+var rule$12 = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Require the body H1 to correspond to the skill `name`",
+			recommended: false,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/h1-matches-name.md"
+		},
+		schema: [],
+		messages: { mismatch: "Body H1 (`{{title}}`) should correspond to the skill `name` (`{{name}}`)." }
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		return { root(root) {
+			const node = findFrontmatter(root);
+			if (!node) return;
+			const { data } = parseFrontmatter(node);
+			if (!data || typeof data.name !== "string" || data.name === "") return;
+			const h1 = collect(root, "heading").find((h) => h.depth === 1);
+			if (!h1 || !h1.position) return;
+			const title = textContent(h1).trim();
+			if (normalize(title) !== normalize(data.name)) context.report({
+				loc: h1.position,
+				messageId: "mismatch",
+				data: {
+					title,
+					name: data.name
+				}
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/rules/body-max-length.ts
+var DEFAULT_MAX_LINES$1 = 500;
+var rule$11 = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Keep the skill body short to preserve progressive disclosure",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/body-max-length.md"
+		},
+		schema: [{
+			type: "object",
+			properties: { maxLines: {
+				type: "integer",
+				minimum: 1
+			} },
+			additionalProperties: false
+		}],
+		messages: { tooLong: "Skill body is {{lines}} lines; keep it at or under {{max}} and move detail into referenced files." }
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		const max = context.options[0]?.maxLines ?? DEFAULT_MAX_LINES$1;
+		return { root(root) {
+			const totalLines = root.position?.end?.line ?? 0;
+			const fm = findFrontmatter(root);
+			const bodyStart = fm ? fm.position?.end?.line ?? 0 : 0;
+			const bodyLines = Math.max(0, totalLines - bodyStart);
+			if (bodyLines > max) context.report({
+				loc: {
+					start: {
+						line: bodyStart + 1,
+						column: 1
+					},
+					end: {
+						line: totalLines,
+						column: 1
+					}
+				},
+				messageId: "tooLong",
+				data: {
+					lines: bodyLines,
+					max
+				}
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/utils/links.ts
+/**
+* Whether a URL points at a repo-relative path (not an anchor, scheme, or
+* protocol-relative URL).
+*/
+function isRelativeUrl(url) {
+	if (!url || url.startsWith("#")) return false;
+	if (url.startsWith("//") || /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(url)) return false;
+	return true;
+}
+/**
+* Strip a URL's fragment and query so it can be resolved to a filesystem path.
+*/
+function urlToPath(url) {
+	let path = url;
+	const hash = path.indexOf("#");
+	if (hash !== -1) path = path.slice(0, hash);
+	const query = path.indexOf("?");
+	if (query !== -1) path = path.slice(0, query);
+	try {
+		return decodeURIComponent(path);
+	} catch {
+		return path;
+	}
+}
+/**
+* All link and image targets in the tree, in document order.
+*/
+function collectLinkTargets(root) {
+	return [...collect(root, "link").map((node) => ({
+		url: node.url,
+		kind: "link",
+		node
+	})), ...collect(root, "image").map((node) => ({
+		url: node.url,
+		kind: "image",
+		node
+	}))];
+}
+//#endregion
+//#region src/utils/skill-fs.ts
+/**
+* The file access seam of the rules that look past the linted file
+* (`no-broken-relative-links`, `no-orphan-references`, the `kind` rules).
+*
+* By default they read the disk. A host that keeps its skills somewhere else
+* (a database, a remote store) passes every file of the linted skills in the
+* shared setting `settings.skill.files` — a map from path to content — and
+* lints them in memory with ESLint's `Linter`. The paths are resolved like
+* the linted `filename`, so `/skills/demo/SKILL.md` and
+* `/skills/demo/references/a.md` are siblings exactly as on disk. A flat
+* config matches only files under the `Linter`'s `cwd`, so pass the virtual
+* root as `cwd` (`new Linter({ cwd: "/skills" })`).
+*/
+function diskMarkdownFilesUnder(dir) {
+	if (!existsSync(dir)) return [];
+	const out = [];
+	const walk = (current) => {
+		let entries;
+		try {
+			entries = readdirSync(current, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const full = join(current, entry.name);
+			if (entry.isDirectory()) walk(full);
+			else if (entry.isFile() && entry.name.endsWith(".md")) out.push(full);
+		}
+	};
+	walk(dir);
+	return out;
+}
+var diskFs = {
+	exists: existsSync,
+	markdownFilesUnder: diskMarkdownFilesUnder
+};
+/** A file system over an in-memory map of path → content. */
+function memoryFs(files) {
+	const paths = Object.keys(files).map((path) => resolve(path));
+	const under = (dir) => {
+		const prefix = resolve(dir) + sep;
+		return paths.filter((path) => path.startsWith(prefix));
+	};
+	return {
+		exists: (path) => {
+			const target = resolve(path);
+			return paths.includes(target) || under(target).length > 0;
+		},
+		markdownFilesUnder: (dir) => under(dir).filter((path) => path.endsWith(".md"))
+	};
+}
+/** The file system a rule must use, chosen from the shared settings. */
+function skillFs(settings) {
+	const files = (settings?.skill)?.files;
+	return files ? memoryFs(files) : diskFs;
+}
+//#endregion
+//#region src/rules/no-broken-relative-links.ts
+/**
+* @fileoverview Flag relative links/images whose target does not exist.
+*
+* Skills lean 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:`) and pure anchors (`#section`) are ignored.
+*/
+var rule$10 = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Flag relative links/images whose target does not exist",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/no-broken-relative-links.md"
+		},
+		schema: [],
+		messages: { broken: "Relative {{kind}} target `{{url}}` does not exist relative to this skill." }
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		const baseDir = dirname(context.filename);
+		if (!baseDir || baseDir === "." || context.filename === "<input>") return {};
+		const fs = skillFs(context.settings);
+		return { root(root) {
+			for (const { node, kind, url } of collectLinkTargets(root)) {
+				if (!isRelativeUrl(url) || !node.position) continue;
+				const target = resolve(baseDir, urlToPath(url));
+				if (!fs.exists(target)) context.report({
+					loc: node.position,
+					messageId: "broken",
+					data: {
+						kind,
+						url
+					}
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/rules/no-unknown-frontmatter-keys.ts
+var KNOWN_KEYS = /* @__PURE__ */ new Set([
+	"name",
+	"description",
+	"license",
+	"compatibility",
+	"metadata",
+	"allowed-tools",
+	"when_to_use",
+	"disable-model-invocation",
+	"argument-hint",
+	"model",
+	"context"
+]);
+var rule$9 = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Flag unknown top-level frontmatter keys on a skill",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/no-unknown-frontmatter-keys.md"
+		},
+		schema: [{
+			type: "object",
+			properties: { allow: {
+				type: "array",
+				items: { type: "string" }
+			} },
+			additionalProperties: false
+		}],
+		messages: { unknownKey: "Unknown frontmatter key `{{key}}` — likely a typo or an ignored field." }
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		const allow = new Set(context.options[0]?.allow ?? []);
+		return { root(root) {
+			const node = findFrontmatter(root);
+			if (!node) return;
+			const { data, keyLoc } = parseFrontmatter(node);
+			if (!data) return;
+			for (const key of Object.keys(data)) {
+				if (KNOWN_KEYS.has(key) || allow.has(key)) continue;
+				context.report({
+					loc: keyLoc(key),
+					messageId: "unknownKey",
+					data: { key }
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/rules/refs-one-level-deep.ts
+var rule$8 = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Require reference links to stay one level deep from SKILL.md",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/refs-one-level-deep.md"
+		},
+		schema: [],
+		messages: {
+			tooDeep: "Reference `{{url}}` is more than one directory deep; keep reference files one level below SKILL.md.",
+			escapes: "Reference `{{url}}` points outside the skill directory; keep reference files one level below SKILL.md."
+		}
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		return { root(root) {
+			for (const { node, url } of collectLinkTargets(root)) {
+				if (!isRelativeUrl(url) || !node.position) continue;
+				const dirs = urlToPath(url).split("/").filter((s) => s && s !== ".").slice(0, -1);
+				if (dirs.includes("..")) context.report({
+					loc: node.position,
+					messageId: "escapes",
+					data: { url }
+				});
+				else if (dirs.length > 1) context.report({
+					loc: node.position,
+					messageId: "tooDeep",
+					data: { url }
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/utils/references.ts
+/**
+* Shared helpers for a skill's `references/` directory.
+*/
+/** Every `.md` file under a skill's `references/` directory, recursively. */
+function referenceMarkdownFiles(skillDir, fs) {
+	return fs.markdownFilesUnder(join(skillDir, "references"));
+}
+//#endregion
+//#region src/rules/no-orphan-references.ts
+/**
+* @fileoverview Flag reference files not linked from SKILL.md.
+*
+* A `.md` file sitting in `references/` that nothing in SKILL.md links to is
+* dead weight: Claude is told to load reference files via the pointers in
+* SKILL.md, so an unlinked one is never read. It's usually a leftover, a
+* rename that broke the link, or a missing pointer.
+*/
+var TOP$4 = {
+	start: {
+		line: 1,
+		column: 1
+	},
+	end: {
+		line: 1,
+		column: 1
+	}
+};
+var rule$7 = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Flag reference files not linked from SKILL.md",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/no-orphan-references.md"
+		},
+		schema: [],
+		messages: { orphan: "Reference file `{{file}}` is not linked from SKILL.md and will never be read." }
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		const skillDir = dirname(context.filename);
+		const files = referenceMarkdownFiles(skillDir, skillFs(context.settings));
+		if (!skillDir || skillDir === "." || context.filename === "<input>" || files.length === 0) return {};
+		return { root(root) {
+			const linked = new Set(collectLinkTargets(root).filter(({ url }) => isRelativeUrl(url)).map(({ url }) => resolve(skillDir, urlToPath(url))));
+			for (const file of files) if (!linked.has(file)) context.report({
+				loc: TOP$4,
+				messageId: "orphan",
+				data: { file: relative(skillDir, file) }
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/rules/descriptive-reference-filenames.ts
+var GENERIC = /^(docs?|references?|files?|pages?|untitled|temp|tmp|new|copy|notes?|documents?)[-_ ]?\d*$/i;
+var NUMERIC = /^\d+$/;
+var rule$6 = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Require reference files to have descriptive names",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/descriptive-reference-filenames.md"
+		},
+		schema: [],
+		messages: { generic: "Reference file `{{name}}` has a generic name; use a descriptive one (e.g. `form_validation_rules.md`)." }
+	},
+	create(context) {
+		if (!isReferenceFile(context.filename)) return {};
+		const name = basename$1(context.filename);
+		const stem = name.replace(/\.md$/i, "");
+		return { root() {
+			if (GENERIC.test(stem) || NUMERIC.test(stem)) context.report({
+				loc: {
+					start: {
+						line: 1,
+						column: 1
+					},
+					end: {
+						line: 1,
+						column: 1
+					}
+				},
+				messageId: "generic",
+				data: { name }
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/rules/large-reference-toc.ts
+var DEFAULT_MAX_LINES = 300;
+var TOC_HEADING = /^(table of contents|contents|toc)$/i;
+var rule$5 = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Require large reference files to include a table of contents",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/large-reference-toc.md"
+		},
+		schema: [{
+			type: "object",
+			properties: { maxLines: {
+				type: "integer",
+				minimum: 1
+			} },
+			additionalProperties: false
+		}],
+		messages: { missingToc: "Reference file is {{lines}} lines; add a table of contents (over {{max}} lines)." }
+	},
+	create(context) {
+		if (!isReferenceFile(context.filename)) return {};
+		const max = context.options[0]?.maxLines ?? DEFAULT_MAX_LINES;
+		return { root(root) {
+			const lines = root.position?.end?.line ?? 0;
+			if (lines <= max) return;
+			const hasTocHeading = collect(root, "heading").some((h) => TOC_HEADING.test(textContent(h).trim()));
+			const hasAnchorToc = collect(root, "link").filter((n) => n.url.startsWith("#")).length >= 3;
+			if (!hasTocHeading && !hasAnchorToc) context.report({
+				loc: {
+					start: {
+						line: 1,
+						column: 1
+					},
+					end: {
+						line: 1,
+						column: 1
+					}
+				},
+				messageId: "missingToc",
+				data: {
+					lines,
+					max
+				}
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/rules/valid-allowed-tools.ts
+var rule$4 = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Validate the shape of the optional `allowed-tools` frontmatter field",
+			recommended: true,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/valid-allowed-tools.md"
+		},
+		schema: [],
+		messages: {
+			notArray: "`allowed-tools` must be an array of tool names.",
+			empty: "`allowed-tools` must not be empty; omit the field to allow all tools.",
+			invalidEntry: "`allowed-tools` entries must be non-empty strings."
+		}
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		return { root(root) {
+			const node = findFrontmatter(root);
+			if (!node) return;
+			const { data, keyLoc } = parseFrontmatter(node);
+			if (!data || !("allowed-tools" in data)) return;
+			const value = data["allowed-tools"];
+			const loc = keyLoc("allowed-tools");
+			if (!Array.isArray(value)) {
+				context.report({
+					loc,
+					messageId: "notArray"
+				});
+				return;
+			}
+			if (value.length === 0) {
+				context.report({
+					loc,
+					messageId: "empty"
+				});
+				return;
+			}
+			if (value.some((v) => typeof v !== "string" || v.trim() === "")) context.report({
+				loc,
+				messageId: "invalidEntry"
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/utils/kind.ts
+/**
+* Skill KIND: a taxonomy for applying different lint expectations to
+* different shapes of skill.
+*
+* Grounded in official Claude Code guidance, which distinguishes "Reference
+* content" (inline domain knowledge) from "Task content" (step-by-step
+* actions, often gated with `disable-model-invocation`), plus the
+* `skill-creator` meta-skill's multi-domain/variant pattern
+* (`references/{aws,gcp,azure}.md`). `tool-wrapper` and `meta` are defensible
+* extensions, not explicitly named in any single source — see
+* docs/design/skill-taxonomy-and-rules.md.
+*
+* A skill may declare its kind explicitly via `metadata.kind` in frontmatter;
+* this is the only signal the lint rules act on, since heuristic detection is
+* inherently fuzzy and a wrong guess should never cause a false positive.
+* `detectKind` is exposed separately as an informative, best-effort signal —
+* it never gates a rule.
+*/
+var SKILL_KINDS = [
+	"procedural",
+	"reference",
+	"multi-domain",
+	"tool-wrapper",
+	"meta"
+];
+function isSkillKind(value) {
+	return typeof value === "string" && SKILL_KINDS.includes(value);
+}
+/**
+* The skill's explicitly declared kind, via `metadata.kind` in frontmatter.
+* Returns `undefined` when absent, malformed, or not a recognized kind.
+*/
+function declaredKind(data) {
+	const metadata = data?.metadata;
+	if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) return;
+	const kind = metadata.kind;
+	return isSkillKind(kind) ? kind : void 0;
+}
+//#endregion
+//#region src/rules/procedural-has-steps.ts
+var TOP$3 = {
+	start: {
+		line: 1,
+		column: 1
+	},
+	end: {
+		line: 1,
+		column: 1
+	}
+};
+var rule$3 = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Expect a procedural skill's body to contain ordered steps",
+			recommended: false,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/procedural-has-steps.md"
+		},
+		schema: [],
+		messages: { noSteps: "Skill is declared `metadata.kind: procedural` but its body has no ordered/numbered steps." }
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		return { root(root) {
+			const node = findFrontmatter(root);
+			if (!node) return;
+			const { data } = parseFrontmatter(node);
+			if (declaredKind(data) !== "procedural") return;
+			if (!collect(root, "list").some((list) => list.ordered)) context.report({
+				loc: TOP$3,
+				messageId: "noSteps"
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/rules/reference-has-content.ts
+/**
+* @fileoverview Expect a reference skill to carry at least one reference file.
+*
+* Opt-in: only fires when the skill explicitly declares itself as
+* `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.
+*/
+var TOP$2 = {
+	start: {
+		line: 1,
+		column: 1
+	},
+	end: {
+		line: 1,
+		column: 1
+	}
+};
+var rule$2 = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Expect a reference skill to carry at least one reference file",
+			recommended: false,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/reference-has-content.md"
+		},
+		schema: [],
+		messages: { noReferences: "Skill is declared `metadata.kind: reference` but its `references/` directory is empty or missing." }
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		const skillDir = dirname(context.filename);
+		if (!skillDir || skillDir === "." || context.filename === "<input>") return {};
+		return { root(root) {
+			const node = findFrontmatter(root);
+			if (!node) return;
+			const { data } = parseFrontmatter(node);
+			if (declaredKind(data) !== "reference") return;
+			if (referenceMarkdownFiles(skillDir, skillFs(context.settings)).length === 0) context.report({
+				loc: TOP$2,
+				messageId: "noReferences"
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/rules/multi-domain-has-variants.ts
+/**
+* @fileoverview Expect a multi-domain skill to carry at least two variant references.
+*
+* Opt-in: only fires when the skill explicitly declares itself as
+* `metadata.kind: multi-domain`. The multi-domain pattern (e.g.
+* `references/{aws,gcp,azure}.md`, with `SKILL.md` holding the selection
+* logic) only earns its complexity when there is more than one variant to
+* select between.
+*/
+var TOP$1 = {
+	start: {
+		line: 1,
+		column: 1
+	},
+	end: {
+		line: 1,
+		column: 1
+	}
+};
+var MIN_VARIANTS = 2;
+var rule$1 = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Expect a multi-domain skill to carry at least two variant references",
+			recommended: false,
+			url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/multi-domain-has-variants.md"
+		},
+		schema: [],
+		messages: { tooFewVariants: "Skill is declared `metadata.kind: multi-domain` but has fewer than {{min}} reference files to select between." }
+	},
+	create(context) {
+		if (!isSkillFile(context.filename)) return {};
+		const skillDir = dirname(context.filename);
+		if (!skillDir || skillDir === "." || context.filename === "<input>") return {};
+		return { root(root) {
+			const node = findFrontmatter(root);
+			if (!node) return;
+			const { data } = parseFrontmatter(node);
+			if (declaredKind(data) !== "multi-domain") return;
+			if (referenceMarkdownFiles(skillDir, skillFs(context.settings)).length < MIN_VARIANTS) context.report({
+				loc: TOP$1,
+				messageId: "tooFewVariants",
+				data: { min: MIN_VARIANTS }
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/rules/meta-prefers-dispatch-table.ts
+var TOP = {
+	start: {
+		line: 1,
+		column: 1
+	},
+	end: {
+		line: 1,
+		column: 1
+	}
+};
+//#endregion
+//#region src/index.ts
+/**
+* @weareikko/eslint-plugin-skill — lint Claude Code Agent Skills (`SKILL.md`).
+*
+* The plugin exposes a set of rules plus two ready-to-use flat configs. Each
+* config is self-contained: it targets `**​/SKILL.md`, wires up the
+* `@eslint/markdown` language with YAML frontmatter, and turns on the rules.
+*/
+var plugin = {
+	meta: {
+		name: "@weareikko/eslint-plugin-skill",
+		version: "0.1.1"
+	},
+	rules: {
+		"require-frontmatter": rule$19,
+		"name-kebab-case": rule$18,
+		"name-matches-dir": rule$17,
+		"description-length": rule$16,
+		"description-has-trigger": rule$15,
+		"description-no-html": rule$14,
+		"no-multiple-h1": rule$13,
+		"h1-matches-name": rule$12,
+		"body-max-length": rule$11,
+		"no-broken-relative-links": rule$10,
+		"no-unknown-frontmatter-keys": rule$9,
+		"refs-one-level-deep": rule$8,
+		"no-orphan-references": rule$7,
+		"descriptive-reference-filenames": rule$6,
+		"large-reference-toc": rule$5,
+		"valid-allowed-tools": rule$4,
+		"procedural-has-steps": rule$3,
+		"reference-has-content": rule$2,
+		"multi-domain-has-variants": rule$1,
+		"meta-prefers-dispatch-table": {
+			meta: {
+				type: "suggestion",
+				docs: {
+					description: "Suggest a markdown table for a meta/router skill's dispatch list",
+					recommended: false,
+					url: "https://github.com/weareikko/motto/blob/main/packages/eslint-plugin-skill/docs/rules/meta-prefers-dispatch-table.md"
+				},
+				schema: [],
+				messages: { preferTable: "Skill is declared `metadata.kind: meta` with no markdown table; consider a table for the dispatch list — measured ~21% cheaper than prose with no accuracy difference (see docs/research/meta-dispatch-table-vs-prose.md)." }
+			},
+			create(context) {
+				if (!isSkillFile(context.filename)) return {};
+				return { root(root) {
+					const node = findFrontmatter(root);
+					if (!node) return;
+					const { data } = parseFrontmatter(node);
+					if (declaredKind(data) !== "meta") return;
+					if (collect(root, "table").length === 0) context.report({
+						loc: TOP,
+						messageId: "preferTable"
+					});
+				} };
+			}
+		}
+	},
+	configs: {}
+};
+/**
+* Rule severities for the `recommended` preset. `warn` marks quality signals
+* that shouldn't necessarily fail CI; `strict` promotes them to `error`.
+*/
+var RECOMMENDED_RULES = {
+	"skill/require-frontmatter": "error",
+	"skill/name-kebab-case": "error",
+	"skill/name-matches-dir": "error",
+	"skill/description-length": "error",
+	"skill/description-no-html": "error",
+	"skill/no-multiple-h1": "error",
+	"skill/no-broken-relative-links": "error",
+	"skill/no-unknown-frontmatter-keys": "error",
+	"skill/refs-one-level-deep": "error",
+	"skill/valid-allowed-tools": "error",
+	"skill/description-has-trigger": "warn",
+	"skill/body-max-length": "warn",
+	"skill/no-orphan-references": "warn",
+	"skill/descriptive-reference-filenames": "warn",
+	"skill/large-reference-toc": "warn"
+};
+var STRICT_RULES = Object.fromEntries(Object.keys(RECOMMENDED_RULES).map((id) => [id, "error"]));
+function makeConfig(name, rules) {
+	return {
+		name,
+		files: ["**/SKILL.md", "**/references/**/*.md"],
+		plugins: {
+			markdown,
+			skill: plugin
+		},
+		language: "markdown/gfm",
+		languageOptions: { frontmatter: "yaml" },
+		rules
+	};
+}
+plugin.configs.recommended = makeConfig("skill/recommended", RECOMMENDED_RULES);
+plugin.configs.strict = makeConfig("skill/strict", STRICT_RULES);
+//#endregion
+export { plugin as default };
+
+//# sourceMappingURL=index.js.map