skill-check 0.1.0

package/dist/core/agent-scan.d.ts

@@ -0,0 +1,19 @@
+declare const VALID_RUNNERS: readonly ["auto", "local", "uvx", "pipx"];
+export type AgentScanRunner = (typeof VALID_RUNNERS)[number];
+export interface AgentScanOptions {
+    cwd: string;
+    targetPath?: string;
+    mode?: string;
+    paths?: string[];
+    skills?: string[];
+    runner?: AgentScanRunner;
+}
+export interface AgentScanInvocation {
+    command: string;
+    args: string[];
+}
+export declare function isValidAgentScanRunner(value: string): value is AgentScanRunner;
+export declare function isCommandAvailable(commandName: string): boolean;
+export declare function resolveAgentScanInvocation(options: AgentScanOptions, hasCommand?: (commandName: string) => boolean): AgentScanInvocation;
+export declare function runAgentScan(options: AgentScanOptions): number;
+export {};

package/dist/core/agent-scan.js

@@ -0,0 +1,88 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { CliError } from './errors.js';
+const VALID_RUNNERS = ['auto', 'local', 'uvx', 'pipx'];
+function normalizePaths(cwd, values, fallback) {
+    const list = values && values.length > 0 ? values : fallback;
+    return list.map((value) => path.resolve(cwd, value));
+}
+function buildMcpScanArgs(options) {
+    const targetPath = options.targetPath ?? '.';
+    const paths = normalizePaths(options.cwd, options.paths, []);
+    const skills = normalizePaths(options.cwd, options.skills, [targetPath]);
+    const args = [];
+    for (const scanPath of paths) {
+        args.push(scanPath);
+    }
+    for (const skillsPath of skills) {
+        args.push('--skills', skillsPath);
+    }
+    return args;
+}
+export function isValidAgentScanRunner(value) {
+    return VALID_RUNNERS.includes(value);
+}
+export function isCommandAvailable(commandName) {
+    const pathValue = process.env.PATH;
+    if (!pathValue)
+        return false;
+    const exts = process.platform === 'win32'
+        ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';')
+        : [''];
+    for (const base of pathValue.split(path.delimiter)) {
+        if (!base)
+            continue;
+        for (const ext of exts) {
+            const candidate = path.join(base, `${commandName}${ext}`);
+            try {
+                fs.accessSync(candidate, fs.constants.X_OK);
+                return true;
+            }
+            catch {
+                // Try next candidate.
+            }
+        }
+    }
+    return false;
+}
+export function resolveAgentScanInvocation(options, hasCommand = isCommandAvailable) {
+    const runner = options.runner ?? 'auto';
+    const scanArgs = buildMcpScanArgs(options);
+    if (runner === 'local') {
+        return { command: 'mcp-scan', args: scanArgs };
+    }
+    if (runner === 'uvx') {
+        return { command: 'uvx', args: ['mcp-scan', ...scanArgs] };
+    }
+    if (runner === 'pipx') {
+        return { command: 'pipx', args: ['run', 'mcp-scan', ...scanArgs] };
+    }
+    if (hasCommand('mcp-scan')) {
+        return { command: 'mcp-scan', args: scanArgs };
+    }
+    if (hasCommand('uvx')) {
+        return { command: 'uvx', args: ['mcp-scan', ...scanArgs] };
+    }
+    if (hasCommand('pipx')) {
+        return { command: 'pipx', args: ['run', 'mcp-scan', ...scanArgs] };
+    }
+    throw new CliError('No security scan runner found. Install mcp-scan, uv, or pipx.', 2);
+}
+export function runAgentScan(options) {
+    const invocation = resolveAgentScanInvocation(options);
+    const result = spawnSync(invocation.command, invocation.args, {
+        stdio: 'inherit',
+    });
+    const error = result.error;
+    if (error?.code === 'ENOENT') {
+        throw new CliError(`Runner not found: ${invocation.command}`, 2);
+    }
+    if (error) {
+        throw new CliError(`Failed to run security scan (${invocation.command}): ${error.message}`, 2);
+    }
+    if (typeof result.status !== 'number') {
+        throw new CliError('Security scan process did not return an exit code.', 2);
+    }
+    return result.status;
+}

package/dist/core/allowlist.d.ts

@@ -0,0 +1 @@
+export declare function isAllowlisted(skillId: string, allowlist: string[]): boolean;

package/dist/core/allowlist.js

