@cremini/skillpack 1.0.4 → 1.0.5

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Finpeak Inc
+Copyright (c) 2026 CreminiAI
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -31,17 +31,17 @@ Step-by-Step
 
 ```bash
 npx @cremini/skillpack init --config ./skillpack.json
-npx @cremini/skillpack init output --config https://example.com/skillpack.json
+npx @cremini/skillpack init commic_explainer --config https://raw.githubusercontent.com/CreminiAI/skillpack/refs/heads/main/examples/commic_explainer.json
 ```
 
-This loads a local or remote config, writes `skillpack.json` into the target directory, installs any pending skills, and skips zip packaging unless you pass `--bundle`.
+This loads a local or remote config, writes `skillpack.json` into the target directory, installs the configured skills, and skips zip packaging unless you pass `--bundle`.
 
 ### Step-by-Step Commands
 
 ```bash
 # Add skills
 npx @cremini/skillpack skills add vercel-labs/agent-skills --skill frontend-design
-npx @cremini/skillpack skills add ./my-local-skills
+npx @cremini/skillpack skills add ./my-local-skills --skill local-helper
 
 # Manage prompts
 npx @cremini/skillpack prompts add "Collect company data using Skill A, create charts from the data using Skill B, and compile the results into a PowerPoint using Skill C"
@@ -57,7 +57,7 @@ npx @cremini/skillpack build
 | ------------------------ | ------------------------------------- |
 | `create`                 | Create a skill pack interactively     |
 | `init`                   | Initialize from a config path or URL  |
-| `skills add <source>`    | Add a skill                           |
+| `skills add <source>`    | Add one or more skills with `--skill` |
 | `skills remove <name>`   | Remove a skill                        |
 | `skills list`            | List installed skills                 |
 | `prompts add <text>`     | Add a prompt                          |

package/dist/cli.js

@@ -5,6 +5,8 @@ import { Command } from "commander";
 import chalk8 from "chalk";
 
 // src/commands/create.ts
+import fs4 from "fs";
+import path4 from "path";
 import inquirer from "inquirer";
 import chalk3 from "chalk";
 
@@ -24,6 +26,72 @@ function createDefaultConfig(name, description) {
     skills: []
   };
 }
+function validateSkillEntry(value, sourceLabel, index) {
+  if (!value || typeof value !== "object") {
+    throw new Error(
+      `Invalid config from ${sourceLabel}: "skills[${index}]" must be an object`
+    );
+  }
+  const skill = value;
+  if ("installSource" in skill || "specificSkills" in skill) {
+    throw new Error(
+      `Invalid config from ${sourceLabel}: legacy skill fields are no longer supported; keep only "source", "name", and "description"`
+    );
+  }
+  if (typeof skill.source !== "string" || !skill.source.trim()) {
+    throw new Error(
+      `Invalid config from ${sourceLabel}: "skills[${index}].source" is required`
+    );
+  }
+  if (typeof skill.name !== "string" || !skill.name.trim()) {
+    throw new Error(
+      `Invalid config from ${sourceLabel}: "skills[${index}].name" is required`
+    );
+  }
+  if (typeof skill.description !== "string") {
+    throw new Error(
+      `Invalid config from ${sourceLabel}: "skills[${index}].description" must be a string`
+    );
+  }
+}
+function validateConfigShape(value, sourceLabel) {
+  if (!value || typeof value !== "object") {
+    throw new Error(`Invalid config from ${sourceLabel}: expected a JSON object`);
+  }
+  const config = value;
+  if (typeof config.name !== "string" || !config.name.trim()) {
+    throw new Error(`Invalid config from ${sourceLabel}: "name" is required`);
+  }
+  if (typeof config.description !== "string") {
+    throw new Error(
+      `Invalid config from ${sourceLabel}: "description" must be a string`
+    );
+  }
+  if (typeof config.version !== "string") {
+    throw new Error(
+      `Invalid config from ${sourceLabel}: "version" must be a string`
+    );
+  }
+  if (!Array.isArray(config.prompts) || !config.prompts.every((prompt) => typeof prompt === "string")) {
+    throw new Error(
+      `Invalid config from ${sourceLabel}: "prompts" must be a string array`
+    );
+  }
+  if (!Array.isArray(config.skills)) {
+    throw new Error(`Invalid config from ${sourceLabel}: "skills" must be an array`);
+  }
+  const names = /* @__PURE__ */ new Set();
+  config.skills.forEach((skill, index) => {
+    validateSkillEntry(skill, sourceLabel, index);
+    const normalizedName = skill.name.trim().toLowerCase();
+    if (names.has(normalizedName)) {
+      throw new Error(
+        `Invalid config from ${sourceLabel}: duplicate skill name "${skill.name}" is not allowed`
+      );
+    }
+    names.add(normalizedName);
+  });
+}
 function loadConfig(workDir) {
   const filePath = getPackPath(workDir);
   if (!fs.existsSync(filePath)) {
@@ -32,10 +100,13 @@ function loadConfig(workDir) {
     );
   }
   const raw = fs.readFileSync(filePath, "utf-8");
-  return JSON.parse(raw);
+  const parsed = JSON.parse(raw);
+  validateConfigShape(parsed, filePath);
+  return parsed;
 }
 function saveConfig(workDir, config) {
   const filePath = getPackPath(workDir);
+  validateConfigShape(config, filePath);
   fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8");
 }
 function configExists(workDir) {
@@ -50,98 +121,194 @@ import chalk2 from "chalk";
 import { fileURLToPath } from "url";
 
 // src/core/skill-manager.ts
-import { execSync } from "child_process";
+import { spawnSync } from "child_process";
 import fs2 from "fs";
 import path2 from "path";
 import chalk from "chalk";
 var SKILLS_DIR = "skills";
+function normalizeName(value) {
+  return value.trim().toLowerCase();
+}
 function getSkillsDir(workDir) {
   return path2.join(workDir, SKILLS_DIR);
 }
-async function installPendingSkills(workDir, config) {
-  const pendingSkills = config.skills.filter((s) => s.installSource);
-  if (pendingSkills.length === 0) {
+function groupSkillsBySource(skills) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const skill of skills) {
+    const source = skill.source.trim();
+    const name = skill.name.trim();
+    const names = groups.get(source) ?? [];
+    if (!names.some((entry) => normalizeName(entry) === normalizeName(name))) {
+      names.push(name);
+    }
+    groups.set(source, names);
+  }
+  return Array.from(groups, ([source, names]) => ({ source, names }));
+}
+function buildInstallArgs(group) {
+  const args = [
+    "-y",
+    "skills",
+    "add",
+    group.source,
+    "--agent",
+    "openclaw",
+    "--copy",
+    "-y"
+  ];
+  for (const name of group.names) {
+    args.push("--skill", name);
+  }
+  return args;
+}
+function installSkills(workDir, skills) {
+  if (skills.length === 0) {
     return;
   }
-  console.log(chalk.blue(`
-  Installing pending skills...`));
-  const skillsDir = getSkillsDir(workDir);
-  fs2.mkdirSync(skillsDir, { recursive: true });
-  for (const skill of pendingSkills) {
-    let addCmd = `npx -y skills add ${skill.installSource} --agent openclaw --copy -y`;
-    if (skill.specificSkills && skill.specificSkills.length > 0) {
-      for (const name of skill.specificSkills) {
-        addCmd += ` --skill "${name}"`;
-      }
+  for (const group of groupSkillsBySource(skills)) {
+    const args = buildInstallArgs(group);
+    const displayArgs = args.map((arg) => /\s/.test(arg) ? JSON.stringify(arg) : arg).join(" ");
+    console.log(chalk.dim(`> npx ${displayArgs}`));
+    const result = spawnSync("npx", args, {
+      cwd: workDir,
+      stdio: "inherit",
+      encoding: "utf-8"
+    });
+    if (result.error) {
+      throw result.error;
     }
-    console.log(chalk.dim(`> ${addCmd}`));
-    try {
-      execSync(addCmd, { encoding: "utf-8", cwd: workDir, stdio: "inherit" });
-    } catch (err) {
-      console.error(chalk.red(`Failed to install skill: ${err}`));
+    if (result.status !== 0) {
+      throw new Error(
+        `Failed to install skills from ${group.source} (exit code ${result.status ?? "unknown"})`
+      );
     }
   }
-  config.skills = scanInstalledSkills(workDir);
-  saveConfig(workDir, config);
-  console.log(chalk.green(`  Skill installation complete.
-`));
 }
 function scanInstalledSkills(workDir) {
-  const results = [];
+  const installed = [];
   const skillsDir = getSkillsDir(workDir);
   if (!fs2.existsSync(skillsDir)) {
-    return results;
+    return installed;
   }
-  function findSkillFiles(dir) {
+  function visit(dir) {
     const entries = fs2.readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
       const fullPath = path2.join(dir, entry.name);
       if (entry.isDirectory()) {
-        findSkillFiles(fullPath);
-      } else if (entry.name === "SKILL.md") {
-        const skill = parseSkillMd(fullPath, workDir);
-        if (skill) {
-          results.push(skill);
-        }
+        visit(fullPath);
+        continue;
+      }
+      if (entry.name !== "SKILL.md") {
+        continue;
+      }
+      const skill = parseSkillMd(fullPath);
+      if (skill) {
+        installed.push(skill);
       }
     }
   }
-  findSkillFiles(skillsDir);
-  return results;
+  visit(skillsDir);
+  return installed;
 }
-function parseSkillMd(filePath, workDir) {
+function parseSkillMd(filePath) {
   try {
     const content = fs2.readFileSync(filePath, "utf-8");
     const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
-    if (!frontmatterMatch) return null;
+    if (!frontmatterMatch) {
+      return null;
+    }
     const frontmatter = frontmatterMatch[1];
     const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
     const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
-    if (!nameMatch) return null;
+    if (!nameMatch) {
+      return null;
+    }
     return {
       name: nameMatch[1].trim(),
-      source: path2.relative(workDir, path2.dirname(filePath)),
-      description: descMatch ? descMatch[1].trim() : ""
+      description: descMatch ? descMatch[1].trim() : "",
+      dir: path2.dirname(filePath)
     };
   } catch {
     return null;
   }
 }
+function syncSkillDescriptions(workDir, config) {
+  const descriptionByName = /* @__PURE__ */ new Map();
+  for (const skill of scanInstalledSkills(workDir)) {
+    descriptionByName.set(normalizeName(skill.name), skill.description);
+  }
+  config.skills = config.skills.map((skill) => {
+    const description = descriptionByName.get(normalizeName(skill.name));
+    return description === void 0 ? skill : { ...skill, description };
+  });
+  return config;
+}
+function upsertSkills(config, skills) {
+  for (const skill of skills) {
+    const normalizedName = normalizeName(skill.name);
+    const normalizedSource = skill.source.trim();
+    const existing = config.skills.find(
+      (entry) => normalizeName(entry.name) === normalizedName
+    );
+    if (existing && existing.source.trim() !== normalizedSource) {
+      throw new Error(
+        `Skill "${skill.name}" is already declared from source "${existing.source}"`
+      );
+    }
+    const sameEntry = config.skills.findIndex(
+      (entry) => normalizeName(entry.name) === normalizedName && entry.source.trim() === normalizedSource
+    );
+    if (sameEntry >= 0) {
+      config.skills[sameEntry] = {
+        ...config.skills[sameEntry],
+        name: skill.name.trim(),
+        source: normalizedSource,
+        description: skill.description
+      };
+      continue;
+    }
+    config.skills.push({
+      name: skill.name.trim(),
+      source: normalizedSource,
+      description: skill.description
+    });
+  }
+  return config;
+}
+function installConfiguredSkills(workDir, config) {
+  installSkills(workDir, config.skills);
+}
+function refreshDescriptionsAndSave(workDir, config) {
+  syncSkillDescriptions(workDir, config);
+  saveConfig(workDir, config);
+  return config;
+}
 function removeSkill(workDir, skillName) {
   const config = loadConfig(workDir);
-  const idx = config.skills.findIndex(
-    (s) => s.name.toLowerCase() === skillName.toLowerCase()
+  const normalizedName = normalizeName(skillName);
+  const nextSkills = config.skills.filter(
+    (skill) => normalizeName(skill.name) !== normalizedName
   );
-  if (idx === -1) {
+  if (nextSkills.length === config.skills.length) {
     console.log(chalk.yellow(`Skill not found: ${skillName}`));
     return false;
   }
-  const skillDir = path2.join(workDir, config.skills[idx].source);
-  if (fs2.existsSync(skillDir)) {
-    fs2.rmSync(skillDir, { recursive: true });
-  }
-  config.skills.splice(idx, 1);
+  config.skills = nextSkills;
   saveConfig(workDir, config);
+  const installedMatches = scanInstalledSkills(workDir).filter(
+    (skill) => normalizeName(skill.name) === normalizedName
+  );
+  if (installedMatches.length === 0) {
+    console.log(
+      chalk.yellow(`Removed config for ${skillName}, but no installed files were found`)
+    );
+    return true;
+  }
+  for (const skill of installedMatches) {
+    if (fs2.existsSync(skill.dir)) {
+      fs2.rmSync(skill.dir, { recursive: true, force: true });
+    }
+  }
   console.log(chalk.green(`Removed skill: ${skillName}`));
   return true;
 }
@@ -154,14 +321,15 @@ function getRuntimeDir() {
 }
 async function bundle(workDir) {
   const config = loadConfig(workDir);
-  saveConfig(workDir, config);
   const zipName = `${config.name}.zip`;
   const zipPath = path3.join(workDir, zipName);
   const runtimeDir = getRuntimeDir();
   if (!fs3.existsSync(runtimeDir)) {
     throw new Error(`Runtime directory not found: ${runtimeDir}`);
   }
-  await installPendingSkills(workDir, config);
+  installConfiguredSkills(workDir, config);
+  syncSkillDescriptions(workDir, config);
+  saveConfig(workDir, config);
   console.log(chalk2.blue(`Packaging ${config.name}...`));
   const output = fs3.createWriteStream(zipPath);
   const archive = archiver("zip", { zlib: { level: 9 } });
@@ -222,8 +390,9 @@ function addRuntimeFiles(archive, runtimeDir, prefix) {
 }
 
 // src/commands/create.ts
-import fs4 from "fs";
-import path4 from "path";
+function parseSkillNames(value) {
+  return value.split(",").map((name) => name.trim()).filter(Boolean);
+}
 async function createCommand(directory) {
   const workDir = directory ? path4.resolve(directory) : process.cwd();
   if (directory) {
@@ -249,7 +418,7 @@ async function createCommand(directory) {
       type: "input",
       name: "name",
       message: "App name:",
-      validate: (v) => v.trim() ? true : "Name is required"
+      validate: (value) => value.trim() ? true : "Name is required"
     },
     {
       type: "input",
@@ -259,20 +428,15 @@ async function createCommand(directory) {
     }
   ]);
   const config = createDefaultConfig(name.trim(), description.trim());
+  const requestedSkills = [];
   console.log(
     chalk3.blue("\n  Add Skills (enter a skill source, leave blank to skip)\n")
   );
   console.log(
-    chalk3.dim(
-      "  Supported formats: owner/repo, GitHub URL, local path, or a full npx skills add command"
-    )
-  );
-  console.log(chalk3.dim("  Example: vercel-labs/agent-skills"));
-  console.log(
-    chalk3.dim(
-      "  Example: npx skills add https://github.com/vercel-labs/skills --skill find-skillsclear\n"
-    )
+    chalk3.dim("  Supported formats: owner/repo, GitHub URL, or local path")
   );
+  console.log(chalk3.dim("  Example source: vercel-labs/agent-skills"));
+  console.log(chalk3.dim("  Example skill names: frontend-design, skill-creator\n"));
   while (true) {
     const { source } = await inquirer.prompt([
       {
@@ -281,51 +445,29 @@ async function createCommand(directory) {
         message: "Skill source (leave blank to skip):"
       }
     ]);
-    if (!source.trim()) break;
-    let parsedSource = source.trim();
-    let parsedSpecificSkill;
-    const skillMatch = parsedSource.match(/(.*?)\s+--skill\s+([^\s]+)(.*)/);
-    if (skillMatch) {
-      parsedSpecificSkill = skillMatch[2];
-      parsedSource = `${skillMatch[1]} ${skillMatch[3]}`.trim();
+    if (!source.trim()) {
+      break;
     }
-    const npxMatch = parsedSource.match(/^npx\s+[^\s]+\s+add\s+(.+)$/);
-    if (npxMatch) {
-      parsedSource = npxMatch[1].trim();
-    }
-    if (!parsedSource) continue;
-    let specificSkill = parsedSpecificSkill;
-    if (specificSkill !== void 0) {
-      console.log(chalk3.dim(`  Auto-detected skill source: ${parsedSource}`));
-      console.log(
-        chalk3.dim(`  Auto-detected specific skill: ${specificSkill}`)
-      );
-    } else {
-      if (parsedSource !== source.trim()) {
-        console.log(chalk3.dim(`  Auto-detected skill source: ${parsedSource}`));
+    const { skillNames } = await inquirer.prompt([
+      {
+        type: "input",
+        name: "skillNames",
+        message: "Skill names (comma-separated):",
+        validate: (value) => parseSkillNames(value).length > 0 ? true : "Enter at least one skill name"
       }
-      const answer = await inquirer.prompt([
-        {
-          type: "input",
-          name: "specificSkill",
-          message: "Specific skill name (leave blank to install all):"
-        }
-      ]);
-      specificSkill = answer.specificSkill;
-    }
-    const skillNames = specificSkill && specificSkill.trim() ? [specificSkill.trim()] : void 0;
-    config.skills.push({
-      name: skillNames ? skillNames.join(", ") : parsedSource,
-      source: parsedSource,
-      description: "Pending installation",
-      installSource: parsedSource,
-      specificSkills: skillNames
-    });
+    ]);
+    const nextSkills = parseSkillNames(skillNames).map((skillName) => ({
+      source: source.trim(),
+      name: skillName,
+      description: ""
+    }));
+    upsertSkills(config, nextSkills);
+    requestedSkills.push(...nextSkills);
   }
   console.log(chalk3.blue("\n  Add Prompts\n"));
   console.log(
     chalk3.blue(
-      "Use a prompt to explain how you will organize the skills you added to complete the task\n"
+      "Use prompts to explain how the pack should orchestrate the selected skills\n"
     )
   );
   let promptIndex = 1;
@@ -336,17 +478,15 @@ async function createCommand(directory) {
         type: "input",
         name: "prompt",
         message: isFirst ? `Prompt #${promptIndex} (required):` : `Prompt #${promptIndex} (leave blank to finish):`,
