@supa-magic/spm 0.2.6 → 0.3.1

package/dist/bin/spm.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, readdirSync, statSync } from "node:fs";
-import { join, dirname, relative, resolve, normalize } from "node:path";
+import { join, dirname, relative, posix, resolve, normalize } from "node:path";
 import { parse, stringify } from "yaml";
 import { execFileSync, execSync, spawn } from "node:child_process";
 import { readFile, mkdir, writeFile, rm, readdir } from "node:fs/promises";
@@ -50,7 +50,9 @@ const detectProviders = (root) => Object.entries(knownProviders).reduce(
 );
 const getGitRoot = () => {
   try {
-    return execSync("git rev-parse --show-toplevel", { encoding: "utf-8" }).trim();
+    return execSync("git rev-parse --show-toplevel", {
+      encoding: "utf-8"
+    }).trim();
   } catch {
     return void 0;
   }
@@ -77,6 +79,25 @@ const writeConfig = (config, root) => {
   const configPath = getConfigPath(root);
   writeFileSync(configPath, stringify(config), "utf-8");
 };
+const addConfigEntry = ({
+  providerPath,
+  kind,
+  name,
+  source
+}) => {
+  const { config } = readConfig();
+  const provider = Object.values(config.providers).find(
+    (p) => p.path === providerPath
+  );
+  if (!provider) {
+    throw new Error(`Provider with path "${providerPath}" not found in config`);
+  }
+  if (!provider[kind]) {
+    provider[kind] = {};
+  }
+  provider[kind][name] = source;
+  writeConfig(config);
+};
 const green = "\x1B[32m";
 const red = "\x1B[31m";
 const cyan = "\x1B[36m";
@@ -368,7 +389,8 @@ const downloadFile = async (source) => {
   const content = await getContent(source);
   return { content, source };
 };
-const template = '# Skillset Integration\n\nYou are integrating a new skillset into the project. Analyze the existing project setup and intelligently integrate the new files.\n\n## Context\n\n- **Downloaded files**: `{{downloadDir}}`\n- **Provider directory**: `{{providerDir}}`\n- **Skillset**: `{{skillsetName}}` v`{{skillsetVersion}}`\n- **Source**: `{{source}}`\n- **Config file**: `{{configPath}}`\n\nIdentical files have already been removed from the download folder. Only files that need action remain. If the download folder is empty, skip to the config update step.\n\n## Output Format\n\nCRITICAL — follow exactly:\n- NEVER wrap output in code blocks or backticks\n- NEVER write conversational text ("Now let me...", "Let me check...", "The files are...")\n- NEVER use emojis\n- Output ONLY structured log lines\n- Step headers are plain text ending with `...` — these are parsed by the CLI to drive spinner states\n- Items below headers are indented with 2 spaces and use `• ` prefix\n- File lists use ASCII tree: `├─`, `└─`, `│`\n- End with `Done` on its own line\n\nStep headers (use these exactly):\n\n1. `Analyzing existing setup...`\n2. `Analyzing downloaded files...`\n3. `Detecting conflicts...`\n4. `Integrating...`\n5. `Updating config...`\n6. `Running setup...` (only if a setup file exists)\n7. `Done`\n\nExample output:\n\nAnalyzing existing setup...\n  • 4 skills, 2 rules, 1 hook\n\nAnalyzing downloaded files...\n  • skills: git, github, implement\n  • rules: coding\n  • hook: biome-format\n\nDetecting conflicts...\n  • No conflicts\n\nIntegrating...\n  • skills/git/SKILL.md\n  • skills/git/branch.md\n  • skills/github/SKILL.md\n\nUpdating config...\n  • skillset: skill-creator@1.0.0\n\nRunning setup...\n  • Configured MCP server: biome\n\nDone\n\n## Step 1: Analyzing existing setup\n\nRead the provider directory (`{{providerDir}}`) and catalog what is already in place: skills, rules, agents, hooks, mcp servers files.\n\n## Step 2: Analyzing downloaded files\n\nRead all files in `{{downloadDir}}`. Only files present in this folder need to be installed.\n\n## Step 3: Detecting conflicts\n\nFor each downloaded file, check if a file with the same name exists in the provider directory.\n\n- **No existing file** → install as new\n- **Different skillset version** → replace silently (new version supersedes)\n- **Same version or no version info** → conflict — ask the user:\n\nDetecting conflicts...\n  • rules/coding.md — local has custom rules\n  • Choose: (r)eplace / (s)kip / (m)erge\n\nWait for response before proceeding.\n\n## Step 4: Integrating\n\nInstall files into `{{providerDir}}`, following the directory structure from the download folder.\n\n**Integrate, don\'t copy.** When a new skill can leverage existing project conventions, adapt it:\n\n- If the project has `rules/coding.md` with specific conventions → make new skills follow those rules instead of their own defaults\n- If existing skills handle branching or committing → reference them instead of duplicating instructions\n- If the project has naming conventions, testing patterns, or architectural rules → align new skills with them\n\n## Step 5: Updating config\n\nUpdate `{{configPath}}`:\n\n- Under the provider with path `{{providerDir}}`, add the skillset entry under `skillsets`:\n  `{{skillsetName}}: "{{source}}@{{skillsetVersion}}"`\n- Do NOT add individual skill, agent, or file names to the config\n- The `skills` map is reserved for standalone skill installations\n\n{{setupSection}}\n\n## Rules\n\n- Setup files are NOT installed — they contain instructions to configure the project\n- Do not delete or modify existing files in the provider directory unless resolving a conflict\n- Do NOT delete the download folder — cleanup is handled externally\n';
+const template = '# Skillset Integration\n\nYou are integrating a new skillset into the project. Analyze the existing project setup and intelligently integrate the new files.\n\n## Context\n\n- **Downloaded files**: `{{downloadDir}}`\n- **Provider directory**: `{{providerDir}}`\n- **Skillset**: `{{skillsetName}}` v`{{skillsetVersion}}`\n\nIdentical files have already been removed from the download folder. Only files that need action remain. If the download folder is empty, output `Done` immediately.\n\n## Output Format\n\nCRITICAL — follow exactly:\n- NEVER wrap output in code blocks or backticks\n- NEVER write conversational text ("Now let me...", "Let me check...", "The files are...")\n- NEVER use emojis\n- Output ONLY structured log lines\n- Step headers are plain text ending with `...` — these are parsed by the CLI to drive spinner states\n- Items below headers are indented with 2 spaces and use `• ` prefix\n- File lists use ASCII tree: `├─`, `└─`, `│`\n- End with `Done` on its own line\n\nStep headers (use these exactly):\n\n1. `Analyzing existing setup...`\n2. `Analyzing downloaded files...`\n3. `Detecting conflicts...`\n4. `Integrating...`\n5. `Running setup...` (only if a setup file exists)\n6. `Done`\n\nExample output:\n\nAnalyzing existing setup...\n  • 4 skills, 2 rules, 1 hook\n\nAnalyzing downloaded files...\n  • skills: git, github, implement\n  • rules: coding\n  • hook: biome-format\n\nDetecting conflicts...\n  • No conflicts\n\nIntegrating...\n  • skills/git/SKILL.md\n  • skills/git/branch.md\n  • skills/github/SKILL.md\n\nRunning setup...\n  • Configured MCP server: biome\n\nDone\n\n## Step 1: Analyzing existing setup\n\nRead the provider directory (`{{providerDir}}`) and catalog what is already in place: skills, rules, agents, hooks, mcp servers files.\n\n## Step 2: Analyzing downloaded files\n\nRead all files in `{{downloadDir}}`. Only files present in this folder need to be installed.\n\n## Step 3: Detecting conflicts\n\nFor each downloaded file, check if a file with the same name exists in the provider directory.\n\n- **No existing file** → install as new\n- **Different skillset version** → replace silently (new version supersedes)\n- **Same version or no version info** → conflict — ask the user:\n\nDetecting conflicts...\n  • rules/coding.md — local has custom rules\n  • Choose: (r)eplace / (s)kip / (m)erge\n\nWait for response before proceeding.\n\n## Step 4: Integrating\n\nInstall files into `{{providerDir}}`, following the directory structure from the download folder.\n\n**Integrate, don\'t copy.** When a new skill can leverage existing project conventions, adapt it:\n\n- If the project has `rules/coding.md` with specific conventions → make new skills follow those rules instead of their own defaults\n- If existing skills handle branching or committing → reference them instead of duplicating instructions\n- If the project has naming conventions, testing patterns, or architectural rules → align new skills with them\n\n{{setupSection}}\n\n## Rules\n\n- Setup files are NOT installed — they contain instructions to configure the project\n- Do not delete or modify existing files in the provider directory unless resolving a conflict\n- Do NOT delete the download folder — cleanup is handled externally\n';
+const skillTemplate = '# Skill Integration\n\nYou are integrating a single skill into the project. Analyze the existing project setup and intelligently integrate the new files.\n\n## Context\n\n- **Downloaded files**: `{{downloadDir}}`\n- **Provider directory**: `{{providerDir}}`\n- **Skill**: `{{skillName}}`\n\nIdentical files have already been removed from the download folder. Only files that need action remain. If the download folder is empty, output `Done` immediately.\n\n## Output Format\n\nCRITICAL — follow exactly:\n- NEVER wrap output in code blocks or backticks\n- NEVER write conversational text ("Now let me...", "Let me check...", "The files are...")\n- NEVER use emojis\n- Output ONLY structured log lines\n- Step headers are plain text ending with `...` — these are parsed by the CLI to drive spinner states\n- Items below headers are indented with 2 spaces and use `• ` prefix\n- File lists use ASCII tree: `├─`, `└─`, `│`\n- End with `Done` on its own line\n\nStep headers (use these exactly):\n\n1. `Analyzing existing setup...`\n2. `Analyzing downloaded files...`\n3. `Detecting conflicts...`\n4. `Integrating...`\n5. `Done`\n\nExample output:\n\nAnalyzing existing setup...\n  • 4 skills, 2 rules, 1 hook\n\nAnalyzing downloaded files...\n  • skill: git (3 files)\n\nDetecting conflicts...\n  • No conflicts\n\nIntegrating...\n  • skills/git/SKILL.md\n  • skills/git/branch.md\n\nDone\n\n## Step 1: Analyzing existing setup\n\nRead the provider directory (`{{providerDir}}`) and catalog what is already in place: skills, rules, agents, hooks, mcp servers files.\n\n## Step 2: Analyzing downloaded files\n\nRead all files in `{{downloadDir}}`. Only files present in this folder need to be installed.\n\n## Step 3: Detecting conflicts\n\nFor each downloaded file, check if a file with the same name exists in the provider directory.\n\n- **No existing file** → install as new\n- **Different content** → replace silently\n- **Same content** → skip (should already be pruned)\n\nDetecting conflicts...\n  • rules/coding.md — local has custom rules\n  • Choose: (r)eplace / (s)kip / (m)erge\n\nWait for response before proceeding.\n\n## Step 4: Integrating\n\nInstall files into `{{providerDir}}/skills/{{skillName}}/`, following the directory structure from the download folder.\n\n**Integrate, don\'t copy.** When a new skill can leverage existing project conventions, adapt it:\n\n- If the project has `rules/coding.md` with specific conventions → make new skills follow those rules instead of their own defaults\n- If existing skills handle branching or committing → reference them instead of duplicating instructions\n- If the project has naming conventions, testing patterns, or architectural rules → align new skills with them\n\n## Rules\n\n- Do not delete or modify existing files in the provider directory unless resolving a conflict\n- Do NOT delete the download folder — cleanup is handled externally\n';
 const buildSetupSection = (setupFile) => setupFile ? [
   "## Step 6: Running setup",
   "",
@@ -376,13 +398,20 @@ const buildSetupSection = (setupFile) => setupFile ? [
   "Setup files configure the project environment (e.g. MCP servers, LSP, tooling).",
   "Do NOT copy the setup file into the provider directory — only execute its instructions."
 ].join("\n") : "";
-const buildInstructions = (input) => template.replace(/\{\{downloadDir\}\}/g, input.downloadDir).replace(/\{\{providerDir\}\}/g, input.providerDir).replace(/\{\{skillsetName\}\}/g, input.skillsetName).replace(/\{\{skillsetVersion\}\}/g, input.skillsetVersion).replace(/\{\{source\}\}/g, input.source).replace(/\{\{configPath\}\}/g, input.configPath).replace("{{setupSection}}", buildSetupSection(input.setupFile));
+const buildInstructions = (input) => template.replace(/\{\{downloadDir\}\}/g, input.downloadDir).replace(/\{\{providerDir\}\}/g, input.providerDir).replace(/\{\{skillsetName\}\}/g, input.skillsetName).replace(/\{\{skillsetVersion\}\}/g, input.skillsetVersion).replace("{{setupSection}}", buildSetupSection(input.setupFile));
 const writeInstructionsFile = (input) => {
   const filePath = join(tmpdir(), "spm", `install-${input.skillsetName}.md`);
   mkdirSync(dirname(filePath), { recursive: true });
   writeFileSync(filePath, buildInstructions(input), "utf-8");
   return filePath;
 };
+const buildSkillInstructions = (input) => skillTemplate.replace(/\{\{downloadDir\}\}/g, input.downloadDir).replace(/\{\{providerDir\}\}/g, input.providerDir).replace(/\{\{skillName\}\}/g, input.skillName);
+const writeSkillInstructionsFile = (input) => {
+  const filePath = join(tmpdir(), "spm", `install-skill-${input.skillName}.md`);
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, buildSkillInstructions(input), "utf-8");
+  return filePath;
+};
 const isNoise = (line) => line === "```" || line.startsWith("```") || /^(now |let me |the files? |i'll |i will |looking |checking )/i.test(line);
 const isStepHeader = (raw, trimmed) => !raw.startsWith(" ") && !raw.startsWith("	") && trimmed.endsWith("...");
 const stepCategory = (header) => {
@@ -409,7 +438,7 @@ const toRelativePath = (filePath, providerDir) => {
   if (idx !== -1) return normalized.slice(idx + marker.length);
   return normalized.split("/").pop() ?? normalized;
 };
-const spawnClaude = (instructionsFilePath, stepper, providerDir, model) => new Promise((resolve2, reject) => {
+const spawnClaude = (instructionsFilePath, stepper, providerDir, model, entityLabel = "Skillset") => new Promise((resolve2, reject) => {
   const args = [
     "-p",
     "Install the skill as instructed.",
@@ -444,12 +473,12 @@ const spawnClaude = (instructionsFilePath, stepper, providerDir, model) => new P
     }
     if (currentStepHeader.startsWith("Integrating")) {
       stepper.succeed(
-        stepFileCount > 0 ? `Skillset was integrated (${stepFileCount} file(s))` : "Skillset was integrated"
+        stepFileCount > 0 ? `${entityLabel} was integrated (${stepFileCount} file(s))` : `${entityLabel} was integrated`
       );
       return;
     }
     if (currentStepHeader.startsWith("Running setup")) {
-      stepper.succeed("Skillset setup completed");
+      stepper.succeed(`${entityLabel} setup completed`);
       currentStepHeader = "";
       return;
     }
@@ -564,6 +593,13 @@ ${stderr}` : "";
     });
   });
 });
+const installSingleSkill = (input, stepper) => spawnClaude(
+  writeSkillInstructionsFile(input),
+  stepper,
+  input.providerDir,
+  input.model,
+  "Skill"
+);
 const installSkillset = (input, stepper) => spawnClaude(
   writeInstructionsFile(input),
   stepper,
@@ -591,6 +627,27 @@ const pruneUnchanged = (downloadDir, providerDir) => {
   });
   return removed;
 };
+const frontmatterPattern = /^---\r?\n([\s\S]*?)\r?\n---/;
+const hasStringName = (value) => typeof value === "object" && value !== null && "name" in value && typeof value.name === "string";
+const deriveSkillName = (content, fileName) => {
+  const match = content.match(frontmatterPattern);
+  if (match) {
+    const frontmatter = parse(match[1]);
+    if (hasStringName(frontmatter)) return frontmatter.name;
+  }
+  return fileName.replace(/\.md$/i, "").toLowerCase();
+};
+const hasDefaultBranch = (value) => typeof value === "object" && value !== null && "default_branch" in value && typeof value.default_branch === "string";
+const fetchDefaultBranch = async (owner, repository) => {
+  const response = await fetch(
+    `https://api.github.com/repos/${owner}/${repository}`
+  );
+  if (!response.ok) {
+    return "main";
+  }
+  const data = await response.json();
+  return hasDefaultBranch(data) ? data.default_branch : "main";
+};
 const requiredFields = ["name", "version", "description", "provider"];
 const validateSkillset = (data) => {
   if (!data || typeof data !== "object") {
@@ -618,12 +675,33 @@ const fetchSkillset = async (location) => {
   const text = await response.text();
   return validateSkillset(parse(text));
 };
+const detectKind = (path) => /\.md$/i.test(path) ? "skill" : "skillset";
 const parseGitHubUrl = (url) => {
-  const match = url.match(
-    /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/tree\/[^/]+\/(.+)$/
+  const blobOrTree = url.match(
+    /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/(?:tree|blob)\/([^/]+)\/(.+)$/
+  );
+  if (blobOrTree) {
+    const identifier = {
+      owner: blobOrTree[1],
+      repository: blobOrTree[2],
+      path: blobOrTree[4],
+      ref: blobOrTree[3]
+    };
+    return { kind: detectKind(identifier.path), identifier };
+  }
+  const raw = url.match(
+    /^https?:\/\/raw\.githubusercontent\.com\/([^/]+)\/([^/]+)\/([^/]+)\/(.+)$/
   );
-  if (!match) return void 0;
-  return { owner: match[1], repository: match[2], path: match[3] };
+  if (raw) {
+    const identifier = {
+      owner: raw[1],
+      repository: raw[2],
+      path: raw[4],
+      ref: raw[3]
+    };
+    return { kind: detectKind(identifier.path), identifier };
+  }
+  return void 0;
 };
 const parseAtIdentifier = (input) => {
   const parts = input.slice(1).split("/").filter(Boolean);
@@ -632,11 +710,12 @@ const parseAtIdentifier = (input) => {
       `Invalid identifier "${input}". Expected format: @owner/repo/path (e.g., @supa-magic/skillbox/claude/fsd).`
     );
   }
-  return {
+  const identifier = {
     owner: parts[0],
     repository: parts[1],
     path: parts.slice(2).join("/")
   };
+  return { kind: detectKind(identifier.path), identifier };
 };
 const parseIdentifier = (input) => {
   const trimmed = input.trim();
@@ -644,7 +723,7 @@ const parseIdentifier = (input) => {
     const result = parseGitHubUrl(trimmed);
     if (!result) {
       throw new Error(
-        `Invalid GitHub URL "${trimmed}". Expected format: https://github.com/owner/repo/tree/branch/path.`
+        `Invalid GitHub URL "${trimmed}". Expected format: https://github.com/owner/repo/tree|blob/branch/path or https://raw.githubusercontent.com/owner/repo/ref/path.`
       );
     }
     return result;
@@ -656,19 +735,39 @@ const parseIdentifier = (input) => {
   }
   return parseAtIdentifier(trimmed);
 };
-const fetchDefaultBranch = async (owner, repository) => {
-  const response = await fetch(
-    `https://api.github.com/repos/${owner}/${repository}`
-  );
-  if (!response.ok) {
-    return "main";
-  }
-  const data = await response.json();
-  return data.default_branch ?? "main";
+const markdownLinkPattern = /\[[^\]]*\]\(([^)]+\.md)\)/g;
+const inlinePathPattern = /(?:`|(?:^|\s))(\.[^\s`]*\.md)/g;
+const providerPrefixes = [
+  ".claude/",
+  ".cursor/",
+  ".copilot/",
+  ".aider/",
+  ".codeium/",
+  ".cody/"
+];
+const isExcluded = (ref) => {
+  const normalized = ref.replace(/^\.\//, "");
+  return ref.startsWith("http://") || ref.startsWith("https://") || ref.startsWith("/") || ref.includes("..") || providerPrefixes.some((prefix) => normalized.startsWith(prefix));
+};
+const parseSkillRefs = (content, fileDir) => {
+  const refs = /* @__PURE__ */ new Set();
+  const collect = (pattern) => {
+    for (const match of content.matchAll(pattern)) {
+      const ref = match[1];
+      if (!isExcluded(ref)) {
+        const resolved = posix.normalize(posix.join(fileDir, ref));
+        refs.add(resolved);
+      }
+    }
+  };
+  collect(markdownLinkPattern);
+  collect(inlinePathPattern);
+  return [...refs];
 };
 const resolveIdentifier = async (input) => {
-  const identifier = parseIdentifier(input);
-  const ref = await fetchDefaultBranch(identifier.owner, identifier.repository);
+  const parsed = parseIdentifier(input);
+  const { identifier } = parsed;
+  const ref = identifier.ref ?? await fetchDefaultBranch(identifier.owner, identifier.repository);
   return {
     owner: identifier.owner,
     repository: identifier.repository,
@@ -676,6 +775,40 @@ const resolveIdentifier = async (input) => {
     ref
   };
 };
+const resolveSkill = async (identifier) => {
+  const ref = identifier.ref ?? await fetchDefaultBranch(identifier.owner, identifier.repository);
+  const visited = /* @__PURE__ */ new Set();
+  const files = [];
+  const fetchRecursive = async (repoPath) => {
+    const normalized = posix.normalize(repoPath);
+    if (visited.has(normalized)) return;
+    visited.add(normalized);
+    const content = await downloadFromGitHub({
+      owner: identifier.owner,
+      repository: identifier.repository,
+      path: normalized,
+      ref
+    });
+    files.push({ path: normalized, content });
+    const fileDir = posix.dirname(normalized);
+    const refs = parseSkillRefs(content, fileDir);
+    await Promise.all(refs.map((refPath) => fetchRecursive(refPath)));
+  };
+  await fetchRecursive(identifier.path);
+  const mainFile = files[0];
+  const fileName = posix.basename(identifier.path);
+  const name = mainFile ? deriveSkillName(mainFile.content, fileName) : fileName.replace(/\.md$/i, "");
+  return {
+    name,
+    location: {
+      owner: identifier.owner,
+      repository: identifier.repository,
+      path: identifier.path,
+      ref
+    },
+    files
+  };
+};
 const resolveSkillSource = (source, location) => {
   if (source.startsWith("./")) {
     const skillsetDir = location.path.replace(/\/skillset\.yml$/, "");
@@ -839,108 +972,194 @@ const printSummary = (files, providerPath) => {
 `);
   });
 };
+const printCompleted = (startedAt) => {
+  const elapsed = Math.round((Date.now() - startedAt) / 1e3);
+  const timeStr = elapsed >= 60 ? `${Math.floor(elapsed / 60)}m${(elapsed % 60).toString().padStart(2, "0")}s` : `${elapsed}s`;
+  process.stdout.write(
+    `${green}✔${reset$2} Installation completed ${dim$1}in ${timeStr}${reset$2}
+`
+  );
+};
+const installSkillsetFlow = async (input, stepper, startedAt) => {
+  readConfig();
+  stepper.start("Resolving endpoint...", "packages");
+  const location = await resolveIdentifier(input);
+  const locationRef = `${location.owner}/${location.repository}@${location.ref}`;
+  stepper.succeed("Resolved", locationRef);
+  stepper.start("Fetching skillset manifest...", "packages");
+  const skillset = await fetchSkillset(location);
+  stepper.succeed(
+    `Fetched skillset manifest`,
+    `${skillset.name} v${skillset.version}`
+  );
+  const providerPath = knownProviders[skillset.provider];
+  if (!providerPath) {
+    throw new Error(
+      `Unknown provider "${skillset.provider}". Known providers: ${Object.keys(knownProviders).join(", ")}`
+    );
+  }
+  const provider = { path: providerPath };
+  const entries = resolveSkillset(skillset, location);
+  if (entries.length === 0) {
+    stepper.succeed("No files to download");
+    stepper.stop();
+    return;
+  }
+  const projectRoot = getProjectRoot();
+  const downloadDir = join(projectRoot, ".spm", skillset.name);
+  const toTargetPath = (entry) => {
+    if (entry.type === "skill" && entry.skillName) {
+      const fileName = entry.path.split("/").pop() ?? entry.path;
+      return `skills/${entry.skillName}/${fileName}`;
+    }
+    const skillsetDir = location.path.replace(/\/[^/]+$/, "");
+    return entry.path.startsWith(`${skillsetDir}/`) ? entry.path.slice(skillsetDir.length + 1) : entry.path;
+  };
+  stepper.start(`Downloading ${entries.length} file(s)...`, "packages");
+  const results = await downloadEntries(
+    entries,
+    location,
+    (type, path) => stepper.item(`${type} ${path.split("/").pop() ?? path}`)
+  );
+  const setupResults = results.filter((r) => r.type === "setup");
+  const installResults = results.filter((r) => r.type !== "setup");
+  await Promise.all(
+    installResults.map(async (result2) => {
+      const target = toTargetPath(result2);
+      const filePath = safePath(downloadDir, target);
+      await mkdir(dirname(filePath), { recursive: true });
+      await writeFile(filePath, result2.content, "utf-8");
+    })
+  );
+  let setupFile;
+  if (setupResults.length > 0) {
+    const setup = setupResults[0];
+    setupFile = join(downloadDir, "SETUP.md");
+    await mkdir(dirname(setupFile), { recursive: true });
+    await writeFile(setupFile, setup.content, "utf-8");
+  }
+  stepper.succeed(`Downloaded ${results.length} file(s)`);
+  const downloadedPaths = installResults.map((r) => toTargetPath(r));
+  const providerFullPath = join(projectRoot, provider.path);
+  const pruned = pruneUnchanged(downloadDir, providerFullPath);
+  if (pruned > 0) {
+    stepper.succeed(`Skipped ${pruned} unchanged file(s)`);
+  }
+  const model = skillset.provider === "claude" ? "haiku" : void 0;
+  const source = `https://github.com/${location.owner}/${location.repository}/blob/${location.ref}/${location.path}`;
+  const result = await installSkillset(
+    {
+      downloadDir,
+      setupFile,
+      providerDir: providerFullPath,
+      skillsetName: skillset.name,
+      skillsetVersion: skillset.version,
+      configPath: getConfigPath(),
+      model
+    },
+    stepper
+  );
+  addConfigEntry({
+    providerPath: provider.path,
+    kind: "skillsets",
+    name: skillset.name,
+    source
+  });
+  await rm(downloadDir, { recursive: true, force: true });
+  const spmDir = join(projectRoot, ".spm");
+  const remaining = await readdir(spmDir).catch(() => []);
+  if (remaining.length === 0) await rm(spmDir, { recursive: true, force: true });
+  stepper.stop();
+  printCompleted(startedAt);
+  const summaryFiles = result.files.length > 0 ? result.files : downloadedPaths;
+  printSummary(summaryFiles, provider.path);
+  process.stdout.write(
+    `
+🪄  ${cyan}Restart your AI agent to apply the new skills.${reset$2}
+`
+  );
+};
+const installSkillFlow = async (identifier, stepper, startedAt) => {
+  const { config } = readConfig();
+  stepper.start("Resolving skill...", "packages");
+  const resolved = await resolveSkill(identifier);
+  const locationRef = `${resolved.location.owner}/${resolved.location.repository}@${resolved.location.ref}`;
+  stepper.succeed("Resolved", `${resolved.name} ${dim$1}${locationRef}${reset$2}`);
+  const firstProvider = Object.entries(config.providers)[0];
+  if (!firstProvider) {
+    throw new Error(
+      "No provider detected. Initialize a provider directory first (e.g., .claude/)."
+    );
+  }
+  const [providerName, providerConfig] = firstProvider;
+  const providerPath = providerConfig.path;
+  const projectRoot = getProjectRoot();
+  const downloadDir = join(projectRoot, ".spm", resolved.name);
+  const skillDir = posix.dirname(resolved.location.path);
+  stepper.start(`Downloading ${resolved.files.length} file(s)...`, "packages");
+  await Promise.all(
+    resolved.files.map(async (file) => {
+      const relativePath = file.path.startsWith(`${skillDir}/`) ? file.path.slice(skillDir.length + 1) : file.path.split("/").pop() ?? file.path;
+      const filePath = safePath(downloadDir, relativePath);
+      await mkdir(dirname(filePath), { recursive: true });
+      await writeFile(filePath, file.content, "utf-8");
+      stepper.item(relativePath);
+    })
+  );
+  stepper.succeed(`Downloaded ${resolved.files.length} file(s)`);
+  const providerFullPath = join(projectRoot, providerPath);
+  const skillProviderDir = join(providerFullPath, "skills", resolved.name);
+  const pruned = pruneUnchanged(downloadDir, skillProviderDir);
+  if (pruned > 0) {
+    stepper.succeed(`Skipped ${pruned} unchanged file(s)`);
+  }
+  const model = providerName === "claude" ? "haiku" : void 0;
+  const source = `https://github.com/${resolved.location.owner}/${resolved.location.repository}/blob/${resolved.location.ref}/${resolved.location.path}`;
+  const result = await installSingleSkill(
+    {
+      downloadDir,
+      providerDir: providerFullPath,
+      skillName: resolved.name,
+      configPath: getConfigPath(),
+      model
+    },
+    stepper
+  );
+  addConfigEntry({
+    providerPath,
+    kind: "skills",
+    name: resolved.name,
+    source
+  });
+  await rm(downloadDir, { recursive: true, force: true });
+  const spmDir = join(projectRoot, ".spm");
+  const remaining = await readdir(spmDir).catch(() => []);
+  if (remaining.length === 0) await rm(spmDir, { recursive: true, force: true });
+  stepper.stop();
+  printCompleted(startedAt);
+  const downloadedPaths = resolved.files.map((f) => {
+    const skillDirPrefix = `${skillDir}/`;
+    return f.path.startsWith(skillDirPrefix) ? `skills/${resolved.name}/${f.path.slice(skillDirPrefix.length)}` : `skills/${resolved.name}/${f.path.split("/").pop() ?? f.path}`;
+  });
+  const summaryFiles = result.files.length > 0 ? result.files : downloadedPaths;
+  printSummary(summaryFiles, providerPath);
+  process.stdout.write(
+    `
+🪄  ${cyan}Restart your AI agent to apply the new skills.${reset$2}
+`
+  );
+};
 const registerInstallCommand = (program2) => {
-  program2.command("install <skillset>").alias("i").description("Install a skillset into the project").action(async (input) => {
+  program2.command("install <target>").alias("i").description("Install a skillset or skill into the project").action(async (input) => {
     const stepper = createStepper();
     const startedAt = Date.now();
     try {
-      readConfig();
-      stepper.start("Resolving endpoint...", "packages");
-      const location = await resolveIdentifier(input);
-      const locationRef = `${location.owner}/${location.repository}@${location.ref}`;
-      stepper.succeed("Resolved", locationRef);
-      stepper.start("Fetching skillset manifest...", "packages");
-      const skillset = await fetchSkillset(location);
-      stepper.succeed(
-        `Fetched skillset manifest`,
-        `${skillset.name} v${skillset.version}`
-      );
-      const providerPath = knownProviders[skillset.provider];
-      if (!providerPath) {
-        throw new Error(
-          `Unknown provider "${skillset.provider}". Known providers: ${Object.keys(knownProviders).join(", ")}`
-        );
-      }
-      const provider = { path: providerPath };
-      const entries = resolveSkillset(skillset, location);
-      if (entries.length === 0) {
-        stepper.succeed("No files to download");
-        stepper.stop();
-        return;
-      }
-      const projectRoot = getProjectRoot();
-      const downloadDir = join(projectRoot, ".spm", skillset.name);
-      const toTargetPath = (entry) => {
-        if (entry.type === "skill" && entry.skillName) {
-          const fileName = entry.path.split("/").pop() ?? entry.path;
-          return `skills/${entry.skillName}/${fileName}`;
-        }
-        const skillsetDir = location.path.replace(/\/[^/]+$/, "");
-        return entry.path.startsWith(`${skillsetDir}/`) ? entry.path.slice(skillsetDir.length + 1) : entry.path;
-      };
-      stepper.start(`Downloading ${entries.length} file(s)...`, "packages");
-      const results = await downloadEntries(
-        entries,
-        location,
-        (type, path) => stepper.item(`${type} ${path.split("/").pop() ?? path}`)
-      );
-      const setupResults = results.filter((r) => r.type === "setup");
-      const installResults = results.filter((r) => r.type !== "setup");
-      await Promise.all(
-        installResults.map(async (result2) => {
-          const target = toTargetPath(result2);
-          const filePath = safePath(downloadDir, target);
-          await mkdir(dirname(filePath), { recursive: true });
-          await writeFile(filePath, result2.content, "utf-8");
-        })
-      );
-      let setupFile;
-      if (setupResults.length > 0) {
-        const setup = setupResults[0];
-        setupFile = join(downloadDir, "SETUP.md");
-        await mkdir(dirname(setupFile), { recursive: true });
-        await writeFile(setupFile, setup.content, "utf-8");
-      }
-      stepper.succeed(`Downloaded ${results.length} file(s)`);
-      const downloadedPaths = installResults.map((r) => toTargetPath(r));
-      const providerFullPath = join(projectRoot, provider.path);
-      const pruned = pruneUnchanged(downloadDir, providerFullPath);
-      if (pruned > 0) {
-        stepper.succeed(`Skipped ${pruned} unchanged file(s)`);
+      const parsed = parseIdentifier(input);
+      if (parsed.kind === "skill") {
+        await installSkillFlow(parsed.identifier, stepper, startedAt);
+      } else {
+        await installSkillsetFlow(input, stepper, startedAt);
       }
-      const model = skillset.provider === "claude" ? "haiku" : void 0;
-      const result = await installSkillset(
-        {
-          downloadDir,
-          setupFile,
-          providerDir: providerFullPath,
-          skillsetName: skillset.name,
-          skillsetVersion: skillset.version,
-          source: `@${location.owner}/${location.repository}`,
-          configPath: getConfigPath(),
-          model
-        },
-        stepper
-      );
-      await rm(downloadDir, { recursive: true, force: true });
-      const spmDir = join(projectRoot, ".spm");
-      const remaining = await readdir(spmDir).catch(() => []);
-      if (remaining.length === 0)
-        await rm(spmDir, { recursive: true, force: true });
-      stepper.stop();
-      const elapsed = Math.round((Date.now() - startedAt) / 1e3);
-      const timeStr = elapsed >= 60 ? `${Math.floor(elapsed / 60)}m${(elapsed % 60).toString().padStart(2, "0")}s` : `${elapsed}s`;
-      process.stdout.write(
-        `${green}✔${reset$2} Installation completed ${dim$1}in ${timeStr}${reset$2}
-`
-      );
-      const summaryFiles = result.files.length > 0 ? result.files : downloadedPaths;
-      printSummary(summaryFiles, provider.path);
-      process.stdout.write(
-        `
-🪄  ${cyan}Restart your AI agent to apply the new skills.${reset$2}
-`
-      );
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       stepper.fail(message);
@@ -964,7 +1183,7 @@ const banner = (version2) => [
   `${shade}▝▜${light}████▛▘  ${reset$1}${dim}v${version2} ✨ supa-magic${reset$1}`,
   `${shade}  ▘${light}  ▝`
 ].join("\n");
-const version = "0.2.6";
+const version = "0.3.1";
 const program = new Command();
 const gray = "\x1B[90m";
 const reset = "\x1B[0m";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supa-magic/spm",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "CLI tool for managing AI skillsets",
   "license": "MIT",
   "contributors": [