skill-check 1.0.0 → 1.2.0

package/README.md

@@ -382,7 +382,13 @@ Run `skill-check rules <id>` for detail on a specific rule.
 | `frontmatter.description_required` | error | yes |
 | `frontmatter.name_matches_directory` | error | yes |
 | `frontmatter.name_slug_format` | error | yes |
+| `frontmatter.name_max_length` | error | no |
 | `frontmatter.field_order` | error | yes |
+| `frontmatter.unknown_fields` | warn | no |
+| `frontmatter.compatibility_max_length` | warn | no |
+| `frontmatter.metadata_string_values` | warn | no |
+| `frontmatter.allowed_tools_format` | warn | no |
+| `description.non_empty` | error | no |
 | `description.max_length` | error | no |
 | `description.use_when_phrase` | warn | yes |
 | `description.min_recommended_length` | warn | yes |

package/dist/cli/main.js

@@ -605,15 +605,19 @@ async function runAgentScanWithFeedback(scanOptions, target, io, format) {
     }
 }
 function resolveValidationStatus(result) {
+    if (result.summary.skillCount === 0)
+        return 'SKIPPED';
     if (result.summary.errorCount > 0)
         return 'FAIL';
     if (result.summary.warningCount > 0)
         return 'WARN';
     return 'PASS';
 }
