@skillmarkdown/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SkillMarkdown
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @skillmarkdown/cli
+
+`@skillmarkdown/cli` is the official CLI for scaffolding, validating, and packaging `SKILL.md`-based AI skills. It provides the `skillmd` command, starting with deterministic, spec-aligned skill scaffolding via `skillmd init`.
+
+## Status
+
+Early development. v0 focuses on `skillmd init` and `skillmd validate`. Docs are intentionally lightweight and may evolve.
+
+## Install
+
+### Global install
+
+```bash
+npm i -g @skillmarkdown/cli
+```
+
+### Run without installing
+
+```bash
+npx @skillmarkdown/cli init
+```
+
+## Usage
+
+### Initialize a skill folder
+
+```bash
+skillmd init
+```
+
+This scaffolds a spec-aligned skill structure including `SKILL.md` and optional directories (`scripts/`, `references/`, `assets/`), then runs local validation.
+
+To skip validation during init:
+
+```bash
+skillmd init --no-validate
+```
+
+### Validate a skill folder
+
+```bash
+skillmd validate
+```
+
+You can also pass an explicit path:
+
+```bash
+skillmd validate /path/to/skill
+```
+
+Run additional scaffold/template checks:
+
+```bash
+skillmd validate --strict
+```
+
+Compare local validation with `skills-ref` (when installed):
+
+```bash
+skillmd validate --parity
+```
+
+## Development
+
+- Local testing guide: `docs/testing.md`
+- CI check script: `npm run ci:check`
+- Packed tarball smoke test: `npm run smoke:pack`
+- Optional npm link smoke test: `npm run smoke:link`
+
+## Links
+
+- Agent Skills spec: https://agentskills.io/specification
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const init_1 = require("./commands/init");
+const validate_1 = require("./commands/validate");
+function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        console.error("skillmd: no command provided");
+        console.error("Usage: skillmd <init|validate>");
+        process.exitCode = 1;
+        return;
+    }
+    if (args[0] === "init") {
+        process.exitCode = (0, init_1.runInitCommand)(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>");
+    process.exitCode = 1;
+}
+main();

package/dist/commands/init.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInitCommand = runInitCommand;
+const scaffold_1 = require("../lib/scaffold");
+const validator_1 = require("../lib/validator");
+function runInitCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const validateSkillFn = options.validateSkill ?? ((targetDir) => (0, validator_1.validateSkill)(targetDir, { strict: true }));
+    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;
+    }
+    try {
+        const result = (0, scaffold_1.scaffoldSkillInDirectory)(cwd);
+        console.log(`Initialized skill '${result.skillName}' in ${cwd}`);
+        if (skipValidation) {
+            console.log("Validation skipped (--no-validate).");
+            return 0;
+        }
+        const validation = validateSkillFn(cwd);
+        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;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        console.error(`skillmd init: ${message}`);
+        return 1;
+    }
+}

package/dist/commands/validate.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runValidateCommand = runValidateCommand;
+const node_path_1 = require("node:path");
+const validator_1 = require("../lib/validator");
+const upstream_validator_1 = require("../lib/upstream-validator");
+function runValidateCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const validateLocal = options.validateLocal ?? validator_1.validateSkill;
+    const validateUpstream = options.validateUpstream ?? upstream_validator_1.validateWithSkillsRef;
+    let strict = false;
+    let parity = false;
+    let pathArg;
+    for (const arg of args) {
+        if (arg === "--strict") {
+            strict = true;
+            continue;
+        }
+        if (arg === "--parity") {
+            parity = true;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            console.error(`skillmd validate: unsupported flag '${arg}'`);
+            console.error("Usage: skillmd validate [path] [--strict] [--parity]");
+            return 1;
+        }
+        if (pathArg) {
+            console.error("skillmd validate: accepts at most one path argument");
+            console.error("Usage: skillmd validate [path] [--strict] [--parity]");
+            return 1;
+        }
+        pathArg = arg;
+    }
+    const targetDir = pathArg ? (0, node_path_1.resolve)(cwd, pathArg) : cwd;
+    const validation = validateLocal(targetDir, { strict });
+    if (parity) {
+        const upstream = validateUpstream(targetDir);
+        if (upstream.status === "unavailable") {
+            console.error(`Validation parity unavailable: ${upstream.message}. Install skills-ref to use --parity.`);
+            return 1;
+        }
+        if (validation.status === "passed" && upstream.status !== "passed") {
+            console.error("Validation parity mismatch: local validation passed but skills-ref failed.");
+            console.error(`skills-ref: ${upstream.message}`);
+            return 1;
+        }
+        if (validation.status === "failed" && upstream.status !== "failed") {
+            console.error("Validation parity mismatch: local validation failed but skills-ref passed.");
+            return 1;
+        }
+    }
+    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).");
+    }
+    return 1;
+}

package/dist/lib/normalize-name.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeSkillName = normalizeSkillName;
+exports.getMaxSkillNameLength = getMaxSkillNameLength;
+const MAX_SKILL_NAME_LENGTH = 64;
+function normalizeSkillName(input) {
+    const normalized = input
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    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 (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(normalized)) {
+        throw new Error("skill name must use lowercase letters, numbers, and single hyphens only");
+    }
+    return normalized;
+}
+function getMaxSkillNameLength() {
+    return MAX_SKILL_NAME_LENGTH;
+}

