@skillmarkdown/cli 0.1.3 → 0.1.5

package/README.md

@@ -42,6 +42,8 @@ skillmd init --no-validate
 skillmd validate
 ```
 
+Default `validate` is spec-only. It checks `SKILL.md` and frontmatter rules, and does not require scaffold directories/files.
+
 You can also pass an explicit path:
 
 ```bash
@@ -54,6 +56,8 @@ Run additional scaffold/template checks:
 skillmd validate --strict
 ```
 
+`--strict` is intentionally stronger than base spec mode and enforces scaffold/template conventions (for example `.gitkeep` files and required section headings).
+
 Compare local validation with `skills-ref` (when installed):
 
 ```bash

package/dist/cli.js

@@ -3,24 +3,27 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const init_1 = require("./commands/init");
 const validate_1 = require("./commands/validate");
+const cli_text_1 = require("./lib/cli-text");
+const COMMAND_HANDLERS = {
+    init: init_1.runInitCommand,
+    validate: validate_1.runValidateCommand,
+};
 function main() {
     const args = process.argv.slice(2);
+    const command = args[0];
     if (args.length === 0) {
         console.error("skillmd: no command provided");
-        console.error("Usage: skillmd <init|validate>");
+        console.error(cli_text_1.ROOT_USAGE);
         process.exitCode = 1;
         return;
     }
-    if (args[0] === "init") {
-        process.exitCode = (0, init_1.runInitCommand)(args.slice(1));
+    const handler = COMMAND_HANDLERS[command];
+    if (handler) {
+        process.exitCode = handler(args.slice(1));
         return;
     }
-    if (args[0] === "validate") {
-        process.exitCode = (0, validate_1.runValidateCommand)(args.slice(1));
-        return;
-    }
-    console.error(`skillmd: unknown command '${args[0]}'`);
-    console.error("Usage: skillmd <init|validate>");
+    console.error(`skillmd: unknown command '${command}'`);
+    console.error(cli_text_1.ROOT_USAGE);
     process.exitCode = 1;
 }
 main();

package/dist/commands/init.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runInitCommand = runInitCommand;
+const cli_text_1 = require("../lib/cli-text");
+const command_output_1 = require("../lib/command-output");
 const scaffold_1 = require("../lib/scaffold");
 const validator_1 = require("../lib/validator");
 function runInitCommand(args, options = {}) {
@@ -9,23 +11,20 @@ function runInitCommand(args, options = {}) {
     const skipValidation = args.includes("--no-validate");
     const hasUnsupportedArgs = args.length > 1 || (args.length === 1 && args[0] !== "--no-validate");
     if (hasUnsupportedArgs) {
-        console.error("skillmd init: unsupported argument(s)");
-        console.error("Usage: skillmd init [--no-validate]");
-        return 1;
+        return (0, command_output_1.failWithUsage)("skillmd init: unsupported argument(s)", cli_text_1.INIT_USAGE);
     }
     try {
         const result = (0, scaffold_1.scaffoldSkillInDirectory)(cwd);
-        console.log(`Initialized skill '${result.skillName}' in ${cwd}`);
+        console.log(`Initialized skill '${result.skillName}'.`);
         if (skipValidation) {
             console.log("Validation skipped (--no-validate).");
             return 0;
         }
         const validation = validateSkillFn(cwd);
+        (0, command_output_1.printValidationResult)(validation);
         if (validation.status === "passed") {
-            console.log(`Validation passed: ${validation.message}`);
             return 0;
         }
-        console.error(`Validation failed: ${validation.message}`);
         console.error("Run 'skillmd validate' after fixing issues.");
         return 1;
     }

package/dist/commands/validate.js

@@ -2,8 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runValidateCommand = runValidateCommand;
 const node_path_1 = require("node:path");
-const validator_1 = require("../lib/validator");
+const cli_text_1 = require("../lib/cli-text");
+const command_output_1 = require("../lib/command-output");
 const upstream_validator_1 = require("../lib/upstream-validator");
+const validator_1 = require("../lib/validator");
 function runValidateCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const validateLocal = options.validateLocal ?? validator_1.validateSkill;
@@ -21,14 +23,10 @@ function runValidateCommand(args, options = {}) {
             continue;
         }
         if (arg.startsWith("-")) {
-            console.error(`skillmd validate: unsupported flag '${arg}'`);
-            console.error("Usage: skillmd validate [path] [--strict] [--parity]");
-            return 1;
+            return (0, command_output_1.failWithUsage)(`skillmd validate: unsupported flag '${arg}'`, cli_text_1.VALIDATE_USAGE);
         }
         if (pathArg) {
-            console.error("skillmd validate: accepts at most one path argument");
-            console.error("Usage: skillmd validate [path] [--strict] [--parity]");
-            return 1;
+            return (0, command_output_1.failWithUsage)("skillmd validate: accepts at most one path argument", cli_text_1.VALIDATE_USAGE);
         }
         pathArg = arg;
     }
@@ -50,14 +48,13 @@ function runValidateCommand(args, options = {}) {
             return 1;
         }
     }
+    (0, command_output_1.printValidationResult)(validation);
     if (validation.status === "passed") {
-        console.log(`Validation passed: ${validation.message}`);
         if (parity) {
             console.log("Validation parity passed (skills-ref).");
         }
         return 0;
     }
-    console.error(`Validation failed: ${validation.message}`);
     if (parity) {
         console.error("Validation parity matched (skills-ref also failed).");
     }

package/dist/lib/cli-text.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALIDATE_USAGE = exports.INIT_USAGE = exports.ROOT_USAGE = void 0;
+exports.ROOT_USAGE = "Usage: skillmd <init|validate>";
+exports.INIT_USAGE = "Usage: skillmd init [--no-validate]";
+exports.VALIDATE_USAGE = "Usage: skillmd validate [path] [--strict] [--parity]";

package/dist/lib/command-output.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.failWithUsage = failWithUsage;
+exports.printValidationResult = printValidationResult;
+function failWithUsage(message, usage) {
+    console.error(message);
+    console.error(usage);
+    return 1;
+}
+function printValidationResult(validation) {
+    if (validation.status === "passed") {
+        console.log(`Validation passed: ${validation.message}`);
+        return;
+    }
+    console.error(`Validation failed: ${validation.message}`);
+}

package/dist/lib/normalize-name.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeSkillName = normalizeSkillName;
 exports.getMaxSkillNameLength = getMaxSkillNameLength;
-const MAX_SKILL_NAME_LENGTH = 64;
+const skill_spec_1 = require("./skill-spec");
 function normalizeSkillName(input) {
     const normalized = input
         .trim()
@@ -13,8 +13,8 @@ function normalizeSkillName(input) {
     if (normalized.length === 0) {
         throw new Error("skill name is empty after normalization; use letters/numbers and optional hyphens");
     }
-    if (normalized.length > MAX_SKILL_NAME_LENGTH) {
-        throw new Error(`skill name must be at most ${MAX_SKILL_NAME_LENGTH} characters`);
+    if (normalized.length > skill_spec_1.MAX_SKILL_NAME_LENGTH) {
+        throw new Error(`skill name must be at most ${skill_spec_1.MAX_SKILL_NAME_LENGTH} characters`);
     }
     if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(normalized)) {
         throw new Error("skill name must use lowercase letters, numbers, and single hyphens only");
@@ -22,5 +22,5 @@ function normalizeSkillName(input) {
     return normalized;
 }
 function getMaxSkillNameLength() {
-    return MAX_SKILL_NAME_LENGTH;
+    return skill_spec_1.MAX_SKILL_NAME_LENGTH;
 }

package/dist/lib/scaffold.js

@@ -4,6 +4,7 @@ exports.scaffoldSkillInDirectory = scaffoldSkillInDirectory;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const normalize_name_1 = require("./normalize-name");
+const skill_spec_1 = require("./skill-spec");
 const templates_1 = require("./templates");
 function assertDirectoryEmpty(targetDir) {
     const entries = (0, node_fs_1.readdirSync)(targetDir);
@@ -22,8 +23,7 @@ function assertDirectoryNameMatchesNormalized(targetDir) {
 function scaffoldSkillInDirectory(targetDir) {
     const skillName = assertDirectoryNameMatchesNormalized(targetDir);
     assertDirectoryEmpty(targetDir);
-    const directories = ["scripts", "references", "assets"];
-    for (const directory of directories) {
+    for (const directory of skill_spec_1.SCAFFOLD_DIRECTORIES) {
         const fullPath = (0, node_path_1.join)(targetDir, directory);
         (0, node_fs_1.mkdirSync)(fullPath, { recursive: true });
         (0, node_fs_1.writeFileSync)((0, node_path_1.join)(fullPath, ".gitkeep"), "", "utf8");

package/dist/lib/skill-spec.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STRICT_SECTION_HEADINGS = exports.STRICT_SECTION_TITLES = exports.STRICT_REQUIRED_FILES = exports.SCAFFOLD_DIRECTORIES = exports.MAX_SKILL_NAME_LENGTH = void 0;
+exports.MAX_SKILL_NAME_LENGTH = 64;
+exports.SCAFFOLD_DIRECTORIES = ["scripts", "references", "assets"];
+exports.STRICT_REQUIRED_FILES = [
+    ".gitignore",
+    ...exports.SCAFFOLD_DIRECTORIES.map((directory) => `${directory}/.gitkeep`),
+];
+exports.STRICT_SECTION_TITLES = [
+    "Scope",
+    "When to use",
+    "Inputs",
+    "Outputs",
+    "Steps / Procedure",
+    "Examples",
+    "Limitations / Failure modes",
+    "Security / Tool access",
+];
+exports.STRICT_SECTION_HEADINGS = exports.STRICT_SECTION_TITLES.map((title) => `## ${title}`);

package/dist/lib/templates.js

@@ -2,36 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildSkillMarkdown = buildSkillMarkdown;
 exports.buildGitignore = buildGitignore;
+const skill_spec_1 = require("./skill-spec");
 function buildSkillMarkdown(name) {
+    const sections = skill_spec_1.STRICT_SECTION_TITLES.map((title) => `## ${title}\nTODO`).join("\n\n");
     return `---
 name: ${name}
 description: "TODO: Describe what this skill does and when to use it."
 license: TODO
 ---
 
-## Scope
-TODO
-
-## When to use
-TODO
-
-## Inputs
-TODO
-
-## Outputs
-TODO
-
-## Steps / Procedure
-TODO
-
-## Examples
-TODO
-
-## Limitations / Failure modes
-TODO
-
-## Security / Tool access
-TODO
+${sections}
 `;
 }
 function buildGitignore() {

package/dist/lib/validator.js

@@ -4,98 +4,78 @@ exports.validateSkill = validateSkill;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const yaml_1 = require("yaml");
-const STRICT_REQUIRED_FILES = [
-    ".gitignore",
-    "scripts/.gitkeep",
-    "references/.gitkeep",
-    "assets/.gitkeep",
-];
-const REQUIRED_SECTIONS = [
-    "## Scope",
-    "## When to use",
-    "## Inputs",
-    "## Outputs",
-    "## Steps / Procedure",
-    "## Examples",
-    "## Limitations / Failure modes",
-    "## Security / Tool access",
-];
+const skill_spec_1 = require("./skill-spec");
+const SKILL_FILE = "SKILL.md";
 function stripUtf8Bom(content) {
     return content.replace(/^\uFEFF/, "");
 }
+function readSkillContentIfExists(targetDir) {
+    const skillPath = (0, node_path_1.join)(targetDir, SKILL_FILE);
+    return (0, node_fs_1.existsSync)(skillPath) ? (0, node_fs_1.readFileSync)(skillPath, "utf8") : null;
+}
 function extractFrontmatter(content) {
     const normalizedContent = stripUtf8Bom(content);
     const match = normalizedContent.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
     if (!match || typeof match[1] !== "string") {
         return null;
     }
-    let parsed;
     try {
-        parsed = (0, yaml_1.parse)(match[1]);
+        const parsed = (0, yaml_1.parse)(match[1]);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return null;
+        }
+        return { frontmatter: parsed };
     }
     catch {
         return null;
     }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        return null;
-    }
-    return {
-        frontmatter: parsed,
-    };
 }
 function isValidSkillName(name) {
-    if (name.length === 0 || name.length > 64) {
-        return false;
-    }
-    return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);
+    return (name.length > 0 &&
+        name.length <= skill_spec_1.MAX_SKILL_NAME_LENGTH &&
+        /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name));
 }
 function isStringMap(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return false;
-    }
-    return Object.values(value).every((entry) => typeof entry === "string");
+    return (!!value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.values(value).every((entry) => typeof entry === "string"));
 }
 function collectSpecErrors(targetDir) {
-    const errors = [];
-    const skillPath = (0, node_path_1.join)(targetDir, "SKILL.md");
-    if (!(0, node_fs_1.existsSync)(skillPath)) {
-        errors.push("missing required file: SKILL.md");
-        return errors;
+    const skillContent = readSkillContentIfExists(targetDir);
+    if (!skillContent) {
+        return [`missing required file: ${SKILL_FILE}`];
     }
-    const skillContent = (0, node_fs_1.readFileSync)(skillPath, "utf8");
     const parsedSkill = extractFrontmatter(skillContent);
     if (!parsedSkill) {
-        errors.push("SKILL.md must start with valid YAML frontmatter");
-        return errors;
+        return ["SKILL.md must start with valid YAML frontmatter"];
     }
+    const errors = [];
     const { frontmatter } = parsedSkill;
-    const name = frontmatter.name;
-    const description = frontmatter.description;
-    const license = frontmatter.license;
-    const compatibility = frontmatter.compatibility;
-    const metadata = frontmatter.metadata;
-    const allowedTools = frontmatter["allowed-tools"];
     const directoryName = (0, node_path_1.basename)(targetDir);
+    const name = frontmatter.name;
     if (typeof name !== "string" || name.length === 0) {
         errors.push("frontmatter is missing required string field: name");
     }
     else {
         if (!isValidSkillName(name)) {
-            errors.push("frontmatter 'name' must be 1-64 chars using lowercase letters, numbers, and single hyphens");
+            errors.push(`frontmatter 'name' must be 1-${skill_spec_1.MAX_SKILL_NAME_LENGTH} chars using lowercase letters, numbers, and single hyphens`);
         }
         if (name !== directoryName) {
             errors.push(`frontmatter 'name' (${name}) must match directory name (${directoryName})`);
         }
     }
+    const description = frontmatter.description;
     if (typeof description !== "string" || description.trim().length === 0) {
         errors.push("frontmatter is missing required non-empty string field: description");
     }
     else if (description.length > 1024) {
         errors.push("frontmatter 'description' must be at most 1024 characters");
     }
-    if (license !== undefined && typeof license !== "string") {
+    if (frontmatter.license !== undefined && typeof frontmatter.license !== "string") {
         errors.push("frontmatter 'license' must be a string when provided");
     }
+    const compatibility = frontmatter.compatibility;
     if (compatibility !== undefined) {
         if (typeof compatibility !== "string") {
             errors.push("frontmatter 'compatibility' must be a string when provided");
@@ -104,54 +84,35 @@ function collectSpecErrors(targetDir) {
             errors.push("frontmatter 'compatibility' must be 1-500 characters");
         }
     }
-    if (metadata !== undefined && !isStringMap(metadata)) {
+    if (frontmatter.metadata !== undefined && !isStringMap(frontmatter.metadata)) {
         errors.push("frontmatter 'metadata' must be a mapping of string keys to string values");
     }
+    const allowedTools = frontmatter["allowed-tools"];
     if (allowedTools !== undefined && typeof allowedTools !== "string") {
         errors.push("frontmatter 'allowed-tools' must be a string when provided");
     }
     return errors;
 }
 function collectStrictScaffoldErrors(targetDir) {
-    const errors = [];
-    for (const requiredFile of STRICT_REQUIRED_FILES) {
-        if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(targetDir, requiredFile))) {
-            errors.push(`missing strict scaffold file: ${requiredFile}`);
-        }
-    }
-    const skillPath = (0, node_path_1.join)(targetDir, "SKILL.md");
-    if (!(0, node_fs_1.existsSync)(skillPath)) {
-        return errors;
-    }
-    const skillContent = (0, node_fs_1.readFileSync)(skillPath, "utf8");
-    for (const section of REQUIRED_SECTIONS) {
-        if (!hasHeadingOutsideFencedCode(skillContent, section)) {
-            errors.push(`SKILL.md is missing strict section: ${section}`);
-        }
+    const missingStrictFiles = skill_spec_1.STRICT_REQUIRED_FILES.filter((requiredFile) => !(0, node_fs_1.existsSync)((0, node_path_1.join)(targetDir, requiredFile))).map((requiredFile) => `missing strict scaffold file: ${requiredFile}`);
+    const skillContent = readSkillContentIfExists(targetDir);
+    if (!skillContent) {
+        return missingStrictFiles;
     }
-    return errors;
+    const missingStrictSections = skill_spec_1.STRICT_SECTION_HEADINGS.filter((section) => !hasHeadingOutsideFencedCode(skillContent, section)).map((section) => `SKILL.md is missing strict section: ${section}`);
+    return [...missingStrictFiles, ...missingStrictSections];
 }
 function hasHeadingOutsideFencedCode(content, heading) {
-    const lines = content.split(/\r?\n/);
     const headingPattern = new RegExp(`^\\s{0,3}${escapeRegExp(heading)}\\s*$`);
     let activeFence = null;
-    for (const line of lines) {
+    for (const line of content.split(/\r?\n/)) {
         const trimmed = line.trim();
         if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
             const fence = trimmed.startsWith("```") ? "```" : "~~~";
-            if (activeFence === null) {
-                activeFence = fence;
-                continue;
-            }
-            if (activeFence === fence) {
-                activeFence = null;
-                continue;
-            }
-        }
-        if (activeFence) {
+            activeFence = activeFence === fence ? null : (activeFence ?? fence);
             continue;
         }
-        if (headingPattern.test(line.replace(/\r$/, ""))) {
+        if (!activeFence && headingPattern.test(line.replace(/\r$/, ""))) {
             return true;
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillmarkdown/cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "CLI for scaffolding SKILL.md-based AI skills",
   "license": "MIT",
   "type": "commonjs",