@@ -0,0 +1,8 @@
+import { minimatch } from 'minimatch';
+export function isAllowlisted(skillId, allowlist) {
+    return allowlist.some((pattern) => {
+        if (pattern === skillId)
+            return true;
+        return minimatch(skillId, pattern, { dot: true });
+    });
+}

package/dist/core/analyze.d.ts

@@ -0,0 +1,6 @@
+import type { AnalysisResult, CliOptions, ResolvedConfig } from '../types.js';
+export declare function analyze(cwd: string, targetPath: string | undefined, cliOptions: CliOptions): Promise<AnalysisResult>;
+export declare function analyzeWithConfig(cwd: string, config: ResolvedConfig): Promise<AnalysisResult>;
+export declare function resolveExitCode(result: AnalysisResult): number;
+export declare function writeIfRequested(config: ResolvedConfig, text: string): string | undefined;
+export declare function ensureInitConfig(targetPath: string, force?: boolean): void;

package/dist/core/analyze.js

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { coreRules } from '../rules/core/index.js';
+import { buildSkillArtifact } from './artifact.js';
+import { resolveConfig } from './config.js';
+import { discoverSkillFiles } from './discovery.js';
+import { CliError } from './errors.js';
+import { loadPluginRules } from './plugins.js';
+import { runRuleEngine } from './rule-engine.js';
+function summarize(skillCount, diagnostics) {
+    const errorCount = diagnostics.filter((d) => d.severity === 'error').length;
+    const warningCount = diagnostics.filter((d) => d.severity === 'warn').length;
+    return { skillCount, errorCount, warningCount };
+}
+export async function analyze(cwd, targetPath, cliOptions) {
+    const config = await resolveConfig(cwd, targetPath, cliOptions);
+    return analyzeWithConfig(cwd, config);
+}
+export async function analyzeWithConfig(cwd, config) {
+    const files = await discoverSkillFiles(config);
+    const skills = files.map((file) => buildSkillArtifact(file, cwd));
+    const pluginRules = await loadPluginRules(config);
+    const rules = [...coreRules, ...pluginRules];
+    const diagnostics = await runRuleEngine(skills, rules, config);
+    return {
+        config,
+        skills,
+        diagnostics,
+        summary: summarize(skills.length, diagnostics),
+    };
+}
+export function resolveExitCode(result) {
+    if (result.summary.errorCount > 0)
+        return 1;
+    if (result.config.failOnWarning && result.summary.warningCount > 0)
+        return 1;
+    return 0;
+}
+export function writeIfRequested(config, text) {
+    const reportPath = config.output.reportPath;
+    if (!reportPath)
+        return undefined;
+    const parent = path.dirname(reportPath);
+    fs.mkdirSync(parent, { recursive: true });
+    fs.writeFileSync(reportPath, text);
+    return reportPath;
+}
+export function ensureInitConfig(targetPath, force = false) {
+    if (fs.existsSync(targetPath) && !force) {
+        throw new CliError(`Config file already exists: ${targetPath}. Use --force to overwrite.`, 2);
+    }
+    const template = {
+        roots: ['.'],
+        include: ['**/skills/*/SKILL.md'],
+        exclude: ['**/node_modules/**', '**/.git/**'],
+        limits: {
+            maxDescriptionChars: 1024,
+            maxBodyLines: 500,
+            minDescriptionChars: 50,
+            maxBodyTokens: 5000,
+        },
+        rules: {
+            'description.use_when_phrase': 'warn',
+        },
+        allowlist: [],
+        plugins: [],
+        output: {
+            format: 'text',
+        },
+    };
+    fs.writeFileSync(targetPath, `${JSON.stringify(template, null, 2)}\n`);
+}

package/dist/core/artifact.d.ts

@@ -0,0 +1,2 @@
+import type { SkillArtifact } from '../types.js';
+export declare function buildSkillArtifact(filePath: string, cwd: string): SkillArtifact;

