skissue 0.1.18 → 0.1.20

package/README.md

@@ -18,7 +18,6 @@
   <a href="https://www.npmjs.com/package/skissue"><img src="https://img.shields.io/npm/v/skissue?style=flat-square&logo=npm&color=CB3837" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/skissue"><img src="https://img.shields.io/npm/dm/skissue?style=flat-square&logo=npm&color=CB3837" alt="npm downloads"></a>
   <a href="https://github.com/midyan/skill-issue/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=flat-square" alt="License MIT"></a>
-  <a href="https://github.com/midyan/skill-issue"><img src="https://img.shields.io/github/stars/midyan/skill-issue?style=flat-square&logo=github&color=8B5CF6" alt="GitHub stars"></a>
   <img src="https://img.shields.io/badge/node-%3E%3D24-brightgreen?style=flat-square&logo=nodedotjs" alt="Node 24+">
   <img src="https://img.shields.io/badge/TypeScript-5.7-blue?style=flat-square&logo=typescript" alt="TypeScript">
 </p>
@@ -136,7 +135,7 @@ Skills are in `.agents/skills/`. Your agents can find them. Commit the folder. S
 
 A skill registry is just a Git repo with a specific layout. Here's how to build one from scratch.
 
-**Shortcut:** run `npx skissue init-registry` to create `registry.json`, `registry/<sample-skill>/SKILL.md`, and optionally `git init` in the current directory or a path you choose.
+**Shortcut:** run `npx skissue init-registry` to create `registry.json`, `registry/<skill-id>/SKILL.md` (default skill id `validate-links`), and optionally `git init` in the current directory or a path you choose.
 
 ### Registry structure
 

package/dist/entry.js

@@ -9,7 +9,7 @@ import { resolve as resolve4 } from "node:path";
 // src/commands/init.ts
 import * as p2 from "@clack/prompts";
 import chalk2 from "chalk";
-import { existsSync as existsSync4 } from "node:fs";
+import { existsSync as existsSync4, statSync as statSync3 } from "node:fs";
 import { mkdir as mkdir4 } from "node:fs/promises";
 import { relative, resolve as resolve3 } from "node:path";
 
@@ -357,6 +357,7 @@ function requiredTrimmed(v) {
 }
 
 // src/commands/init-registry.ts
