skill-check 0.1.0

package/dist/core/rule-engine.js

@@ -0,0 +1,52 @@
+import { isAllowlisted } from './allowlist.js';
+function resolveRuleLevel(config, ruleId, fallback) {
+    const override = config.rules[ruleId];
+    if (override)
+        return override;
+    return fallback;
+}
+export async function runRuleEngine(skills, rules, config) {
+    const diagnostics = [];
+    const context = {
+        config,
+        resolveRuleLevel: (ruleId, fallback) => resolveRuleLevel(config, ruleId, fallback),
+    };
+    for (const skill of skills) {
+        for (const rule of rules) {
+            const level = resolveRuleLevel(config, rule.id, rule.defaultSeverity);
+            if (level === 'off')
+                continue;
+            const findings = await rule.evaluate(skill, context);
+            if (!findings || findings.length === 0)
+                continue;
+            for (const finding of findings) {
+                if (isAllowlisted(skill.id, config.allowlist)) {
+                    continue;
+                }
+                let severity = finding.severity ?? (level === 'error' ? 'error' : 'warn');
+                if (config.strictMode && severity === 'warn') {
+                    severity = 'error';
+                }
+                diagnostics.push({
+                    ruleId: rule.id,
+                    severity,
+                    message: finding.message,
+                    file: skill.relativePath,
+                    line: finding.line ?? 1,
+                    column: finding.column ?? 1,
+                    suggestion: finding.suggestion,
+                });
+            }
+        }
+    }
+    diagnostics.sort((a, b) => {
+        if (a.file !== b.file)
+            return a.file.localeCompare(b.file);
+        if (a.line !== b.line)
+            return a.line - b.line;
+        if (a.column !== b.column)
+            return a.column - b.column;
+        return a.ruleId.localeCompare(b.ruleId);
+    });
+    return diagnostics;
+}

package/dist/core/sarif.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisResult } from '../types.js';
+export declare function toSarif(result: AnalysisResult): Record<string, unknown>;

package/dist/core/sarif.js

@@ -0,0 +1,48 @@
+export function toSarif(result) {
+    const rulesMap = new Map();
+    for (const diagnostic of result.diagnostics) {
+        if (!rulesMap.has(diagnostic.ruleId)) {
+            rulesMap.set(diagnostic.ruleId, {
+                id: diagnostic.ruleId,
+                shortDescription: {
+                    text: diagnostic.ruleId,
+                },
+            });
+        }
+    }
+    return {
+        version: '2.1.0',
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'skill-check',
+                        informationUri: 'https://github.com/thedaviddias/skill-check',
+                        rules: Array.from(rulesMap.values()),
+                    },
+                },
+                results: result.diagnostics.map((diagnostic) => ({
+                    ruleId: diagnostic.ruleId,
+                    level: diagnostic.severity === 'error' ? 'error' : 'warning',
+                    message: {
+                        text: diagnostic.message,
+                    },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: {
+                                    uri: diagnostic.file,
+                                },
+                                region: {
+                                    startLine: diagnostic.line,
+                                    startColumn: diagnostic.column,
+                                },
+                            },
+                        },
+                    ],
+                })),
+            },
+        ],
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { analyze, resolveExitCode } from './core/analyze.js';
+export type { BaselineDiff } from './core/baseline.js';
+export { diffBaseline, loadBaseline } from './core/baseline.js';
+export { resolveConfig } from './core/config.js';
+export { detectDuplicates } from './core/duplicates.js';
+export { toGitHubAnnotations } from './core/github-formatter.js';
+export { renderHtml } from './core/html-report.js';
+export type { SkillScore } from './core/quality-score.js';
+export { computeSkillScores } from './core/quality-score.js';
+export { coreRules } from './rules/core/index.js';
+export type { AnalysisResult, CliOptions, Diagnostic, PluginModule, ResolvedConfig, RuleDefinition, RuleFinding, Severity, SkillArtifact, } from './types.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { analyze, resolveExitCode } from './core/analyze.js';
+export { diffBaseline, loadBaseline } from './core/baseline.js';
+export { resolveConfig } from './core/config.js';
+export { detectDuplicates } from './core/duplicates.js';
+export { toGitHubAnnotations } from './core/github-formatter.js';
+export { renderHtml } from './core/html-report.js';
+export { computeSkillScores } from './core/quality-score.js';
+export { coreRules } from './rules/core/index.js';

