@skillmarkdown/cli 0.2.0 → 0.2.2

package/README.md

@@ -28,7 +28,31 @@ npx @skillmarkdown/cli init
 skillmd init
 ```
 
-This scaffolds a spec-aligned skill structure including `SKILL.md` and optional directories (`scripts/`, `references/`, `assets/`), then runs local validation.
+Default `init` creates the minimal filesystem scaffold:
+
+- `SKILL.md` only
+
+and runs spec validation.
+
+To scaffold the full verbose template:
+
+```bash
+skillmd init --template verbose
+```
+
+The `verbose` template includes `SKILL.md`, `.gitignore`, and optional directories (`scripts/`, `references/`, `assets/`) with starter placeholder content and `.gitkeep`, then runs strict validation.
+
+Included starter files:
+
+- `scripts/README.md`
+- `scripts/extract.py`
+- `references/REFERENCE.md`
+- `references/FORMS.md`
+- `assets/README.md`
+- `assets/report-template.md`
+- `assets/lookup-table.csv`
+
+`SKILL.md` content is the same across `minimal` and `verbose` templates. Template selection only changes extra scaffold files/directories around `SKILL.md`.
 
 To skip validation during init:
 
@@ -36,6 +60,11 @@ To skip validation during init:
 skillmd init --no-validate
 ```
 
+Supported templates:
+
+- `minimal` (default)
+- `verbose`
+
 ### Validate a skill folder
 
 ```bash
@@ -74,6 +103,7 @@ By default, `login` uses the project’s built-in development config. You can ov
 
 - `SKILLMD_GITHUB_CLIENT_ID`
 - `SKILLMD_FIREBASE_API_KEY`
+- `SKILLMD_FIREBASE_PROJECT_ID`
 
 See `.env.example` for the expected keys.
 Maintainers: built-in defaults are defined in `src/lib/auth-defaults.ts`.
@@ -94,6 +124,8 @@ skillmd login --reauth
 skillmd logout
 ```
 
+`skillmd login --status` includes the authenticated Firebase project so you can confirm whether the active session is for `skillmarkdown` or `skillmarkdown-development`.
+
 When a saved session exists, `skillmd login` verifies the stored refresh token. If it is invalid/expired, the CLI automatically starts a new login flow. If verification is inconclusive (for example network timeout), the command exits non-zero and keeps the current session.
 
 ## Development

package/dist/cli.js

@@ -30,4 +30,8 @@ async function main() {
     console.error(cli_text_1.ROOT_USAGE);
     process.exitCode = 1;
 }
-void main();
+void main().catch((error) => {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    console.error(`skillmd: ${message}`);
+    process.exitCode = 1;
+});

package/dist/commands/init.js