-        validate: isFirst ? (v) => v.trim() ? true : "The first Prompt cannot be empty" : void 0
+        validate: isFirst ? (value) => value.trim() ? true : "The first Prompt cannot be empty" : void 0
       }
     ]);
-    if (!isFirst && !prompt.trim()) break;
+    if (!isFirst && !prompt.trim()) {
+      break;
+    }
     config.prompts.push(prompt.trim());
     promptIndex++;
   }
-  saveConfig(workDir, config);
-  console.log(chalk3.green(`
-  ${PACK_FILE} saved
-`));
   const { shouldBundle } = await inquirer.prompt([
     {
       type: "confirm",
@@ -355,6 +495,14 @@ async function createCommand(directory) {
       default: true
     }
   ]);
+  saveConfig(workDir, config);
+  console.log(chalk3.green(`
+  ${PACK_FILE} saved
+`));
+  if (requestedSkills.length > 0) {
+    installConfiguredSkills(workDir, config);
+    refreshDescriptionsAndSave(workDir, config);
+  }
   if (shouldBundle) {
     await bundle(workDir);
   }
@@ -379,27 +527,6 @@ function isHttpUrl(value) {
     return false;
   }
 }
-function validateConfigShape(value, source) {
-  if (!value || typeof value !== "object") {
-    throw new Error(`Invalid config from ${source}: expected a JSON object`);
-  }
-  const config = value;
-  if (typeof config.name !== "string" || !config.name.trim()) {
-    throw new Error(`Invalid config from ${source}: "name" is required`);
-  }
-  if (typeof config.description !== "string") {
-    throw new Error(`Invalid config from ${source}: "description" must be a string`);
-  }
-  if (typeof config.version !== "string") {
-    throw new Error(`Invalid config from ${source}: "version" must be a string`);
-  }
-  if (!Array.isArray(config.prompts) || !config.prompts.every((p) => typeof p === "string")) {
-    throw new Error(`Invalid config from ${source}: "prompts" must be a string array`);
-  }
-  if (!Array.isArray(config.skills)) {
-    throw new Error(`Invalid config from ${source}: "skills" must be an array`);
-  }
-}
 async function readConfigSource(source) {
   let raw = "";
   if (isHttpUrl(source)) {
@@ -440,7 +567,8 @@ async function initCommand(directory, options) {
   console.log(chalk4.blue(`
   Initialize ${config.name} from ${options.config}
 `));
-  await installPendingSkills(workDir, config);
+  installConfiguredSkills(workDir, config);
+  refreshDescriptionsAndSave(workDir, config);
   if (options.bundle) {
     await bundle(workDir);
   }
@@ -460,21 +588,37 @@ import chalk5 from "chalk";
 function registerSkillsCommand(program2) {
   const skills = program2.command("skills").description("Manage skills in the app");
   skills.command("add <source>").description("Add a skill from a git repo, URL, or local path").option("-s, --skill <names...>", "Specify skill name(s)").action(async (source, opts) => {
+    if (!opts.skill || opts.skill.length === 0) {
+      console.log(
+        chalk5.red(
+          "Specify at least one skill name with --skill when adding a source"
+        )
+      );
+      process.exitCode = 1;
+      return;
+    }
     const workDir = process.cwd();
     const config = loadConfig(workDir);
-    config.skills.push({
-      name: opts.skill ? opts.skill.join(", ") : source,
+    const requestedSkills = opts.skill.map((name) => ({
+      name: name.trim(),
       source,
-      description: "Pending installation",
-      installSource: source,
-      specificSkills: opts.skill && opts.skill.length > 0 ? opts.skill : void 0
-    });
+      description: ""
+    }));
+    upsertSkills(config, requestedSkills);
     saveConfig(workDir, config);
-    console.log(
-      chalk5.green(
-        `Skill list updated (${config.skills.length} total). Skills will be installed during build.`
-      )
-    );
+    try {
+      installSkills(workDir, requestedSkills);
+      refreshDescriptionsAndSave(workDir, config);
+    } catch (error) {
+      console.log(
+        chalk5.red(
+          `Skill installation failed: ${error instanceof Error ? error.message : String(error)}`
+        )
+      );
+      process.exitCode = 1;
+      return;
+    }
+    console.log(chalk5.green(`Installed ${requestedSkills.length} skill(s).`));
   });
   skills.command("remove <name>").description("Remove a skill").action((name) => {
     removeSkill(process.cwd(), name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cremini/skillpack",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Turn Skills into a Standalone App with UI",
   "type": "module",
   "repository": {

package/runtime/server/skills-loader.js

@@ -1,31 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-/**
- * Recursively load the contents of all SKILL.md files under skills/.
- * @param {string} rootDir - Root directory containing skills/
- * @returns {string[]} Array of SKILL.md file contents
- */
-export function loadSkillContents(rootDir) {
-  const skillsDir = path.join(rootDir, "skills");
-  const contents = [];
-
-  if (!fs.existsSync(skillsDir)) {
-    return contents;
-  }
-
-  function walk(dir) {
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        walk(full);
-      } else if (entry.name === "SKILL.md") {
-        contents.push(fs.readFileSync(full, "utf-8"));
-      }
-    }
-  }
-
-  walk(skillsDir);
-  return contents;
-}