d-skills 0.0.0-stage → 1.0.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# d-skills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Install agent skills into any project.
+
+```sh
+npx d-skills install
+```
+
+Run without flags for the interactive flow: pick an install directory, then
+pick categories. Skills land directly under the target directory
+(`<dir>/<skill>`), never nested by category.
+
+## Usage
+
+```sh
+npx d-skills install --dir .agents/skills --all
+npx d-skills install --category design
+npx d-skills install --category design --category integrations
+npx d-skills install --category design --offline
+npx d-skills install --dir /tmp/demo --dry-run
+npx d-skills list
+npx d-skills list --categories
+npx d-skills list --json
+```
+
+## Options
+
+| Flag                 | Default           | Purpose                                          |
+| -------------------- | ----------------- | ------------------------------------------------ |
+| `-d, --dir <path>`   | `.agents/skills`  | Install directory (`~` and relative paths work)  |
+| `-c, --category <n>` | all               | Install one category (repeatable)                |
+| `-a, --all`          |                   | Install all categories                           |
+| `-f, --force`        |                   | Overwrite skills that already exist              |
+| `--offline`          |                   | Use bundled `skills/` instead of downloading     |
+| `--dry-run`          |                   | Print the plan without copying                   |
+
+Existing skills are skipped unless `--force` is given. Unknown categories
+fail fast with a suggestion, e.g. `Did you mean: "desgin" → "design"?`.
+Piped runs never prompt: they default to all categories and `--dir`.
+
+## Install targets
+
+The interactive directory prompt offers presets plus a custom path:
+
+- `.agents/skills` (default)
+- `.claude/skills`
+- `.codex/skills`
+- `.cursor/skills`
+- Custom path
+
+## Source
+
+By default skills are downloaded from GitHub, so installs always get the
+latest version without republishing the npm package. Tag and SHA refs are
+cached under the OS temp directory; branch refs are re-downloaded.
+
+| Variable           | Default                         | Purpose                  |
+| ------------------ | ------------------------------- | ------------------------ |
+| `DSKILLS_REPO`     | `DaviRJ/d-skills`               | Source repository        |
+| `DSKILLS_REF`      | `main`                          | Branch, tag, or commit   |
+| `DSKILLS_BASE_URL` | `https://codeload.github.com`   | Tarball host (advanced)  |
+
+## Skills
+
+Skills live in `skills/<category>/<skill>/`. See `skills/README.md` for how
+to add a skill or category.
+
+## Development
+
+```sh
+pnpm install
+pnpm validate:skills
+pnpm build
+pnpm test
+node dist/cli.js --help
+```

package/dist/cli.js

