skill-check 1.1.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

@@ -1056,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/defaults.js

@@ -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/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.1.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
     },