package/dist/core/artifact.js

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseFrontmatter } from './frontmatter.js';
+function deriveCategoryAndSlug(filePath) {
+    const parts = path.resolve(filePath).split(path.sep).filter(Boolean);
+    const skillsIndex = parts.lastIndexOf('skills');
+    if (skillsIndex > 0 && skillsIndex + 1 < parts.length) {
+        const category = parts[skillsIndex - 1] ?? 'unknown';
+        const slug = parts[skillsIndex + 1] ?? 'unknown-skill';
+        return { category, slug };
+    }
+    const slug = path.basename(path.dirname(filePath));
+    const category = path.basename(path.dirname(path.dirname(filePath)));
+    return { category, slug };
+}
+export function buildSkillArtifact(filePath, cwd) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const parsed = parseFrontmatter(content);
+    const { category, slug } = deriveCategoryAndSlug(filePath);
+    const id = `${category}/${slug}`;
+    return {
+        id,
+        category,
+        slug,
+        filePath: path.resolve(filePath),
+        relativePath: path.relative(cwd, path.resolve(filePath)),
+        content,
+        body: parsed.body,
+        frontmatter: parsed.frontmatter,
+        frontmatterRaw: parsed.frontmatterRaw,
+        parseError: parsed.error,
+    };
+}

package/dist/core/baseline.d.ts

@@ -0,0 +1,8 @@
+import type { Diagnostic } from '../types.js';
+export declare function loadBaseline(baselinePath: string): Diagnostic[];
+export interface BaselineDiff {
+    newDiagnostics: Diagnostic[];
+    fixedDiagnostics: Diagnostic[];
+    unchanged: Diagnostic[];
+}
+export declare function diffBaseline(current: Diagnostic[], baseline: Diagnostic[]): BaselineDiff;

package/dist/core/baseline.js

@@ -0,0 +1,17 @@
+import fs from 'node:fs';
+function diagnosticKey(d) {
+    return `${d.file}|${d.ruleId}|${d.line}|${d.column}|${d.message}`;
+}
+export function loadBaseline(baselinePath) {
+    const raw = fs.readFileSync(baselinePath, 'utf8');
+    const data = JSON.parse(raw);
+    return data.diagnostics ?? [];
+}
+export function diffBaseline(current, baseline) {
+    const baselineKeys = new Set(baseline.map(diagnosticKey));
+    const currentKeys = new Set(current.map(diagnosticKey));
+    const newDiagnostics = current.filter((d) => !baselineKeys.has(diagnosticKey(d)));
+    const fixedDiagnostics = baseline.filter((d) => !currentKeys.has(diagnosticKey(d)));
+    const unchanged = current.filter((d) => baselineKeys.has(diagnosticKey(d)));
+    return { newDiagnostics, fixedDiagnostics, unchanged };
+}

package/dist/core/config.d.ts

@@ -0,0 +1,2 @@
+import type { CliOptions, ResolvedConfig } from '../types.js';
+export declare function resolveConfig(cwd: string, targetPath: string | undefined, cli: CliOptions): Promise<ResolvedConfig>;

package/dist/core/config.js