@@ -5,22 +5,53 @@ 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 parseInitArgs(args) {
+    let skipValidation = false;
+    let template = "minimal";
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--no-validate") {
+            skipValidation = true;
+            continue;
+        }
+        if (arg === "--template") {
+            const nextValue = args[index + 1];
+            const resolved = nextValue ? (0, scaffold_1.resolveInitTemplateId)(nextValue) : null;
+            if (!resolved) {
+                return { skipValidation: false, template: "minimal", valid: false };
+            }
+            template = resolved;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--template=")) {
+            const value = arg.slice("--template=".length);
+            const resolved = (0, scaffold_1.resolveInitTemplateId)(value);
+            if (!resolved) {
+                return { skipValidation: false, template: "minimal", valid: false };
+            }
+            template = resolved;
+            continue;
+        }
+        return { skipValidation: false, template: "minimal", valid: false };
+    }
+    return { skipValidation, template, valid: true };
+}
 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) {
+    const validateSkillFn = options.validateSkill ?? validator_1.validateSkill;
+    const { skipValidation, template, valid } = parseInitArgs(args);
+    if (!valid) {
         return (0, command_output_1.failWithUsage)("skillmd init: unsupported argument(s)", cli_text_1.INIT_USAGE);
     }
     try {
-        const result = (0, scaffold_1.scaffoldSkillInDirectory)(cwd);
+        const result = (0, scaffold_1.scaffoldSkillInDirectory)(cwd, { template });
         console.log(`Initialized skill '${result.skillName}'.`);
         if (skipValidation) {
             console.log("Validation skipped (--no-validate).");
             return 0;
         }
-        const validation = validateSkillFn(cwd);
+        const validation = validateSkillFn(cwd, { strict: result.template === "verbose" });
         (0, command_output_1.printValidationResult)(validation);
         if (validation.status === "passed") {
             return 0;

package/dist/commands/login.js

@@ -26,16 +26,34 @@ function parseFlags(args) {
     }
     return { status, reauth, valid: true };
 }
-function printSessionStatus(session) {
+function formatSessionProject(session, currentConfigProjectId) {
+    if (!session.projectId) {
+        if (currentConfigProjectId) {
+            return { label: `unknown (current config: ${currentConfigProjectId})`, mismatch: false };
+        }
+        return { label: "unknown", mismatch: false };
+    }
+    return {
+        label: session.projectId,
+        mismatch: Boolean(currentConfigProjectId && session.projectId !== currentConfigProjectId),
+    };
+}
+function printSessionStatus(session, currentConfigProjectId) {
     if (!session) {
         console.log("Not logged in.");
         return 1;
     }
+    const project = formatSessionProject(session, currentConfigProjectId);
     if (session.email) {
-        console.log(`Logged in with GitHub as ${session.email}.`);
-        return 0;
+        console.log(`Logged in with GitHub as ${session.email} (project: ${project.label}).`);
+    }
+    else {
+        console.log(`Logged in with GitHub (uid: ${session.uid}, project: ${project.label}).`);
+    }
+    if (project.mismatch && currentConfigProjectId) {
+        console.log(`Current CLI config targets project '${currentConfigProjectId}'. ` +
+            "Run 'skillmd login --reauth' to switch projects.");
     }
-    console.log(`Logged in with GitHub (uid: ${session.uid}).`);
     return 0;
 }
 function requireConfig(env) {
@@ -57,22 +75,29 @@ async function runLoginCommand(args, options = {}) {
     const readSessionFn = options.readSession ?? auth_session_1.readAuthSession;
     const writeSessionFn = options.writeSession ?? auth_session_1.writeAuthSession;
     const clearSessionFn = options.clearSession ?? auth_session_1.clearAuthSession;
-    if (status) {
-        return printSessionStatus(readSessionFn());
-    }
     try {
         const config = requireConfig(options.env ?? process.env);
+        if (status) {
+            return printSessionStatus(readSessionFn(), config.firebaseProjectId);
+        }
         const existingSession = readSessionFn();
         if (existingSession && !reauth) {
             const verifyRefreshTokenFn = options.verifyRefreshToken ?? firebase_auth_1.verifyFirebaseRefreshToken;
             try {
                 const validation = await verifyRefreshTokenFn(config.firebaseApiKey, existingSession.refreshToken);
                 if (validation.valid) {
+                    const project = formatSessionProject(existingSession, config.firebaseProjectId);
                     if (existingSession.email) {
-                        console.log(`Already logged in as ${existingSession.email}. Run 'skillmd logout' first.`);
+                        console.log(`Already logged in as ${existingSession.email} (project: ${project.label}). ` +
+                            "Run 'skillmd logout' first.");
                     }
                     else {
-                        console.log("Already logged in. Run 'skillmd logout' first.");
+                        console.log(`Already logged in (uid: ${existingSession.uid}, project: ${project.label}). ` +
+                            "Run 'skillmd logout' first.");
+                    }
+                    if (project.mismatch) {
+                        console.log(`Current CLI config targets project '${config.firebaseProjectId}'. ` +
+                            "Run 'skillmd login --reauth' to switch projects.");
                     }
                     return 0;
                 }
@@ -100,12 +125,13 @@ async function runLoginCommand(args, options = {}) {
             uid: firebaseSession.localId,
             email: firebaseSession.email,
             refreshToken: firebaseSession.refreshToken,
+            projectId: config.firebaseProjectId,
         });
         if (firebaseSession.email) {
-            console.log(`Login successful. Signed in as ${firebaseSession.email}.`);
+            console.log(`Login successful. Signed in as ${firebaseSession.email} (project: ${config.firebaseProjectId}).`);
         }
         else {
-            console.log("Login successful.");
+            console.log(`Login successful (project: ${config.firebaseProjectId}).`);
         }
         return 0;
     }

package/dist/commands/logout.js

@@ -8,12 +8,19 @@ function runLogoutCommand(args, options = {}) {
     if (args.length > 0) {
         return (0, command_output_1.failWithUsage)("skillmd logout: unsupported argument(s)", cli_text_1.LOGOUT_USAGE);
     }
-    const clearSessionFn = options.clearSession ?? auth_session_1.clearAuthSession;
-    const removed = clearSessionFn();
-    if (removed) {
-        console.log("Logged out.");
+    try {
+        const clearSessionFn = options.clearSession ?? auth_session_1.clearAuthSession;
+        const removed = clearSessionFn();
+        if (removed) {
+            console.log("Logged out.");
+            return 0;
+        }
+        console.log("No active session to log out.");
         return 0;
     }
-    console.log("No active session to log out.");
-    return 0;
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        console.error(`skillmd logout: ${message}`);
+        return 1;
+    }
 }

package/dist/commands/validate.js

@@ -7,56 +7,63 @@ 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;
-    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;
+    try {
+        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("-")) {
+                return (0, command_output_1.failWithUsage)(`skillmd validate: unsupported flag '${arg}'`, cli_text_1.VALIDATE_USAGE);
+            }
+            if (pathArg) {
+                return (0, command_output_1.failWithUsage)("skillmd validate: accepts at most one path argument", cli_text_1.VALIDATE_USAGE);
+            }
+            pathArg = arg;
         }
-        if (arg === "--parity") {
-            parity = true;
-            continue;
-        }
-        if (arg.startsWith("-")) {
-            return (0, command_output_1.failWithUsage)(`skillmd validate: unsupported flag '${arg}'`, cli_text_1.VALIDATE_USAGE);
-        }
-        if (pathArg) {
-            return (0, command_output_1.failWithUsage)("skillmd validate: accepts at most one path argument", cli_text_1.VALIDATE_USAGE);
-        }
-        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;
+        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 === "failed" && upstream.status !== "failed") {
-            console.error("Validation parity mismatch: local validation failed but skills-ref passed.");
-            return 1;
+        (0, command_output_1.printValidationResult)(validation);
+        if (validation.status === "passed") {
+            if (parity) {
+                console.log("Validation parity passed (skills-ref).");
+            }
+            return 0;
         }
-    }
-    (0, command_output_1.printValidationResult)(validation);
-    if (validation.status === "passed") {
         if (parity) {
-            console.log("Validation parity passed (skills-ref).");
+            console.error("Validation parity matched (skills-ref also failed).");
         }
-        return 0;
+        return 1;
     }
-    if (parity) {
-        console.error("Validation parity matched (skills-ref also failed).");
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        console.error(`skillmd validate: ${message}`);
+        return 1;
     }
-    return 1;
 }

package/dist/lib/auth-config.js

@@ -54,12 +54,14 @@ function getLoginEnvConfig(env = process.env, options = {}) {
     const dotEnv = loadDotEnv(getDefaultUserEnvPath(options));
     const githubClientId = pickValue(env.SKILLMD_GITHUB_CLIENT_ID, dotEnv.SKILLMD_GITHUB_CLIENT_ID, auth_defaults_1.DEFAULT_LOGIN_AUTH_CONFIG.githubClientId);
     const firebaseApiKey = pickValue(env.SKILLMD_FIREBASE_API_KEY, dotEnv.SKILLMD_FIREBASE_API_KEY, auth_defaults_1.DEFAULT_LOGIN_AUTH_CONFIG.firebaseApiKey);
-    if (!githubClientId || !firebaseApiKey) {
+    const firebaseProjectId = pickValue(env.SKILLMD_FIREBASE_PROJECT_ID, dotEnv.SKILLMD_FIREBASE_PROJECT_ID, auth_defaults_1.DEFAULT_LOGIN_AUTH_CONFIG.firebaseProjectId);
+    if (!githubClientId || !firebaseApiKey || !firebaseProjectId) {
         throw new Error("missing login configuration");
     }
     return {
         githubClientId,
         firebaseApiKey,
+        firebaseProjectId,
     };
 }
 function getDefaultUserEnvPath(options = {}) {

package/dist/lib/auth-defaults.js

@@ -5,4 +5,5 @@ exports.DEFAULT_LOGIN_AUTH_CONFIG = void 0;
 exports.DEFAULT_LOGIN_AUTH_CONFIG = Object.freeze({
     githubClientId: "Ov23lixkdtyLp35IFaBG",
     firebaseApiKey: "AIzaSyAkaZRmpCvZasFjeRAfW_b0V0nUcGOTjok",
+    firebaseProjectId: "skillmarkdown",
 });

package/dist/lib/auth-session.js

@@ -28,6 +28,12 @@ function readAuthSession(sessionPath = SESSION_PATH) {
         if (parsed.email !== undefined && typeof parsed.email !== "string") {
             return null;
         }
+        if (parsed.projectId !== undefined && typeof parsed.projectId !== "string") {
+            return null;
+        }
+        if (typeof parsed.projectId === "string" && parsed.projectId.length === 0) {
+            return null;
+        }
         return parsed;
     }
     catch {

package/dist/lib/cli-text.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LOGOUT_USAGE = exports.LOGIN_USAGE = exports.VALIDATE_USAGE = exports.INIT_USAGE = exports.ROOT_USAGE = void 0;
 exports.ROOT_USAGE = "Usage: skillmd <init|validate|login|logout>";
-exports.INIT_USAGE = "Usage: skillmd init [--no-validate]";
+exports.INIT_USAGE = "Usage: skillmd init [--no-validate] [--template <minimal|verbose>]";
 exports.VALIDATE_USAGE = "Usage: skillmd validate [path] [--strict] [--parity]";
 exports.LOGIN_USAGE = "Usage: skillmd login [--status|--reauth]";
 exports.LOGOUT_USAGE = "Usage: skillmd logout";

package/dist/lib/firebase-auth.js

@@ -60,7 +60,9 @@ async function verifyFirebaseRefreshToken(apiKey, refreshToken) {
     }
     const errorMessage = payload.error?.message ?? "";
     if (response.status === 400 &&
-        (errorMessage === "INVALID_REFRESH_TOKEN" || errorMessage === "TOKEN_EXPIRED")) {
+        (errorMessage === "INVALID_REFRESH_TOKEN" ||
+            errorMessage === "TOKEN_EXPIRED" ||
+            errorMessage === "PROJECT_NUMBER_MISMATCH")) {
         return { valid: false };
     }
     throw new Error(`Firebase token verification failed (${response.status}): ${errorMessage || "unknown error"}`);

package/dist/lib/scaffold.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInitTemplateId = isInitTemplateId;
+exports.resolveInitTemplateId = resolveInitTemplateId;
 exports.scaffoldSkillInDirectory = scaffoldSkillInDirectory;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -20,15 +22,58 @@ function assertDirectoryNameMatchesNormalized(targetDir) {
     }
     return normalizedName;
 }
-function scaffoldSkillInDirectory(targetDir) {
+function isInitTemplateId(value) {
+    return skill_spec_1.INIT_TEMPLATE_IDS.includes(value);
+}
+function resolveInitTemplateId(value) {
+    return isInitTemplateId(value) ? value : null;
+}
+function createDirectory(path, createdPaths) {
+    (0, node_fs_1.mkdirSync)(path, { recursive: false, mode: 0o755 });
+    createdPaths.push({ kind: "dir", path });
+}
+function createFile(path, content, createdPaths) {
+    (0, node_fs_1.writeFileSync)(path, content, { encoding: "utf8", flag: "wx", mode: 0o644 });
+    (0, node_fs_1.chmodSync)(path, 0o644);
+    createdPaths.push({ kind: "file", path });
+}
+function rollbackCreatedPaths(createdPaths) {
+    for (const entry of [...createdPaths].reverse()) {
+        if (entry.kind === "file") {
+            (0, node_fs_1.rmSync)(entry.path, { force: true });
+            continue;
+        }
+        (0, node_fs_1.rmSync)(entry.path, { recursive: true, force: true });
+    }
+}
+function scaffoldSkillInDirectory(targetDir, options = {}) {
+    const template = options.template ?? "minimal";
     const skillName = assertDirectoryNameMatchesNormalized(targetDir);
     assertDirectoryEmpty(targetDir);
-    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");
+    const createdPaths = [];
+    try {
+        if (template === "verbose") {
+            for (const directory of skill_spec_1.SCAFFOLD_DIRECTORIES) {
+                const fullPath = (0, node_path_1.join)(targetDir, directory);
+                createDirectory(fullPath, createdPaths);
+                createFile((0, node_path_1.join)(fullPath, ".gitkeep"), "", createdPaths);
+            }
+            createFile((0, node_path_1.join)(targetDir, ".gitignore"), (0, templates_1.buildGitignore)(), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "SKILL.md"), (0, templates_1.buildVerboseSkillMarkdown)(skillName), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "scripts", "README.md"), (0, templates_1.buildScriptsReadme)(), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "scripts", "extract.py"), (0, templates_1.buildExtractScriptPython)(), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "references", "REFERENCE.md"), (0, templates_1.buildReferenceGuide)(), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "references", "FORMS.md"), (0, templates_1.buildFormsReference)(), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "assets", "README.md"), (0, templates_1.buildAssetsReadme)(), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "assets", "report-template.md"), (0, templates_1.buildReportTemplate)(), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "assets", "lookup-table.csv"), (0, templates_1.buildLookupTableCsv)(), createdPaths);
+            return { skillName, template };
+        }
+        createFile((0, node_path_1.join)(targetDir, "SKILL.md"), (0, templates_1.buildMinimalSkillMarkdown)(skillName), createdPaths);
+        return { skillName, template };
+    }
+    catch (error) {
+        rollbackCreatedPaths(createdPaths);
+        throw error;
     }