@@ -0,0 +1,412 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+import { readFileSync as readFileSync3 } from "fs";
+import { dirname as dirname2, join as join5 } from "path";
+import { fileURLToPath } from "url";
+
+// src/commands/install.ts
+import { mkdtempSync, rmSync as rmSync2 } from "fs";
+import { homedir, tmpdir as tmpdir2 } from "os";
+import { isAbsolute, join as join4, resolve } from "path";
+import * as p2 from "@clack/prompts";
+
+// src/lib/categories.ts
+import { readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function parseFrontmatterField(content, field) {
+  const block = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!block) return null;
+  const line = block[1].match(new RegExp(`^${field}:\\s*(.+?)\\s*$`, "m"));
+  if (!line) return null;
+  return line[1].replace(/^["']|["']$/g, "").trim();
+}
+function discoverCategories(skillsRoot2) {
+  if (!isDirectory(skillsRoot2)) return [];
+  const categories = [];
+  for (const categoryName of readdirSync(skillsRoot2).sort()) {
+    const categoryDir = join(skillsRoot2, categoryName);
+    if (!isDirectory(categoryDir)) continue;
+    const skills = [];
+    for (const skillName of readdirSync(categoryDir).sort()) {
+      const skillDir = join(categoryDir, skillName);
+      if (!isDirectory(skillDir)) continue;
+      let description = "";
+      try {
+        const skillFile = readFileSync(join(skillDir, "SKILL.md"), "utf8");
+        description = parseFrontmatterField(skillFile, "description") ?? "";
+      } catch {
+        continue;
+      }
+      skills.push({
+        name: skillName,
+        description,
+        category: categoryName,
+        dir: skillDir
+      });
+    }
+    categories.push({ name: categoryName, dir: categoryDir, skills });
+  }
+  return categories;
+}
+function levenshtein(a, b) {
+  const grid = Array.from({ length: a.length + 1 }, (_, i) => [
+    i,
+    ...Array(b.length).fill(0)
+  ]);
+  for (let j = 1; j <= b.length; j++) grid[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      grid[i][j] = Math.min(
+        grid[i - 1][j] + 1,
+        grid[i][j - 1] + 1,
+        grid[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+    }
+  }
+  return grid[a.length][b.length];
+}
+function suggestSimilar(input, names) {
+  const lower = input.toLowerCase();
+  const partial = names.find(
+    (name) => name.toLowerCase().includes(lower) || lower.includes(name.toLowerCase())
+  );
+  if (partial) return partial;
+  let best;
+  let bestDist = 3;
+  for (const name of names) {
+    const dist = levenshtein(lower, name.toLowerCase());
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = name;
+    }
+  }
+  return best;
+}
+
+// src/lib/github.ts
+import { existsSync, mkdirSync, readFileSync as readFileSync2 } from "fs";
+import { tmpdir } from "os";
+import { join as join2 } from "path";
+import { writeFile } from "fs/promises";
+import * as tar from "tar";
+var DEFAULT_REPO = "DaviRJ/d-skills";
+var DEFAULT_REF = "main";
+function resolveRepo() {
+  return process.env.DSKILLS_REPO ?? DEFAULT_REPO;
+}
+function resolveRef() {
+  return process.env.DSKILLS_REF ?? DEFAULT_REF;
+}
+function tarballUrl(repo, ref) {
+  const base = process.env.DSKILLS_BASE_URL ?? "https://codeload.github.com";
+  return `${base}/${repo}/tar.gz/${ref}`;
+}
+function isCacheableRef(ref) {
+  return /^[0-9a-f]{7,40}$/i.test(ref) || /^v?\d+\.\d+\.\d+/.test(ref);
+}
+function cachePath(repo, ref) {
+  return join2(
+    tmpdir(),
+    "dskills-cache",
+    repo.replace("/", "-"),
+    `${ref}.tar.gz`
+  );
+}
+async function downloadTarball(repo, ref) {
+  const dest = cachePath(repo, ref);
+  if (isCacheableRef(ref) && existsSync(dest)) return dest;
+  let response;
+  try {
+    response = await fetch(tarballUrl(repo, ref));
+  } catch (cause) {
+    throw new Error(
+      `Cannot download skills from GitHub (${repo}@${ref}): ${cause.message}. Check your network or retry with --offline.`
+    );
+  }
+  if (!response.ok || !response.body) {
+    throw new Error(
+      `Cannot download skills from GitHub (${repo}@${ref}): HTTP ${response.status}. Check the repo and ref, or retry with --offline.`
+    );
+  }
+  mkdirSync(join2(dest, ".."), { recursive: true });
+  await writeFile(dest, Buffer.from(await response.arrayBuffer()));
+  return dest;
+}
+async function listTarballCategories(tarballPath) {
+  const categories = /* @__PURE__ */ new Set();
+  try {
+    const head = readFileSync2(tarballPath).subarray(0, 2);
+    if (head.length < 2 || head[0] !== 31 || head[1] !== 139) {
+      throw new Error("not a gzip archive");
+    }
+    await tar.t({
+      file: tarballPath,
+      onentry: (entry) => {
+        const parts = entry.path.split("/").filter((p3) => p3 !== "");
+        if (parts.length >= 3 && parts[1] === "skills")
+          categories.add(parts[2]);
+      }
+    });
+  } catch (cause) {
+    throw new Error(
+      `Cannot read downloaded archive: ${cause.message}`
+    );
+  }
+  return [...categories].sort();
+}
+async function extractSkills(tarballPath, destRoot, selection) {
+  try {
+    await tar.x({
+      file: tarballPath,
+      cwd: destRoot,
+      strip: 1,
+      filter: (path) => {
+        const parts = path.split("/").filter((p3) => p3 !== "");
+        if (parts.length < 2 || parts[1] !== "skills") return false;
+        if (parts.length === 2) return true;
+        return selection.length === 0 || selection.includes(parts[2]);
+      }
+    });
+  } catch (cause) {
+    throw new Error(
+      `Cannot extract downloaded archive: ${cause.message}`
+    );
+  }
+}
+
+// src/lib/installer.ts
+import { cpSync, existsSync as existsSync2, mkdirSync as mkdirSync2, rmSync } from "fs";
+import { dirname, join as join3 } from "path";
+function planInstall(categories, selection, targetDir) {
+  const wanted = selection.length === 0 ? categories : categories.filter((c) => selection.includes(c.name));
+  const plan = [];
+  for (const category of wanted) {
+    for (const skill of category.skills) {
+      plan.push({
+        skill: skill.name,
+        category: category.name,
+        sourceDir: skill.dir,
+        targetDir: join3(targetDir, skill.name)
+      });
+    }
+  }
+  return plan;
+}
+async function runInstall(plan, options = {}) {
+  const { force = false, dryRun = false } = options;
+  const results = [];
+  for (const item of plan) {
+    const exists = existsSync2(item.targetDir);
+    if (exists && !force) {
+      results.push({ ...item, status: "skipped" });
+      continue;
+    }
+    if (!dryRun) {
+      mkdirSync2(dirname(item.targetDir), { recursive: true });
+      if (exists) rmSync(item.targetDir, { recursive: true, force: true });
+      cpSync(item.sourceDir, item.targetDir, { recursive: true });
+    }
+    results.push({ ...item, status: exists ? "overwritten" : "installed" });
+  }
+  return results;
+}
+
+// src/lib/prompts.ts
+import * as p from "@clack/prompts";
+var CUSTOM_DIR = "__custom__";
+var INSTALL_PRESETS = [
+  ".agents/skills",
+  ".claude/skills",
+  ".codex/skills",
+  ".cursor/skills"
+];
+async function askInstallDir(defaultDir) {
+  const presets = [.../* @__PURE__ */ new Set([defaultDir, ...INSTALL_PRESETS])];
+  const choice = await p.select({
+    message: "Install directory?",
+    options: [
+      ...presets.map((dir) => ({ value: dir, label: dir })),
+      { value: CUSTOM_DIR, label: "Custom path..." }
+    ]
+  });
+  if (p.isCancel(choice)) {
+    p.cancel("Cancelled.");
+    process.exit(0);
+  }
+  if (choice !== CUSTOM_DIR) return choice;
+  const custom = await p.text({
+    message: "Custom directory?",
+    placeholder: defaultDir
+  });
+  if (p.isCancel(custom)) {
+    p.cancel("Cancelled.");
+    process.exit(0);
+  }
+  const trimmed = String(custom).trim();
+  return trimmed === "" ? defaultDir : trimmed;
+}
+async function askScope(categories) {
+  const value = await p.multiselect({
+    message: "Which categories to install?",
+    options: categories.map((c) => ({
+      value: c.name,
+      label: c.name,
+      hint: `${c.skills.length} skills`
+    })),
+    initialValues: categories.map((c) => c.name),
+    required: true
+  });
+  if (p.isCancel(value)) {
+    p.cancel("Cancelled.");
+    process.exit(0);
+  }
+  const selected = value;
+  if (selected.length === categories.length) return [];
+  return selected;
+}
+
+// src/commands/install.ts
+var DEFAULT_DIR = ".agents/skills";
+function resolveTargetDir(input) {
+  if (input === "~") return homedir();
+  const expanded = input.startsWith("~/") ? join4(homedir(), input.slice(2)) : input;
+  return isAbsolute(expanded) ? expanded : resolve(process.cwd(), expanded);
+}
+function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+function assertKnownCategories(requested, names) {
+  const unknown = requested.filter((c) => !names.includes(c));
+  if (unknown.length === 0) return;
+  const hints = unknown.flatMap((u) => {
+    const match = suggestSimilar(u, names);
+    return match ? [`"${u}" \u2192 "${match}"`] : [];
+  });
+  throw new Error(
+    `Unknown categor${unknown.length === 1 ? "y" : "ies"}: ${unknown.join(", ")}.${hints.length > 0 ? ` Did you mean: ${hints.join(", ")}?` : ""} Available: ${names.join(", ")}`
+  );
+}
+async function runInstallCommand(options) {
+  const requested = options.all ? [] : options.category ?? [];
+  let categories;
+  let cleanup;
+  if (options.offline) {
+    categories = discoverCategories(options.skillsRoot);
+    if (categories.length === 0) {
+      throw new Error(`No skills found in ${options.skillsRoot}.`);
+    }
+  } else {
+    const repo = resolveRepo();
+    const ref = resolveRef();
+    const tarball = await downloadTarball(repo, ref);
+    const available = await listTarballCategories(tarball);
+    if (available.length === 0) {
+      throw new Error(`No skills found in ${repo}@${ref}.`);
+    }
+    assertKnownCategories(requested, available);
+    const workDir = mkdtempSync(join4(tmpdir2(), "dskills-"));
+    cleanup = () => rmSync2(workDir, { recursive: true, force: true });
+    await extractSkills(tarball, workDir, requested);
+    categories = discoverCategories(join4(workDir, "skills"));
+  }
+  try {
+    assertKnownCategories(
+      requested,
+      categories.map((c) => c.name)
+    );
+    const interactive = isInteractive();
+    let dir = options.dir;
+    let selection = requested;
+    if (interactive) {
+      p2.intro("d-skills");
+      if (dir === void 0) dir = await askInstallDir(DEFAULT_DIR);
+      if (!options.all && selection.length === 0)
+        selection = await askScope(categories);
+    }
+    const targetDir = resolveTargetDir(dir ?? DEFAULT_DIR);
+    const plan = planInstall(categories, selection, targetDir);
+    if (options.dryRun) {
+      console.log(`Would install ${plan.length} skills to ${targetDir}:`);
+      for (const item of plan)
+        console.log(`  ${item.skill} (${item.category})`);
+      if (interactive) p2.outro("Dry run \u2014 nothing was copied.");
+      return;
+    }
+    const results = await runInstall(plan, { force: options.force });
+    const counts = { installed: 0, overwritten: 0, skipped: 0 };
+    for (const result of results) {
+      counts[result.status] += 1;
+      console.log(`${result.status} ${result.skill} (${result.category})`);
+    }
+    const summary = `Done: ${counts.installed} installed, ${counts.overwritten} overwritten, ${counts.skipped} skipped \u2192 ${targetDir}`;
+    if (interactive) {
+      p2.outro(`${summary}
+Skills land directly under the target directory.`);
+    } else {
+      console.log(summary);
+    }
+  } finally {
+    cleanup?.();
+  }
+}
+
+// src/commands/list.ts
+function runList(options) {
+  const categories = discoverCategories(options.skillsRoot);
+  if (options.json) {
+    console.log(JSON.stringify(categories, null, 2));
+    return;
+  }
+  if (categories.length === 0) {
+    console.log("No skills found.");
+    return;
+  }
+  for (const category of categories) {
+    console.log(`${category.name} (${category.skills.length})`);
+    if (!options.categories) {
+      for (const skill of category.skills) {
+        console.log(`  - ${skill.name}`);
+      }
+    }
+  }
+}
+
+// src/cli.ts
+var rootDir = join5(dirname2(fileURLToPath(import.meta.url)), "..");
+var skillsRoot = join5(rootDir, "skills");
+function packageVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync3(join5(rootDir, "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+var program = new Command();
+program.name("d-skills").description("Install agent skills into any project").version(packageVersion());
+program.command("install").description("Install skills into a local directory").option("-d, --dir <path>", "install directory").option(
+  "-c, --category <name>",
+  "install single category (repeatable)",
+  (value, acc) => [...acc, value],
+  []
+).option("-a, --all", "install all categories").option("-f, --force", "overwrite existing skills").option("--offline", "use bundled skills instead of GitHub").option("--dry-run", "print plan without copying").action(async (opts) => {
+  try {
+    await runInstallCommand({ ...opts, skillsRoot });
+  } catch (error) {
+    console.error(`error: ${error.message}`);
+    process.exitCode = 1;
+  }
+});
+program.command("list").description("List available categories and skills").option("--json", "machine-readable output").option("--categories", "category names only").action((opts) => {
+  runList({ ...opts, skillsRoot });
+});
+program.parse();

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "d-skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Install agent skills into any project",
+  "license": "MIT",
+  "author": "Davi Bezerra",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DaviRJ/d-skills.git"
+  },
+  "homepage": "https://github.com/DaviRJ/d-skills#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "d-skills": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "keywords": [
+    "skills",
+    "agents",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "11.28.5",
+      "onFail": "download"
+    }
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "commander": "^15.0.0",
+    "tar": "^7.5.22"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "@types/tar": "^7.0.87",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "validate:skills": "node scripts/validate-skills.mjs"
+  }
 }

package/skills/README.md

@@ -0,0 +1,35 @@
+# Skills
+
+Skills are grouped by category using plain folders:
+
+```text
+skills/<category>/<skill>/SKILL.md
+```
+
+Current categories:
+
+- `design` — visual and content design skills
+- `integrations` — third-party service integrations
+
+## Add a new skill
+
+1. Create `skills/<category>/<skill>/`.
+2. Add `SKILL.md` with frontmatter where `name` matches the folder name:
+
+```md
+---
+name: my-skill
+description: What this skill does.
+---
+```
+
+3. Add optional `references/`, `scripts/`, `templates/`, `data/` next to `SKILL.md`.
+4. Run `pnpm validate:skills`.
+
+## Add a new category
+
+1. Create `skills/<new-category>/` using lowercase letters, numbers, and dashes.
+2. Add one or more skills inside it.
+3. Run `pnpm validate:skills`.
+
+No registry file or code change is required. The CLI discovers categories by scanning directories.