@@ -0,0 +1,215 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_EXCLUDE, DEFAULT_INCLUDE, DEFAULT_LIMITS, DEFAULT_OUTPUT, } from './defaults.js';
+import { CliError } from './errors.js';
+function isStringArray(value) {
+    return (Array.isArray(value) && value.every((entry) => typeof entry === 'string'));
+}
+function isObjectRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError(`Invalid JSON in ${filePath}: ${message}`, 2);
+    }
+}
+function validateConfigShape(config, sourcePath) {
+    if (!isObjectRecord(config)) {
+        throw new CliError(`Invalid config${sourcePath ? ` (${sourcePath})` : ''}: config must be an object`, 2);
+    }
+    const knownKeys = new Set([
+        'roots',
+        'include',
+        'exclude',
+        'limits',
+        'rules',
+        'allowlist',
+        'plugins',
+        'output',
+    ]);
+    for (const key of Object.keys(config)) {
+        if (!knownKeys.has(key)) {
+            throw new CliError(`Invalid config${sourcePath ? ` (${sourcePath})` : ''}: unknown key "${key}"`, 2);
+        }
+    }
+    if (config.roots !== undefined && !isStringArray(config.roots)) {
+        throw new CliError(`Invalid config${sourcePath ? ` (${sourcePath})` : ''}: roots must be string[]`, 2);
+    }
+    if (config.include !== undefined && !isStringArray(config.include)) {
+        throw new CliError(`Invalid config${sourcePath ? ` (${sourcePath})` : ''}: include must be string[]`, 2);
+    }
+    if (config.exclude !== undefined && !isStringArray(config.exclude)) {
+        throw new CliError(`Invalid config${sourcePath ? ` (${sourcePath})` : ''}: exclude must be string[]`, 2);
+    }
+    if (config.allowlist !== undefined && !isStringArray(config.allowlist)) {
+        throw new CliError(`Invalid config${sourcePath ? ` (${sourcePath})` : ''}: allowlist must be string[]`, 2);
+    }
+    if (config.plugins !== undefined && !isStringArray(config.plugins)) {
+        throw new CliError(`Invalid config${sourcePath ? ` (${sourcePath})` : ''}: plugins must be string[]`, 2);
+    }
+    if (config.limits !== undefined) {
+        if (!isObjectRecord(config.limits)) {
+            throw new CliError(`Invalid config${sourcePath ? ` (${sourcePath})` : ''}: limits must be an object`, 2);
+        }
+        for (const [key, value] of Object.entries(config.limits)) {
+            if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+                throw new CliError(`Invalid config${sourcePath ? ` (${sourcePath})` : ''}: limits.${key} must be a positive number`, 2);
+            }
+        }
+    }
+    if (config.rules !== undefined) {
+        if (!isObjectRecord(config.rules)) {
+            throw new CliError(`Invalid config${sourcePath ? ` (${sourcePath})` : ''}: rules must be an object`, 2);
+        }
+        for (const value of Object.values(config.rules)) {
+            if (value !== 'off' && value !== 'warn' && value !== 'error') {
+                throw new CliError(`Invalid config${sourcePath ? ` (${sourcePath})` : ''}: rules values must be off|warn|error`, 2);
+            }
+        }
+    }
+    if (config.output !== undefined) {
+        if (!isObjectRecord(config.output)) {
+            throw new CliError(`Invalid config${sourcePath ? ` (${sourcePath})` : ''}: output must be an object`, 2);
+        }
+        if (config.output.format !== undefined &&
+            config.output.format !== 'text' &&
+            config.output.format !== 'json' &&
+            config.output.format !== 'sarif' &&
+            config.output.format !== 'html' &&
+            config.output.format !== 'github') {
+            throw new CliError(`Invalid config${sourcePath ? ` (${sourcePath})` : ''}: output.format must be text|json|sarif|html|github`, 2);
+        }
+        if (config.output.reportPath !== undefined &&
+            typeof config.output.reportPath !== 'string') {
+            throw new CliError(`Invalid config${sourcePath ? ` (${sourcePath})` : ''}: output.reportPath must be string`, 2);
+        }
+    }
+    return config;
+}
+function mergeConfig(base, override) {
+    return {
+        ...base,
+        ...override,
+        limits: {
+            ...(base.limits ?? {}),
+            ...(override.limits ?? {}),
+        },
+        rules: {
+            ...(base.rules ?? {}),
+            ...(override.rules ?? {}),
+        },
+        output: {
+            ...(base.output ?? {}),
+            ...(override.output ?? {}),
+        },
+    };
+}
+function resolveRoots(cwd, roots) {
+    return roots.map((root) => path.resolve(cwd, root));
+}
+function normalizeList(values, fallback) {
+    if (!values || values.length === 0)
+        return fallback;
+    return values.map((value) => value.trim()).filter(Boolean);
+}
+function normalizeRules(values) {
+    if (!values)
+        return {};
+    const normalized = {};
+    for (const [ruleId, level] of Object.entries(values)) {
+        if (level === 'off' || level === 'warn' || level === 'error') {
+            normalized[ruleId] = level;
+        }
+    }
+    return normalized;
+}
+export async function resolveConfig(cwd, targetPath, cli) {
+    if (cli.strict && cli.lenient) {
+        throw new CliError('Cannot use --strict and --lenient together.', 2);
+    }
+    const explicitConfigPath = cli.configPath
+        ? path.resolve(cwd, cli.configPath)
+        : undefined;
+    const defaultConfigPath = path.resolve(cwd, 'skill-check.config.json');
+    let fileConfig = {};
+    let configPath;
+    if (explicitConfigPath) {
+        if (!fs.existsSync(explicitConfigPath)) {
+            throw new CliError(`Config file not found: ${explicitConfigPath}`, 2);
+        }
+        configPath = explicitConfigPath;
+        fileConfig = validateConfigShape(readJsonFile(explicitConfigPath), explicitConfigPath);
+    }
+    else if (fs.existsSync(defaultConfigPath)) {
+        configPath = defaultConfigPath;
+        fileConfig = validateConfigShape(readJsonFile(defaultConfigPath), defaultConfigPath);
+    }
+    const optionConfig = {};
+    if (cli.include && cli.include.length > 0) {
+        optionConfig.include = cli.include;
+    }
+    if (cli.exclude && cli.exclude.length > 0) {
+        optionConfig.exclude = cli.exclude;
+    }
+    if (typeof cli.maxBodyLines === 'number' ||
+        typeof cli.maxDescriptionChars === 'number') {
+        optionConfig.limits = {};
+        if (typeof cli.maxBodyLines === 'number') {
+            optionConfig.limits.maxBodyLines = cli.maxBodyLines;
+        }
+        if (typeof cli.maxDescriptionChars === 'number') {
+            optionConfig.limits.maxDescriptionChars = cli.maxDescriptionChars;
+        }
+    }
+    if (cli.format) {
+        optionConfig.output = {
+            format: cli.format,
+        };
+    }
+    const merged = mergeConfig(fileConfig, optionConfig);
+    const roots = targetPath ? [targetPath] : normalizeList(merged.roots, ['.']);
+    const include = normalizeList(merged.include, DEFAULT_INCLUDE);
+    const exclude = normalizeList(merged.exclude, DEFAULT_EXCLUDE);
+    const limits = {
+        ...DEFAULT_LIMITS,
+        ...(merged.limits ?? {}),
+    };
+    const output = {
+        ...DEFAULT_OUTPUT,
+        ...(merged.output ?? {}),
+    };
+    const rules = normalizeRules(merged.rules);
+    if (cli.lenient) {
+        rules['frontmatter.name_matches_directory'] = 'off';
+    }
+    const failOnWarning = Boolean(cli.failOnWarning || cli.strict);
+    const strictMode = Boolean(cli.strict);
+    const lenientMode = Boolean(cli.lenient);
+    const rootsAbs = resolveRoots(cwd, roots);
+    const reportPath = output.reportPath
+        ? path.resolve(cwd, output.reportPath)
+        : undefined;
+    return {
+        cwd,
+        configPath,
+        roots,
+        rootsAbs,
+        include,
+        exclude,
+        limits,
+        rules,
+        allowlist: merged.allowlist ?? [],
+        plugins: merged.plugins ?? [],
+        output: {
+            ...output,
+            reportPath,
+        },
+        failOnWarning,
+        strictMode,
+        lenientMode,
+    };
+}