-    (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/skill-spec.js

@@ -1,7 +1,8 @@
 "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.STRICT_SECTION_HEADINGS = exports.STRICT_SECTION_TITLES = exports.STRICT_REQUIRED_FILES = exports.SCAFFOLD_DIRECTORIES = exports.INIT_TEMPLATE_IDS = exports.MAX_SKILL_NAME_LENGTH = void 0;
 exports.MAX_SKILL_NAME_LENGTH = 64;
+exports.INIT_TEMPLATE_IDS = ["minimal", "verbose"];
 exports.SCAFFOLD_DIRECTORIES = ["scripts", "references", "assets"];
 exports.STRICT_REQUIRED_FILES = [
     ".gitignore",

package/dist/lib/templates.js

@@ -1,19 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildSkillMarkdown = buildSkillMarkdown;
+exports.buildMinimalSkillMarkdown = buildMinimalSkillMarkdown;
+exports.buildVerboseSkillMarkdown = buildVerboseSkillMarkdown;
 exports.buildGitignore = buildGitignore;
+exports.buildScriptsReadme = buildScriptsReadme;
+exports.buildExtractScriptPython = buildExtractScriptPython;
+exports.buildReferenceGuide = buildReferenceGuide;
+exports.buildFormsReference = buildFormsReference;
+exports.buildAssetsReadme = buildAssetsReadme;
+exports.buildReportTemplate = buildReportTemplate;
+exports.buildLookupTableCsv = buildLookupTableCsv;
 const skill_spec_1 = require("./skill-spec");
+const SECTION_PLACEHOLDERS = {
+    Scope: "Define the boundaries of this skill: what it should and should not handle.",
+    "When to use": "Describe the signals or request patterns that should trigger this skill. Keep SKILL.md focused and move deep details into references/ files.",
+    Inputs: "List required and optional inputs, expected formats, and assumptions. Add structured templates to references/FORMS.md when helpful.",
+    Outputs: "Describe expected outputs, side effects, and completion criteria. Use assets/report-template.md when a fixed output structure is useful.",
+    "Steps / Procedure": "Provide ordered steps the agent should follow, including key decision points. See [the reference guide](references/REFERENCE.md) for detailed rules. Run helper scripts such as scripts/extract.py when needed.",
+    Examples: "Add one or two realistic examples of inputs and expected outputs.",
+    "Limitations / Failure modes": "Document known limitations, failure cases, and recommended recovery actions.",
+    "Security / Tool access": "State required tools/permissions and any security constraints. If needed, set frontmatter allowed-tools to pre-approve tool usage.",
+};
 function buildSkillMarkdown(name) {
-    const sections = skill_spec_1.STRICT_SECTION_TITLES.map((title) => `## ${title}\nTODO`).join("\n\n");
+    const sections = skill_spec_1.STRICT_SECTION_TITLES.map((title) => `## ${title}\n\n${SECTION_PLACEHOLDERS[title]}`).join("\n\n");
     return `---
 name: ${name}
-description: "TODO: Describe what this skill does and when to use it."
-license: TODO
+description: Explain what this skill does and when an agent should use it.
+# compatibility: "Optional: environment requirements (products, packages, network access)."
+# metadata:
+#   author: "your-org"
+#   version: "1.0.0"
+# allowed-tools: "Optional: space-delimited pre-approved tools."
+license: Optional. Add a license name or reference to a bundled license file.
 ---
 
 ${sections}
 `;
 }
+function buildMinimalSkillMarkdown(name) {
+    return buildSkillMarkdown(name);
+}
+function buildVerboseSkillMarkdown(name) {
+    return buildSkillMarkdown(name);
+}
 function buildGitignore() {
     return `node_modules/
 dist/
@@ -21,3 +51,155 @@ dist/
 npm-debug.log*
 `;
 }
+function buildScriptsReadme() {
+    return `# scripts/
+
+Use this folder for executable code that agents can run.
+
+Guidelines:
+- Keep scripts self-contained or clearly document dependencies.
+- Emit actionable error messages.
+- Handle edge cases (missing files, invalid input, empty data).
+
+Starter script:
+- \`scripts/extract.py\`
+`;
+}
+function buildExtractScriptPython() {
+    return `#!/usr/bin/env python3
+"""Example extraction script with defensive error handling.
+
+Usage:
+  python3 scripts/extract.py --input ./input.txt --output ./output.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Extract line and word statistics.")
+    parser.add_argument("--input", required=True, help="Path to input text file.")
+    parser.add_argument("--output", required=True, help="Path to output JSON file.")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+
+    if not os.path.exists(args.input):
+        print(f"error: input file does not exist: {args.input}", file=sys.stderr)
+        return 1
+
+    try:
+        with open(args.input, "r", encoding="utf-8") as source:
+            content = source.read()
+    except OSError as error:
+        print(f"error: failed to read input file: {error}", file=sys.stderr)
+        return 1
+
+    lines = [line for line in content.splitlines() if line.strip()]
+    result = {
+        "line_count": len(lines),
+        "word_count": len(content.split()),
+        "preview": lines[:3],
+    }
+
+    try:
+        with open(args.output, "w", encoding="utf-8") as destination:
+            json.dump(result, destination, indent=2)
+            destination.write("\\n")
+    except OSError as error:
+        print(f"error: failed to write output file: {error}", file=sys.stderr)
+        return 1
+
+    print(f"wrote extraction summary to {args.output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+`;
+}
+function buildReferenceGuide() {
+    return `# Reference Guide
+
+Use this file for detailed technical reference that should not live in \`SKILL.md\`.
+
+Suggested sections:
+- Data model and field definitions
+- Validation rules and constraints
+- External API contract notes
+- Error catalog and recovery guidance
+
+Keep this file focused and concise. Add deeper detail in additional reference files when needed.
+`;
+}
+function buildFormsReference() {
+    return `# Forms and Structured Templates
+
+Use this file to store reusable form structures and payload templates.
+
+## Intake Form (Example)
+
+\`\`\`yaml
+request_id: "REQ-0001"
+request_type: "analysis"
+priority: "normal"
+inputs:
+  source_path: "./input.txt"
+  output_path: "./output.json"
+\`\`\`
+
+## Result Envelope (Example)
+
+\`\`\`json
+{
+  "status": "ok",
+  "summary": "One-line result summary",
+  "artifacts": []
+}
+\`\`\`
+`;
+}
+function buildAssetsReadme() {
+    return `# assets/
+
+Use this folder for static resources that scripts or instructions can reference:
+- templates
+- lookup tables
+- example data
+- diagrams
+
+Keep asset files small and task-focused.
+`;
+}
+function buildReportTemplate() {
+    return `# Report Template
+
+## Summary
+- Status:
+- Owner:
+- Updated:
+
+## Findings
+1.
+2.
+3.
+
+## Next Steps
+1.
+2.
+`;
+}
+function buildLookupTableCsv() {
+    return `code,label,description
+E001,missing_input,Required input file is missing
+E002,invalid_format,Input format is invalid or unsupported
+E003,write_failed,Output could not be written
+`;
+}

package/dist/lib/upstream-validator.js

@@ -2,12 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateWithSkillsRef = validateWithSkillsRef;
 const node_child_process_1 = require("node:child_process");
+const SKILLS_REF_TIMEOUT_MS = 10000;
 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",
+        timeout: SKILLS_REF_TIMEOUT_MS,
     });
     if (result.error) {
         if ("code" in result.error && result.error.code === "ENOENT") {
@@ -16,6 +18,12 @@ function validateWithSkillsRef(targetDir) {
                 message: "skills-ref is not installed or not on PATH",
             };
         }
+        if ("code" in result.error && result.error.code === "ETIMEDOUT") {
+            return {
+                status: "unavailable",
+                message: `skills-ref timed out after ${SKILLS_REF_TIMEOUT_MS}ms`,
+            };
+        }
         return {
             status: "unavailable",
             message: `skills-ref execution failed: ${result.error.message}`,

package/package.json

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