-function resolveSecurityStatus(enabled, scanExitCode) {
+function resolveSecurityStatus(enabled, scanExitCode, skillCount) {
     if (!enabled)
         return 'SKIPPED';
+    if (skillCount === 0)
+        return 'SKIPPED';
     return scanExitCode === 0 ? 'PASS' : 'FAIL';
 }
 function computeOverallScore(scores) {
@@ -848,7 +852,7 @@ export async function runCli(argv, io = defaultIO) {
                     affectedFileCount: countAffectedFiles(result.diagnostics),
                     overallScore: computeOverallScore(scores),
                     validationStatus: resolveValidationStatus(result),
-                    securityStatus: resolveSecurityStatus(scanOptions.enabled, scanExitCode),
+                    securityStatus: resolveSecurityStatus(scanOptions.enabled, scanExitCode, result.summary.skillCount),
                     elapsedMs: performance.now() - checkStartedAt,
                     runCommand,
                     mode: checkOptions.share ? 'share' : 'default',
@@ -857,7 +861,7 @@ export async function runCli(argv, io = defaultIO) {
                 if (conclusion.fullCommandPlain) {
                     io.stdout(`${conclusion.fullCommandPlain}\n`);
                 }
-                if (checkOptions.share) {
+                if (checkOptions.share && result.summary.skillCount > 0) {
                     emitShareStatus(io, 'rendering share image...');
                     const shareOutputPath = path.resolve(process.cwd(), checkOptions.shareOut ?? 'skill-check-share.png');
                     const shareText = conclusion.fullCommandPlain
@@ -1052,6 +1056,12 @@ export async function runCli(argv, io = defaultIO) {
             '---',
             `name: ${slug}`,
             `description: Use when ${slug} functionality is needed. Describe triggers, constraints, and expected outcomes.`,
+            '# license: MIT',
+            '# compatibility: Designed for Claude Code (or similar products)',
+            '# metadata:',
+            '#   author: your-org',
+            '#   version: "1.0"',
+            '# allowed-tools: Bash(git:*) Read',
             '---',
             '',
             `# ${slug}`,

package/dist/core/analyze.js

@@ -58,6 +58,8 @@ export function ensureInitConfig(targetPath, force = false) {
             maxBodyLines: 500,
             minDescriptionChars: 50,
             maxBodyTokens: 5000,
+            maxNameChars: 64,
+            maxCompatibilityChars: 500,
         },
         rules: {
             'description.use_when_phrase': 'warn',

package/dist/core/conclusion-card.d.ts

@@ -1,4 +1,4 @@
-export type ValidationStatus = 'PASS' | 'WARN' | 'FAIL';
+export type ValidationStatus = 'PASS' | 'WARN' | 'FAIL' | 'SKIPPED';
 export type SecurityStatus = 'PASS' | 'FAIL' | 'SKIPPED';
 export type ConclusionCardMode = 'default' | 'share';
 export interface ConclusionCardInput {

package/dist/core/conclusion-card.js

@@ -55,6 +55,8 @@ function renderValidationStatus(c, status) {
         return c.green(status);
     if (status === 'WARN')
         return c.yellow(status);
+    if (status === 'SKIPPED')
+        return c.dim(status);
     return c.red(status);
 }
 function renderSecurityStatus(c, status) {

package/dist/core/defaults.js

@@ -1,4 +1,4 @@
-export const DEFAULT_INCLUDE = ['**/skills/*/SKILL.md'];
+export const DEFAULT_INCLUDE = ['**/SKILL.md'];
 export const DEFAULT_EXCLUDE = [
     '**/node_modules/**',
     '**/.git/**',
@@ -13,6 +13,8 @@ export const DEFAULT_LIMITS = {
     maxBodyLines: 500,
     minDescriptionChars: 50,
     maxBodyTokens: 5000,
+    maxNameChars: 64,
+    maxCompatibilityChars: 500,
 };
 export const DEFAULT_OUTPUT = {
     format: 'text',
@@ -23,8 +25,14 @@ export const DEFAULT_RULE_LEVELS = {
     'frontmatter.description_required': 'error',
     'frontmatter.name_matches_directory': 'error',
     'frontmatter.name_slug_format': 'error',
+    'frontmatter.name_max_length': 'error',
     'frontmatter.field_order': 'error',
+    'frontmatter.unknown_fields': 'warn',
+    'frontmatter.compatibility_max_length': 'warn',
+    'frontmatter.metadata_string_values': 'warn',
+    'frontmatter.allowed_tools_format': 'warn',
     'description.max_length': 'error',
+    'description.non_empty': 'error',
     'description.use_when_phrase': 'warn',
     'description.min_recommended_length': 'warn',
     'body.max_lines': 'error',

package/dist/core/discovery.js

@@ -1,11 +1,8 @@
 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') {
@@ -23,21 +20,6 @@ export async function discoverSkillFiles(config) {
             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));
         }

package/dist/core/formatters.js

@@ -84,6 +84,8 @@ function renderScoreBar(score) {
     return `${color('█'.repeat(filled))}${pc.dim('░'.repeat(empty))} ${color(String(score))}`;
 }
 function resolveValidationStatus(result) {
+    if (result.summary.skillCount === 0)
+        return 'SKIPPED';
     if (result.summary.errorCount > 0)
         return 'FAIL';
     if (result.summary.warningCount > 0)

package/dist/rules/core/description.js

@@ -7,6 +7,27 @@ function getDescription(skill) {
     return value.trim();
 }
 export const descriptionRules = [
+    {
+        id: 'description.non_empty',
+        description: 'Description must not be empty or whitespace-only.',
+        defaultSeverity: 'error',
+        evaluate(skill) {
+            if (!skill.frontmatter)
+                return [];
+            const raw = skill.frontmatter.description;
+            if (raw === undefined || raw === null)
+                return [];
+            const trimmed = typeof raw === 'string' ? raw.trim() : String(raw).trim();
+            if (trimmed.length > 0)
+                return [];
+            return [
+                {
+                    message: 'description is empty or whitespace-only',
+                    suggestion: 'Provide a meaningful description. Start with "Use when" to help agents match this skill.',
+                },
+            ];
+        },
+    },
     {
         id: 'description.max_length',
         description: 'Description must be within configured max length.',

package/dist/rules/core/frontmatter.js

@@ -3,6 +3,14 @@ function normalizeName(name) {
         return '';
     return name.replace(/^['"]|['"]$/g, '').trim();
 }
+const KNOWN_FRONTMATTER_FIELDS = new Set([
+    'name',
+    'description',
+    'license',
+    'compatibility',
+    'metadata',
+    'allowed-tools',
+]);
 export const frontmatterRules = [
     {
         id: 'frontmatter.required',
@@ -100,6 +108,27 @@ export const frontmatterRules = [
             ];
         },
     },
+    {
+        id: 'frontmatter.name_max_length',
+        description: 'Frontmatter name must not exceed 64 characters.',
+        defaultSeverity: 'error',
+        evaluate(skill, context) {
+            if (!skill.frontmatter)
+                return [];
+            const name = normalizeName(skill.frontmatter.name);
+            if (!name)
+                return [];
+            const max = context.config.limits.maxNameChars;
+            if (name.length <= max)
+                return [];
+            return [
+                {
+                    message: `name length ${name.length} exceeds max ${max}`,
+                    suggestion: `Shorten the name to ${max} characters or fewer.`,
+                },
+            ];
+        },
+    },
     {
         id: 'frontmatter.field_order',
         description: 'Frontmatter should list name before description.',
@@ -121,4 +150,99 @@ export const frontmatterRules = [
             ];
         },
     },
+    {
+        id: 'frontmatter.unknown_fields',
+        description: 'Frontmatter should only contain spec-defined fields (name, description, license, compatibility, metadata, allowed-tools).',
+        defaultSeverity: 'warn',
+        evaluate(skill) {
+            if (!skill.frontmatter)
+                return [];
+            const unknown = Object.keys(skill.frontmatter).filter((key) => !KNOWN_FRONTMATTER_FIELDS.has(key));
+            if (unknown.length === 0)
+                return [];
+            const plural = unknown.length === 1 ? 'field' : 'fields';
+            return [
+                {
+                    message: `unknown frontmatter ${plural}: ${unknown.join(', ')}`,
+                    suggestion: `The spec defines: ${[...KNOWN_FRONTMATTER_FIELDS].join(', ')}. Remove or rename unrecognized fields.`,
+                },
+            ];
+        },
+    },
+    {
+        id: 'frontmatter.compatibility_max_length',
+        description: 'Compatibility field must not exceed 500 characters when provided.',
+        defaultSeverity: 'warn',
+        evaluate(skill, context) {
+            if (!skill.frontmatter)
+                return [];
+            const value = skill.frontmatter.compatibility;
+            if (value === undefined || value === null)
+                return [];
+            if (typeof value !== 'string')
+                return [];
+            const max = context.config.limits.maxCompatibilityChars;
+            if (value.trim().length <= max)
+                return [];
+            return [
+                {
+                    message: `compatibility length ${value.trim().length} exceeds max ${max}`,
+                    suggestion: `Shorten the compatibility field to ${max} characters or fewer.`,
+                },
+            ];
+        },
+    },
+    {
+        id: 'frontmatter.metadata_string_values',
+        description: 'Metadata field must be a map of string keys to string values.',
+        defaultSeverity: 'warn',
+        evaluate(skill) {
+            if (!skill.frontmatter)
+                return [];
+            const metadata = skill.frontmatter.metadata;
+            if (metadata === undefined || metadata === null)
+                return [];
+            if (typeof metadata !== 'object' || Array.isArray(metadata)) {
+                return [
+                    {
+                        message: 'metadata must be a key-value object',
+                        suggestion: 'Use metadata as a YAML mapping, e.g. metadata:\\n  author: example-org',
+                    },
+                ];
+            }
+            const nonStringKeys = [];
+            for (const [key, val] of Object.entries(metadata)) {
+                if (typeof val !== 'string')
+                    nonStringKeys.push(key);
+            }
+            if (nonStringKeys.length === 0)
+                return [];
+            return [
+                {
+                    message: `metadata values must be strings; non-string keys: ${nonStringKeys.join(', ')}`,
+                    suggestion: 'Convert metadata values to strings, e.g. version: "1.0" instead of version: 1.0',
+                },
+            ];
+        },
+    },
+    {
+        id: 'frontmatter.allowed_tools_format',
+        description: 'allowed-tools field must be a space-delimited string.',
+        defaultSeverity: 'warn',
+        evaluate(skill) {
+            if (!skill.frontmatter)
+                return [];
+            const value = skill.frontmatter['allowed-tools'];
+            if (value === undefined || value === null)
+                return [];
+            if (typeof value === 'string')
+                return [];
+            return [
+                {
+                    message: 'allowed-tools must be a string (space-delimited tool list)',
+                    suggestion: 'Use a space-delimited string, e.g. allowed-tools: Bash(git:*) Read',
+                },
+            ];
+        },
+    },
 ];

package/dist/types.d.ts

@@ -22,6 +22,8 @@ export interface LimitsConfig {
     maxBodyLines: number;
     minDescriptionChars: number;
     maxBodyTokens: number;
+    maxNameChars: number;
+    maxCompatibilityChars: number;
 }
 export interface OutputConfig {
     format: OutputFormat;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-check",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Linter for agent skill files",
   "type": "module",
   "private": false,

package/schemas/config.schema.json

@@ -22,7 +22,9 @@
         "maxDescriptionChars": { "type": "integer", "minimum": 1 },
         "maxBodyLines": { "type": "integer", "minimum": 1 },
         "minDescriptionChars": { "type": "integer", "minimum": 0 },
-        "maxBodyTokens": { "type": "integer", "minimum": 1 }
+        "maxBodyTokens": { "type": "integer", "minimum": 1 },
+        "maxNameChars": { "type": "integer", "minimum": 1 },
+        "maxCompatibilityChars": { "type": "integer", "minimum": 1 }
       },
       "additionalProperties": false
     },