package/dist/core/defaults.d.ts

@@ -0,0 +1,6 @@
+import type { LimitsConfig, OutputConfig, RuleLevel } from '../types.js';
+export declare const DEFAULT_INCLUDE: string[];
+export declare const DEFAULT_EXCLUDE: string[];
+export declare const DEFAULT_LIMITS: LimitsConfig;
+export declare const DEFAULT_OUTPUT: OutputConfig;
+export declare const DEFAULT_RULE_LEVELS: Record<string, RuleLevel>;

package/dist/core/defaults.js

@@ -0,0 +1,34 @@
+export const DEFAULT_INCLUDE = ['**/skills/*/SKILL.md'];
+export const DEFAULT_EXCLUDE = [
+    '**/node_modules/**',
+    '**/.git/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/.next/**',
+    '**/coverage/**',
+];
+export const DEFAULT_LIMITS = {
+    maxDescriptionChars: 1024,
+    maxBodyLines: 500,
+    minDescriptionChars: 50,
+    maxBodyTokens: 5000,
+};
+export const DEFAULT_OUTPUT = {
+    format: 'text',
+};
+export const DEFAULT_RULE_LEVELS = {
+    'frontmatter.required': 'error',
+    'frontmatter.name_required': 'error',
+    'frontmatter.description_required': 'error',
+    'frontmatter.name_matches_directory': 'error',
+    'frontmatter.name_slug_format': 'error',
+    'frontmatter.field_order': 'error',
+    'description.max_length': 'error',
+    'description.use_when_phrase': 'warn',
+    'description.min_recommended_length': 'warn',
+    'body.max_lines': 'error',
+    'body.max_tokens': 'warn',
+    'file.trailing_newline_single': 'warn',
+    'links.local_markdown_resolves': 'warn',
+    'links.references_resolve': 'warn',
+};

package/dist/core/discovery.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedConfig } from '../types.js';
+export declare function discoverSkillFiles(config: ResolvedConfig): Promise<string[]>;