package/dist/lib/scaffold.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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 templates_1 = require("./templates");
+function assertDirectoryEmpty(targetDir) {
+    const entries = (0, node_fs_1.readdirSync)(targetDir);
+    if (entries.length > 0) {
+        throw new Error(`target directory is not empty (${entries.length} item(s) found); run 'skillmd init' in an empty directory`);
+    }
+}
+function assertDirectoryNameMatchesNormalized(targetDir) {
+    const dirName = (0, node_path_1.basename)(targetDir);
+    const normalizedName = (0, normalize_name_1.normalizeSkillName)(dirName);
+    if (dirName !== normalizedName) {
+        throw new Error(`directory name '${dirName}' must already be normalized. Rename it to '${normalizedName}' and retry`);
+    }
+    return normalizedName;
+}
+function scaffoldSkillInDirectory(targetDir) {
+    const skillName = assertDirectoryNameMatchesNormalized(targetDir);
+    assertDirectoryEmpty(targetDir);
+    const directories = ["scripts", "references", "assets"];
+    for (const directory of 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");
+    }
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(targetDir, "SKILL.md"), (0, templates_1.buildSkillMarkdown)(skillName), "utf8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(targetDir, ".gitignore"), (0, templates_1.buildGitignore)(), "utf8");
+    return { skillName };
+}

package/dist/lib/templates.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSkillMarkdown = buildSkillMarkdown;
+exports.buildGitignore = buildGitignore;
+function buildSkillMarkdown(name) {
+    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
+`;
+}
+function buildGitignore() {
+    return `node_modules/
+dist/
+.DS_Store
+npm-debug.log*
+`;
+}

package/dist/lib/upstream-validator.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateWithSkillsRef = validateWithSkillsRef;
+const node_child_process_1 = require("node:child_process");
+function formatOutput(stdout, stderr) {
+    return [stdout.trim(), stderr.trim()].filter((part) => part.length > 0).join("\n");
+}
+function validateWithSkillsRef(targetDir) {
+    const result = (0, node_child_process_1.spawnSync)("skills-ref", ["validate", targetDir], {
+        encoding: "utf8",
+    });
+    if (result.error) {
+        if ("code" in result.error && result.error.code === "ENOENT") {
+            return {
+                status: "unavailable",
+                message: "skills-ref is not installed or not on PATH",
+            };
+        }
+        return {
+            status: "unavailable",
+            message: `skills-ref execution failed: ${result.error.message}`,
+        };
+    }
+    const output = formatOutput(result.stdout ?? "", result.stderr ?? "");
+    if (result.status === 0) {
+        return {
+            status: "passed",
+            message: output || "skills-ref validation passed",
+        };
+    }
+    return {
+        status: "failed",
+        message: output || "skills-ref validation failed",
+    };
+}

package/dist/lib/validator.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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",
+];
+function stripUtf8Bom(content) {
+    return content.replace(/^\uFEFF/, "");
+}
+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]);
+    }
+    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);
+}
+function isStringMap(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    return 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 = (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;
+    }
+    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);
+    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");
+        }
+        if (name !== directoryName) {
+            errors.push(`frontmatter 'name' (${name}) must match directory name (${directoryName})`);
+        }
+    }
+    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") {
+        errors.push("frontmatter 'license' must be a string when provided");
+    }
+    if (compatibility !== undefined) {
+        if (typeof compatibility !== "string") {
+            errors.push("frontmatter 'compatibility' must be a string when provided");
+        }
+        else if (compatibility.length < 1 || compatibility.length > 500) {
+            errors.push("frontmatter 'compatibility' must be 1-500 characters");
+        }
+    }
+    if (metadata !== undefined && !isStringMap(metadata)) {
+        errors.push("frontmatter 'metadata' must be a mapping of string keys to string values");
+    }
+    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}`);
+        }
+    }
+    return errors;
+}
+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) {
+        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) {
+            continue;
+        }
+        if (headingPattern.test(line.replace(/\r$/, ""))) {
+            return true;
+        }
+    }
+    return false;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function validateSkill(targetDir, options = {}) {
+    const errors = collectSpecErrors(targetDir);
+    if (options.strict) {
+        errors.push(...collectStrictScaffoldErrors(targetDir));
+    }
+    if (errors.length === 0) {
+        return {
+            status: "passed",
+            message: options.strict
+                ? "Spec and strict scaffold validation passed."
+                : "Spec validation passed.",
+        };
+    }
+    return {
+        status: "failed",
+        message: errors.join("; "),
+    };
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@skillmarkdown/cli",
+  "version": "0.1.0",
+  "description": "CLI for scaffolding SKILL.md-based AI skills",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "skillmd": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "dist/cli.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "ci:check": "npm run format:check && npm run lint && npm test",
+    "clean": "rm -rf dist",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.js\" \"*.{json,mjs}\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.js\" \"*.{json,mjs}\"",
+    "prepare": "husky",
+    "prepublishOnly": "npm run clean && npm run build",
+    "smoke:link": "bash ./scripts/smoke-link.sh",
+    "smoke:pack": "bash ./scripts/smoke-pack.sh",
+    "test": "npm run build && node --test tests/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skillmarkdown/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/skillmarkdown/cli/issues"
+  },
+  "homepage": "https://github.com/skillmarkdown/cli#readme",
+  "keywords": [
+    "skillmarkdown",
+    "skillmd",
+    "cli"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.3.2",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "eslint": "^10.0.2",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.3.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3"
+  },
+  "lint-staged": {
+    "*.{ts,js}": [
+      "eslint --fix --max-warnings=0",
+      "prettier --write"
+    ],
+    "*.{json,mjs,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
+  "dependencies": {
+    "yaml": "^2.8.2"
+  }
+}