+var DEFAULT_REGISTRY_SKILL_ID = "validate-links";
 function validateSkillId(raw) {
   const id = raw.trim();
   if (!id) return "Skill id is required";
@@ -367,6 +368,15 @@ function validateSkillId(raw) {
 function validateSkillIdPrompt(v) {
   return validateSkillId(String(v ?? ""));
 }
+function registryDirectoryExists(root) {
+  const regDir = join3(root, "registry");
+  if (!existsSync3(regDir)) return false;
+  try {
+    return statSync2(regDir).isDirectory();
+  } catch {
+    return false;
+  }
+}
 function registryLayoutExists(root) {
   const jsonPath = join3(root, "registry.json");
   const regDir = join3(root, "registry");
@@ -379,10 +389,23 @@ function registryLayoutExists(root) {
   }
 }
 function skillMarkdown(skillId) {
+  if (skillId === DEFAULT_REGISTRY_SKILL_ID) {
+    return `---
+name: validate-links
+description: Scan markdown for broken relative links across the repo.
+---
+
+# validate-links (soft)
+
+Use before large doc moves or when CI reports broken links. A **hard** implementation walks \`*.md\` files and checks that \`[text](relative)\` targets resolve.
+
+Add a \`hard/\` directory when you want automated checks (for example a small script or \`npm run check:links\` wired to the same rules).
+`;
+  }
   const title = skillId.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
   return `---
 name: ${skillId}
-description: Sample skill scaffolded by skissue init-registry. Replace this description.
+description: Starter skill scaffolded by skissue init-registry. Replace this description.
 ---
 
 # ${title}
@@ -391,7 +414,7 @@ A minimal starter skill for your registry.
 
 ## When to use
 
-Use when the user works with this sample capability (customize this section).
+Describe when an agent should apply this skill (customize this section).
 
 ## Instructions
 
@@ -448,8 +471,8 @@ async function promptMinimalRegistryScaffold(root) {
     }
   }
   const idRaw = await p.text({
-    message: "Sample skill id (folder name under registry/)",
-    initialValue: "sample-skill",
+    message: "Skill id (folder name under registry/)",
+    initialValue: DEFAULT_REGISTRY_SKILL_ID,
     validate: validateSkillIdPrompt
   });
   if (p.isCancel(idRaw)) {
@@ -574,6 +597,59 @@ Transport: ${mode}
 Branch: ${r.branch}
 skillsRoot: ${cfg.skillsRoot}`;
 }
+async function runLocalBootstrapFlow(cwd, resolvedRoot) {
+  const atConsumerRoot = resolvedRoot === resolve3(cwd);
+  if (atConsumerRoot && !registryLayoutExists(resolvedRoot)) {
+    const okRoot = await p2.confirm({
+      message: "This adds registry.json and registry/ at your project root. Continue?",
+      initialValue: true
+    });
+    if (p2.isCancel(okRoot) || !okRoot) {
+      p2.cancel("Aborted.");
+      return { ok: false, exitCode: 0 };
+    }
+  }
+  const prompted = await promptMinimalRegistryScaffold(resolvedRoot);
+  if (!prompted) {
+    p2.cancel("Aborted. No files were changed.");
+    return { ok: false, exitCode: 0 };
+  }
+  let result;
+  try {
+    result = await scaffoldMinimalRegistry({
+      root: resolvedRoot,
+      skillId: prompted.skillId,
+      runGitInit: prompted.runGitInit
+    });
+  } catch (e) {
+    p2.cancel(e instanceof Error ? e.message : String(e));
+    return { ok: false, exitCode: 1 };
+  }
+  if (!prompted.hadGit && !result.gitInitRan) {
+    p2.note(
+      "This folder is not a git repository. Run `git init` before using it as a local skissue registry.",
+      chalk2.yellow("Heads up")
+    );
+  }
+  const branchDefault = await gitBranchShowCurrent(resolvedRoot) ?? "main";
+  const branch = await p2.text({
+    message: "Branch label (stored in config; installs use git HEAD from that directory)",
+    initialValue: branchDefault,
+    validate: requiredTrimmed
+  });
+  if (p2.isCancel(branch)) {
+    p2.cancel("Aborted.");
+    return { ok: false, exitCode: 0 };
+  }
+  const cfg = ConfigSchema.parse({
+    registry: {
+      path: localRegistryPathForConfig(cwd, resolvedRoot),
+      branch: String(branch).trim()
+    },
+    skillsRoot: ".agents/skills"
+  });
+  return { ok: true, cfg, bootstrappedSkillId: result.skillId };
+}
 async function runInit(cwd) {
   p2.intro(chalk2.bold("skissue init"));
   const existingPath = configPath(cwd);
@@ -646,23 +722,57 @@ async function runInit(cwd) {
         process.exit(0);
       }
       const resolvedExisting = resolve3(cwd, String(regPath).trim());
-      const branchDefault = await gitBranchShowCurrent(resolvedExisting) ?? "main";
-      const branch = await p2.text({
-        message: "Branch label (stored in config; installs use git HEAD from that directory)",
-        initialValue: branchDefault,
-        validate: requiredTrimmed
-      });
-      if (p2.isCancel(branch)) {
-        p2.cancel("Aborted.");
-        process.exit(0);
+      if (!existsSync4(resolvedExisting) || !statSync3(resolvedExisting).isDirectory()) {
+        p2.cancel(`Path does not exist or is not a directory: ${resolvedExisting}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (!registryDirectoryExists(resolvedExisting)) {
+        const pathLabel = String(regPath).trim() || ".";
+        const bootstrapHere = await p2.confirm({
+          message: `${chalk2.yellow("No registry/ directory")} at ${chalk2.cyan(pathLabel)}. Bootstrap a minimal sample registry (registry.json + registry/<skill>) here?`,
+          initialValue: true
+        });
+        if (p2.isCancel(bootstrapHere)) {
+          p2.cancel("Aborted.");
+          process.exit(0);
+        }
+        if (!bootstrapHere) {
+          p2.cancel(
+            "Aborted. Create a registry/ folder in that directory, or run skissue init and choose Bootstrap a minimal sample registry."
+          );
+          process.exit(0);
+        }
+        const outcome = await runLocalBootstrapFlow(cwd, resolvedExisting);
+        if (!outcome.ok) {
+          if (outcome.exitCode === 1) {
+            process.exitCode = 1;
+          } else {
+            process.exit(0);
+          }
+          return;
+        }
+        cfg = outcome.cfg;
+        bootstrappedSkillId = outcome.bootstrappedSkillId;
+      } else {
+        const branchDefault = await gitBranchShowCurrent(resolvedExisting) ?? "main";
+        const branch = await p2.text({
+          message: "Branch label (stored in config; installs use git HEAD from that directory)",
+          initialValue: branchDefault,
+          validate: requiredTrimmed
+        });
+        if (p2.isCancel(branch)) {
+          p2.cancel("Aborted.");
+          process.exit(0);
+        }
+        cfg = ConfigSchema.parse({
+          registry: {
+            path: String(regPath).trim(),
+            branch: String(branch).trim()
+          },
+          skillsRoot: ".agents/skills"
+        });
       }
-      cfg = ConfigSchema.parse({
-        registry: {
-          path: String(regPath).trim(),
-          branch: String(branch).trim()
-        },
-        skillsRoot: ".agents/skills"
-      });
     } else {
       const pathRaw = await p2.text({
         message: "Path for the new registry root (relative to this project or absolute)",
@@ -675,58 +785,17 @@ async function runInit(cwd) {
         process.exit(0);
       }
       const resolvedRoot = resolve3(cwd, String(pathRaw).trim());
-      const atConsumerRoot = resolvedRoot === resolve3(cwd);
-      if (atConsumerRoot && !registryLayoutExists(resolvedRoot)) {
-        const okRoot = await p2.confirm({
-          message: "This adds registry.json and registry/ at your project root. Continue?",
-          initialValue: false
-        });
-        if (p2.isCancel(okRoot) || !okRoot) {
-          p2.cancel("Aborted.");
+      const outcome = await runLocalBootstrapFlow(cwd, resolvedRoot);
+      if (!outcome.ok) {
+        if (outcome.exitCode === 1) {
+          process.exitCode = 1;
+        } else {
           process.exit(0);
         }
-      }
-      const prompted = await promptMinimalRegistryScaffold(resolvedRoot);
-      if (!prompted) {
-        p2.cancel("Aborted. No files were changed.");
-        process.exit(0);
-      }
-      let result;
-      try {
-        result = await scaffoldMinimalRegistry({
-          root: resolvedRoot,
-          skillId: prompted.skillId,
-          runGitInit: prompted.runGitInit
-        });
-      } catch (e) {
-        p2.cancel(e instanceof Error ? e.message : String(e));
-        process.exitCode = 1;
         return;
       }
-      bootstrappedSkillId = result.skillId;
-      if (!prompted.hadGit && !result.gitInitRan) {
-        p2.note(
-          "This folder is not a git repository. Run `git init` before using it as a local skissue registry.",
-          chalk2.yellow("Heads up")
-        );
-      }
-      const branchDefault = await gitBranchShowCurrent(resolvedRoot) ?? "main";
-      const branch = await p2.text({
-        message: "Branch label (stored in config; installs use git HEAD from that directory)",
-        initialValue: branchDefault,
-        validate: requiredTrimmed
-      });
-      if (p2.isCancel(branch)) {
-        p2.cancel("Aborted.");
-        process.exit(0);
-      }
-      cfg = ConfigSchema.parse({
-        registry: {
-          path: localRegistryPathForConfig(cwd, resolvedRoot),
-          branch: String(branch).trim()
-        },
-        skillsRoot: ".agents/skills"
-      });
+      cfg = outcome.cfg;
+      bootstrappedSkillId = outcome.bootstrappedSkillId;
     }
   } else {
     const owner = await p2.text({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skissue",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "license": "MIT",
   "repository": {
     "type": "git",