package/dist/core/discovery.js

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import fg from 'fast-glob';
+import { DEFAULT_INCLUDE } from './defaults.js';
+export async function discoverSkillFiles(config) {
+    const found = new Set();
+    const usesDefaultInclude = config.include.length === DEFAULT_INCLUDE.length &&
+        config.include.every((pattern, index) => pattern === DEFAULT_INCLUDE[index]);
+    for (const root of config.rootsAbs) {
+        if (fs.existsSync(root) && fs.statSync(root).isFile()) {
+            if (path.basename(root) === 'SKILL.md') {
+                found.add(path.resolve(root));
+            }
+            continue;
+        }
+        if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+            continue;
+        }
+        const matches = await fg(config.include, {
+            cwd: root,
+            ignore: config.exclude,
+            absolute: true,
+            onlyFiles: true,
+            dot: true,
+        });
+        if (matches.length === 0 &&
+            usesDefaultInclude &&
+            path.basename(path.resolve(root)) === 'skills') {
+            const fallbackMatches = await fg('**/SKILL.md', {
+                cwd: root,
+                ignore: config.exclude,
+                absolute: true,
+                onlyFiles: true,
+                dot: true,
+            });
+            for (const match of fallbackMatches) {
+                found.add(path.resolve(match));
+            }
+            continue;
+        }
+        for (const match of matches) {
+            found.add(path.resolve(match));
+        }
+    }
+    return Array.from(found).sort();
+}

package/dist/core/duplicates.d.ts

@@ -0,0 +1,2 @@
+import type { Diagnostic, SkillArtifact } from '../types.js';
+export declare function detectDuplicates(skills: SkillArtifact[]): Diagnostic[];

package/dist/core/duplicates.js

@@ -0,0 +1,60 @@
+export function detectDuplicates(skills) {
+    const diagnostics = [];
+    const nameMap = new Map();
+    for (const skill of skills) {
+        if (!skill.frontmatter?.name)
+            continue;
+        const name = String(skill.frontmatter.name);
+        const list = nameMap.get(name) ?? [];
+        list.push(skill);
+        nameMap.set(name, list);
+    }
+    for (const [name, group] of nameMap) {
+        if (group.length <= 1)
+            continue;
+        for (const skill of group) {
+            diagnostics.push({
+                ruleId: 'duplicates.name',
+                severity: 'warn',
+                message: `duplicate skill name "${name}" shared with: ${group
+                    .filter((s) => s !== skill)
+                    .map((s) => s.relativePath)
+                    .join(', ')}`,
+                suggestion: 'Ensure each skill has a unique name.',
+                file: skill.relativePath,
+                line: 1,
+                column: 1,
+            });
+        }
+    }
+    const descMap = new Map();
+    for (const skill of skills) {
+        if (!skill.frontmatter?.description)
+            continue;
+        const desc = String(skill.frontmatter.description).trim().toLowerCase();
+        if (desc.length < 20)
+            continue;
+        const list = descMap.get(desc) ?? [];
+        list.push(skill);
+        descMap.set(desc, list);
+    }
+    for (const [, group] of descMap) {
+        if (group.length <= 1)
+            continue;
+        for (const skill of group) {
+            diagnostics.push({
+                ruleId: 'duplicates.description',
+                severity: 'warn',
+                message: `identical description shared with: ${group
+                    .filter((s) => s !== skill)
+                    .map((s) => s.relativePath)
+                    .join(', ')}`,
+                suggestion: 'Write distinct descriptions so agents can differentiate skills.',
+                file: skill.relativePath,
+                line: 1,
+                column: 1,
+            });
+        }
+    }
+    return diagnostics;
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class CliError extends Error {
+    readonly code: number;
+    constructor(message: string, code?: number);
+}

package/dist/core/errors.js

@@ -0,0 +1,8 @@
+export class CliError extends Error {
+    code;
+    constructor(message, code = 2) {
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+    }
+}

package/dist/core/fix.d.ts

@@ -0,0 +1,11 @@
+import type { AnalysisResult } from '../types.js';
+export interface AutoFixSummary {
+    requestedDiagnostics: number;
+    supportedDiagnostics: number;
+    unsupportedDiagnostics: number;
+    appliedFixes: number;
+    filesUpdated: number;
+    updatedFiles: string[];
+}
+export declare function isFixableRuleId(ruleId: string): boolean;
+export declare function applyAutoFixes(result: AnalysisResult): AutoFixSummary;