package/dist/rules/core/body.d.ts

@@ -0,0 +1,2 @@
+import type { RuleDefinition } from '../../types.js';
+export declare const bodyRules: RuleDefinition[];

package/dist/rules/core/body.js

@@ -0,0 +1,39 @@
+function estimateTokens(text) {
+    return text.split(/\s+/).filter(Boolean).length;
+}
+export const bodyRules = [
+    {
+        id: 'body.max_lines',
+        description: 'Body should stay within configured line limit.',
+        defaultSeverity: 'error',
+        evaluate(skill, context) {
+            const lines = skill.body.split(/\r?\n/).length;
+            const max = context.config.limits.maxBodyLines;
+            if (lines <= max)
+                return [];
+            return [
+                {
+                    message: `body lines ${lines} exceeds max ${max}`,
+                    suggestion: `Reduce body to ${max} lines or fewer.`,
+                },
+            ];
+        },
+    },
+    {
+        id: 'body.max_tokens',
+        description: 'Body should stay within configured token limit.',
+        defaultSeverity: 'warn',
+        evaluate(skill, context) {
+            const tokens = estimateTokens(skill.body);
+            const max = context.config.limits.maxBodyTokens;
+            if (tokens <= max)
+                return [];
+            return [
+                {
+                    message: `body token estimate ${tokens} exceeds max ${max}`,
+                    suggestion: `Reduce body to ~${max} tokens or fewer. Token count is a whitespace-split approximation.`,
+                },
+            ];
+        },
+    },
+];

package/dist/rules/core/description.d.ts

@@ -0,0 +1,2 @@
+import type { RuleDefinition } from '../../types.js';
+export declare const descriptionRules: RuleDefinition[];

package/dist/rules/core/description.js

@@ -0,0 +1,66 @@
+function getDescription(skill) {
+    if (!skill.frontmatter)
+        return '';
+    const value = skill.frontmatter.description;
+    if (typeof value !== 'string')
+        return '';
+    return value.trim();
+}
+export const descriptionRules = [
+    {
+        id: 'description.max_length',
+        description: 'Description must be within configured max length.',
+        defaultSeverity: 'error',
+        evaluate(skill, context) {
+            const description = getDescription(skill);
+            if (!description)
+                return [];
+            const max = context.config.limits.maxDescriptionChars;
+            if (description.length <= max)
+                return [];
+            return [
+                {
+                    message: `description length ${description.length} exceeds max ${max}`,
+                    suggestion: `Shorten description to ${max} characters or fewer.`,
+                },
+            ];
+        },
+    },
+    {
+        id: 'description.use_when_phrase',
+        description: 'Description should include "Use when" phrasing.',
+        defaultSeverity: 'warn',
+        evaluate(skill) {
+            const description = getDescription(skill);
+            if (!description)
+                return [];
+            if (/\buse\s+when\b/i.test(description))
+                return [];
+            return [
+                {
+                    message: 'description should contain "Use when" phrasing',
+                    suggestion: 'Start description with "Use when" to help agents match this skill to user intent.',
+                },
+            ];
+        },
+    },
+    {
+        id: 'description.min_recommended_length',
+        description: 'Description should meet recommended minimum length.',
+        defaultSeverity: 'warn',
+        evaluate(skill, context) {
+            const description = getDescription(skill);
+            if (!description)
+                return [];
+            const min = context.config.limits.minDescriptionChars;
+            if (description.length >= min)
+                return [];
+            return [
+                {
+                    message: `description is short (${description.length} chars), recommended min is ${min}`,
+                    suggestion: `Add more detail about when and why an agent should use this skill.`,
+                },
+            ];
+        },
+    },
+];

package/dist/rules/core/file.d.ts

@@ -0,0 +1,2 @@
+import type { RuleDefinition } from '../../types.js';
+export declare const fileRules: RuleDefinition[];

package/dist/rules/core/file.js

@@ -0,0 +1,26 @@
+export const fileRules = [
+    {
+        id: 'file.trailing_newline_single',
+        description: 'File should end with exactly one trailing newline.',
+        defaultSeverity: 'warn',
+        evaluate(skill) {
+            if (!skill.content.endsWith('\n')) {
+                return [
+                    {
+                        message: 'file should end with a newline',
+                        suggestion: 'Add a single newline at the end of the file.',
+                    },
+                ];
+            }
+            if (skill.content.endsWith('\n\n')) {
+                return [
+                    {
+                        message: 'file has multiple trailing newlines; use a single newline',
+                        suggestion: 'Remove extra blank lines at the end of the file.',
+                    },
+                ];
+            }
+            return [];
+        },
+    },
+];

package/dist/rules/core/frontmatter.d.ts

@@ -0,0 +1,2 @@
+import type { RuleDefinition } from '../../types.js';
+export declare const frontmatterRules: RuleDefinition[];

package/dist/rules/core/frontmatter.js

@@ -0,0 +1,124 @@
+function normalizeName(name) {
+    if (typeof name !== 'string')
+        return '';
+    return name.replace(/^['"]|['"]$/g, '').trim();
+}
+export const frontmatterRules = [
+    {
+        id: 'frontmatter.required',
+        description: 'SKILL.md must have valid YAML frontmatter.',
+        defaultSeverity: 'error',
+        evaluate(skill) {
+            if (skill.frontmatter)
+                return [];
+            return [
+                {
+                    message: skill.parseError ??
+                        'missing or invalid YAML frontmatter (--- ... ---)',
+                    suggestion: 'Add YAML frontmatter at the top: ---\\nname: my-skill\\ndescription: Use when ...\\n---',
+                    line: 1,
+                    column: 1,
+                },
+            ];
+        },
+    },
+    {
+        id: 'frontmatter.name_required',
+        description: 'Frontmatter must include name.',
+        defaultSeverity: 'error',
+        evaluate(skill) {
+            if (!skill.frontmatter)
+                return [];
+            if (skill.frontmatter.name)
+                return [];
+            return [
+                {
+                    message: 'missing frontmatter "name"',
+                    suggestion: `Add "name: ${skill.slug}" to frontmatter.`,
+                    line: 1,
+                    column: 1,
+                },
+            ];
+        },
+    },
+    {
+        id: 'frontmatter.description_required',
+        description: 'Frontmatter must include description.',
+        defaultSeverity: 'error',
+        evaluate(skill) {
+            if (!skill.frontmatter)
+                return [];
+            if (skill.frontmatter.description)
+                return [];
+            return [
+                {
+                    message: 'missing frontmatter "description"',
+                    suggestion: 'Add a "description:" field. Start with "Use when" to explain triggers.',
+                    line: 1,
+                    column: 1,
+                },
+            ];
+        },
+    },
+    {
+        id: 'frontmatter.name_matches_directory',
+        description: 'Frontmatter name must match skill directory slug.',
+        defaultSeverity: 'error',
+        evaluate(skill) {
+            if (!skill.frontmatter)
+                return [];
+            const name = normalizeName(skill.frontmatter.name);
+            if (!name)
+                return [];
+            if (name === skill.slug)
+                return [];
+            return [
+                {
+                    message: `name "${name}" does not match directory "${skill.slug}"`,
+                    suggestion: `Rename to "name: ${skill.slug}" or rename the directory to "${name}".`,
+                },
+            ];
+        },
+    },
+    {
+        id: 'frontmatter.name_slug_format',
+        description: 'Frontmatter name must match slug spec.',
+        defaultSeverity: 'error',
+        evaluate(skill) {
+            if (!skill.frontmatter)
+                return [];
+            const name = normalizeName(skill.frontmatter.name);
+            if (!name)
+                return [];
+            if (/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
+                return [];
+            return [
+                {
+                    message: 'name must use lowercase letters, numbers, and hyphens only',
+                    suggestion: `Use "name: ${skill.slug}" (derived from directory name).`,
+                },
+            ];
+        },
+    },
+    {
+        id: 'frontmatter.field_order',
+        description: 'Frontmatter should list name before description.',
+        defaultSeverity: 'error',
+        evaluate(skill) {
+            if (!skill.frontmatterRaw)
+                return [];
+            const nameIndex = skill.frontmatterRaw.indexOf('name:');
+            const descriptionIndex = skill.frontmatterRaw.indexOf('description:');
+            if (nameIndex === -1 || descriptionIndex === -1)
+                return [];
+            if (nameIndex < descriptionIndex)
+                return [];
+            return [
+                {
+                    message: 'frontmatter field order should be: name, description',
+                    suggestion: 'Reorder so "name:" comes before "description:" in frontmatter.',
+                },
+            ];
+        },
+    },
+];

package/dist/rules/core/index.d.ts

@@ -0,0 +1,2 @@
+import type { RuleDefinition } from '../../types.js';
+export declare const coreRules: RuleDefinition[];

package/dist/rules/core/index.js

@@ -0,0 +1,12 @@
+import { bodyRules } from './body.js';
+import { descriptionRules } from './description.js';
+import { fileRules } from './file.js';
+import { frontmatterRules } from './frontmatter.js';
+import { linkRules } from './links.js';
+export const coreRules = [
+    ...frontmatterRules,
+    ...descriptionRules,
+    ...bodyRules,
+    ...fileRules,
+    ...linkRules,
+];

package/dist/rules/core/links.d.ts

@@ -0,0 +1,2 @@
+import type { RuleDefinition } from '../../types.js';
+export declare const linkRules: RuleDefinition[];

package/dist/rules/core/links.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import { extractMarkdownLinks, isLocalResolvableTarget, resolveLocalTarget, } from '../../core/links.js';
+export const linkRules = [
+    {
+        id: 'links.local_markdown_resolves',
+        description: 'Local markdown links should resolve.',
+        defaultSeverity: 'warn',
+        evaluate(skill) {
+            const links = extractMarkdownLinks(skill.content);
+            const findings = [];
+            for (const link of links) {
+                if (!isLocalResolvableTarget(link.normalizedTarget))
+                    continue;
+                if (link.normalizedTarget.startsWith('references/'))
+                    continue;
+                const target = resolveLocalTarget(skill.filePath, link.normalizedTarget);
+                if (!fs.existsSync(target)) {
+                    findings.push({
+                        message: `broken local link: ${link.rawTarget}`,
+                        suggestion: `Create the file at ${link.normalizedTarget} or fix the link path.`,
+                        line: link.line,
+                        column: link.column,
+                    });
+                }
+            }
+            return findings;
+        },
+    },
+    {
+        id: 'links.references_resolve',
+        description: 'references/* links should resolve within skill directory.',
+        defaultSeverity: 'warn',
+        evaluate(skill) {
+            const links = extractMarkdownLinks(skill.content);
+            const findings = [];
+            for (const link of links) {
+                if (!isLocalResolvableTarget(link.normalizedTarget))
+                    continue;
+                if (!link.normalizedTarget.startsWith('references/'))
+                    continue;
+                const target = resolveLocalTarget(skill.filePath, link.normalizedTarget);
+                if (!fs.existsSync(target)) {
+                    findings.push({
+                        message: `broken references link: ${link.rawTarget}`,
+                        suggestion: `Create ${link.normalizedTarget} in the skill directory or remove the link.`,
+                        line: link.line,
+                        column: link.column,
+                    });
+                }
+            }
+            return findings;
+        },
+    },
+];

package/dist/types.d.ts

@@ -0,0 +1,92 @@
+export type Severity = 'error' | 'warn';
+export type RuleLevel = Severity | 'off';
+export type OutputFormat = 'text' | 'json' | 'sarif' | 'html' | 'github';
+export interface Diagnostic {
+    ruleId: string;
+    severity: Severity;
+    message: string;
+    file: string;
+    line: number;
+    column: number;
+    suggestion?: string;
+}
+export interface RuleFinding {
+    message: string;
+    line?: number;
+    column?: number;
+    suggestion?: string;
+    severity?: Severity;
+}
+export interface LimitsConfig {
+    maxDescriptionChars: number;
+    maxBodyLines: number;
+    minDescriptionChars: number;
+    maxBodyTokens: number;
+}
+export interface OutputConfig {
+    format: OutputFormat;
+    reportPath?: string;
+}
+export interface ResolvedConfig {
+    cwd: string;
+    configPath?: string;
+    roots: string[];
+    rootsAbs: string[];
+    include: string[];
+    exclude: string[];
+    limits: LimitsConfig;
+    rules: Record<string, RuleLevel>;
+    allowlist: string[];
+    plugins: string[];
+    output: OutputConfig;
+    failOnWarning: boolean;
+    strictMode: boolean;
+    lenientMode: boolean;
+}
+export interface SkillArtifact {
+    id: string;
+    category: string;
+    slug: string;
+    filePath: string;
+    relativePath: string;
+    content: string;
+    body: string;
+    frontmatter: Record<string, unknown> | null;
+    frontmatterRaw: string | null;
+    parseError?: string;
+}
+export interface RuleContext {
+    config: ResolvedConfig;
+    resolveRuleLevel: (ruleId: string, fallback: RuleLevel) => RuleLevel;
+}
+export interface RuleDefinition {
+    id: string;
+    description: string;
+    defaultSeverity: Severity;
+    evaluate: (skill: SkillArtifact, context: RuleContext) => RuleFinding[] | Promise<RuleFinding[]>;
+}
+export interface PluginModule {
+    rules: RuleDefinition[];
+}
+export interface Summary {
+    skillCount: number;
+    errorCount: number;
+    warningCount: number;
+}
+export interface AnalysisResult {
+    config: ResolvedConfig;
+    skills: SkillArtifact[];
+    diagnostics: Diagnostic[];
+    summary: Summary;
+}
+export interface CliOptions {
+    configPath?: string;
+    format?: OutputFormat;
+    strict?: boolean;
+    lenient?: boolean;
+    maxBodyLines?: number;
+    maxDescriptionChars?: number;
+    include?: string[];
+    exclude?: string[];
+    failOnWarning?: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "skill-check",
+  "version": "0.1.0",
+  "description": "Linter for agent skill files",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "skill-check": "bin/skill-check.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "schemas",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "clean": "rm -rf dist coverage",
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx src/cli/main.ts",
+    "check": "tsx src/cli/main.ts check .",
+    "check:fix": "tsx src/cli/main.ts check . --fix --no-security-scan",
+    "check:security": "tsx src/cli/main.ts check . --security-scan --allow-installs",
+    "security-scan": "tsx src/cli/main.ts security-scan .",
+    "demo:readme": "bash scripts/readme-demo.sh",
+    "release": "semantic-release",
+    "release:dry-run": "semantic-release --dry-run",
+    "smoke:cli": "bash scripts/smoke-cli.sh",
+    "report": "tsx src/cli/main.ts report .",
+    "lint": "biome check --no-errors-on-unmatched .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepack": "pnpm run clean && pnpm run build",
+    "format": "biome format --write .",
+    "prepare": "lefthook install"
+  },
+  "keywords": [
+    "skills",
+    "agent-skills",
+    "lint",
+    "validator",
+    "cli",
+    "sarif"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thedaviddias/skill-check.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.0.1",
+    "boxen": "^8.0.1",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3",
+    "fast-glob": "^3.3.3",
+    "listr2": "^10.1.0",
+    "minimatch": "^10.2.2",
+    "ora": "^9.3.0",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
+    "@commitlint/config-conventional": "^20.4.2",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^25.3.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "commitlint": "^20.4.2",
+    "lefthook": "^2.1.1",
+    "semantic-release": "^25.0.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "packageManager": "pnpm@10.30.1+sha512.3590e550d5384caa39bd5c7c739f72270234b2f6059e13018f975c313b1eb9fefcc09714048765d4d9efe961382c312e624572c0420762bdc5d5940cdf9be73a"
+}