skillshelf 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wang-Cankun
+
+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

@@ -0,0 +1,208 @@
+# skillshelf
+
+**A package manager for your agent skills — one canonical library, loaded on demand, never all at once.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-black?logo=bun)](https://bun.sh)
+[![CI](https://img.shields.io/github/actions/workflow/status/Wang-Cankun/skillshelf/ci.yml?branch=main)](https://github.com/Wang-Cankun/skillshelf/actions)
+[![npm](https://img.shields.io/npm/v/skillshelf.svg)](https://www.npmjs.com/package/skillshelf)
+
+Your skills are scattered: some in `~/.claude/skills`, some buried in Obsidian or notes
+vaults, more copied into a dozen per-project `.claude` directories. You forget which ones
+exist, rewrite ones you already have, and copies drift out of sync. The naive fix — dump
+everything into `~/.claude/skills` — makes every session pay the token cost of loading
+hundreds of skill descriptions at once.
+
+skillshelf is the middle path: a single git-backed **library** that is a *passive shelf*
+(nothing auto-loads), plus a CLI to **search, tag, bundle, and load** exactly the skills a
+project needs, exactly when it needs them. Find anything in one place; pay only for what you
+actually use.
+
+## Install
+
+skillshelf runs on [Bun](https://bun.sh) (>= 1.0). No other runtime dependencies.
+
+```bash
+# Run it without installing
+bunx skillshelf <command>
+
+# Or install the `skl` binary globally
+bun add -g skillshelf
+skl <command>
+```
+
+## Quickstart
+
+```bash
+# 1. Set up the config + library and link the thin global core
+skl init
+
+# 2. Scaffold a new skill into the library (or `skl add` a third-party one)
+skl new rnaseq-qc --domain bioinfo --desc "QC gate for RNA-seq count matrices"
+
+# 3. Find skills across the whole library
+skl ls
+skl search rnaseq
+
+# 4. Read a skill's instructions on demand — no token cost until you ask
+skl show rnaseq-qc
+
+# 5. Activate a domain bundle in the project you're working in
+cd ~/projects/my-analysis
+skl use bioinfo      # symlinks every skill tagged `bioinfo` into ./.claude/skills
+skl status           # what's currently linked here
+skl drop bioinfo     # unlink when you're done
+```
+
+Add `--json` to any command for machine-readable output (skillshelf is built to be driven
+by an agent as well as a human).
+
+## How it works
+
+skillshelf separates *owning* a skill from *loading* it.
+
+- **Canonical library** — a dedicated git repo, one file per skill in its primary-domain
+  folder. This is a passive shelf: nothing here auto-loads, which is exactly what kills the
+  all-at-once token cost.
+- **Domain bundles** — bundles are *tag queries*, not folders. A skill tagged
+  `domains: [coding, bioinfo]` shows up in both bundles from a single copy on disk.
+  `skl use bioinfo` resolves every skill carrying that tag.
+- **Thin global core** — a handful of universal skills (commit, search, memory) are
+  symlinked permanently into `~/.claude/skills` so they always auto-trigger. Small, bounded
+  token cost — "some loaded is fine; all-at-once is the problem."
+- **On-demand `show`** — prints only the SKILL.md instruction body and lists the paths of
+  any bundled reference files (without reading them). Progressive disclosure: cheap by
+  default, deep when you ask. Works mid-task with no reload.
+- **Sidecar overlay** — installed third-party skills keep a pristine `upstream/` body plus a
+  `<skill>.shelf.json` overlay holding *your* tags, bundle membership, and notes. `skl update`
+  swaps the upstream body cleanly while your taxonomy survives — updates never clobber your tags.
+
+```
+                       skl search / ls / show          skl use <bundle>
+                                │                              │
+   ┌──────────────────────┐    │   ┌──────────────────────┐   │   ┌─────────────────────┐
+   │   canonical library  │────┴──▶│   bundles = tag query │───┴──▶│  project .claude/   │
+   │  (passive git shelf) │        │  bioinfo · coding · … │       │  skills/ (symlinks) │
+   └──────────┬───────────┘        └──────────────────────┘       └─────────────────────┘
+              │
+              └──── thin global core ──▶ ~/.claude/skills  (always-on, bounded)
+```
+
+See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for the full design.
+
+## Command reference
+
+| Command | Summary | Key flags |
+|---|---|---|
+| `skl init` | Set up `~/.skillshelf` config + library and link the global-core skills | `--force` |
+| `skl new <name>` | Scaffold a new skill dir + SKILL.md into the library | `--domain <d>`, `--desc "..."`, `--force` |
+| `skl ls [bundle]` | One-line listing of the library, or one bundle | `--all` |
+| `skl search <kw...>` | Fuzzy match over name + description + domains across the library | — |
+| `skl show <name>` | Print a skill's SKILL.md body; list reference-file paths (not contents) | — |
+| `skl status` | Show which library skills are linked into `./.claude/skills` | — |
+| `skl use <bundle>` | Symlink a bundle's skills into `./.claude/skills/` (hot-loads) | — |
+| `skl drop <bundle>` | Remove a bundle's symlinks from `./.claude/skills/` | — |
+| `skl add <src>` | Install a third-party skill (`github:`/registry), record provenance, auto-tag | `--domain <d>`, `--name <slug>`, `--no-infer`, `--force` |
+| `skl outdated [name]` | Check upstream ref per tracked skill and mark stale ones | — |
+| `skl update [name]` | Re-pull upstream body, preserve overlay, diff if local body diverged | `--force`, `--dry-run` |
+| `skl index` | Regenerate `INDEX.md` (catalog grouped by domain) | — |
+| `skl infer` | Re-run AI domain taxonomy over the library (emit/apply/provider modes) | see below |
+
+Every command also accepts `--json`.
+
+## AI taxonomy & inference
+
+Domains and tags can be inferred and re-run by an LLM via `skl infer`. **This is optional —
+the entire core (search, ls, show, use, bundles, add, update) works fully without any LLM.**
+Inference has three mutually exclusive modes:
+
+```
+skl infer [--emit | --apply <file.json> | --provider <name>] \
+          [--base-url <url>] [--model <id>] [--include-retired] [--json]
+```
+
+**Agent modes (no network call from skillshelf):**
+
+- `--emit` — print a self-contained prompt + the library payload as JSON. Hand it to whatever
+  agent or model you already have open; it does the reasoning.
+- `--apply <file.json>` — apply the taxonomy proposal the agent produced back into the library
+  (for review/approval), updating tags via the overlay.
+
+**API mode (skillshelf calls an OpenAI-compatible endpoint itself):**
+
+Entered when **either** `--provider` **or** `--base-url` is given. The request is
+`POST {base}/chat/completions`, OpenAI schema, `temperature: 0`,
+`response_format: {type: "json_object"}` (strict JSON; falls back to brace-extraction if the
+model wraps JSON in prose or fences).
+
+`--provider <name>` is sugar that only sets a default base URL — the API key always comes
+from the environment or a dotenv file.
+
+| Provider | Base URL |
+|---|---|
+| `openai` | `https://api.openai.com/v1` |
+| `openrouter` | `https://openrouter.ai/api/v1` |
+| `groq` | `https://api.groq.com/openai/v1` |
+| `ollama` | `http://localhost:11434/v1` |
+| `custom` | resolved entirely from `--base-url` / env |
+
+Resolution order, applied independently to base URL, API key, and model (highest precedence
+first):
+
+1. CLI flags (`--base-url`, `--model`; `--provider` for the base-URL preset)
+2. Environment variables — `SKILLSHELF_LLM_*` primary, then `OPENAI_*` fallback
+3. Optional dotenv file at `$SKILLSHELF_ENV_FILE` (default: `./.env` if it exists, else none)
+
+**Environment variables:**
+
+| Variable | Purpose |
+|---|---|
+| `SKILLSHELF_LLM_BASE_URL` | base URL including `/v1` |
+| `SKILLSHELF_LLM_API_KEY` | bearer API key |
+| `SKILLSHELF_LLM_MODEL` | chat model id |
+| `SKILLSHELF_ENV_FILE` | path to a dotenv file (optional; default `./.env` if present) |
+| `OPENAI_BASE_URL` / `OPENAI_API_KEY` / `OPENAI_MODEL` | convention fallbacks for the three above |
+
+Defaults: base URL `https://api.openai.com/v1`, model `gpt-4o-mini` (a placeholder —
+override with `--model` or `*_MODEL`).
+
+The dotenv parser supports `KEY=value` and `export KEY=value`, strips surrounding quotes,
+ignores blank and `#` comment lines, and never throws.
+
+Errors are deterministic and raised before any network call:
+
+- No resolvable key → `missing API key. Set SKILLSHELF_LLM_API_KEY (or OPENAI_API_KEY) in the environment or a dotenv file ($SKILLSHELF_ENV_FILE, default ./.env).`
+- Unknown provider → `unknown provider "X". known: openai, openrouter, groq, ollama, custom`
+
+Example:
+
+```bash
+export SKILLSHELF_LLM_API_KEY=sk-...
+skl infer --provider openai --model gpt-4o-mini
+# or fully self-hosted:
+skl infer --base-url http://localhost:11434/v1 --model llama3.1
+```
+
+## Configuration
+
+| Setting | What it controls | Default |
+|---|---|---|
+| `SKILLSHELF_LIBRARY` | path to the canonical library (env, highest precedence) | `~/.skillshelf/library` |
+| `~/.skillshelf/config.json` | `{ "library": "...", "globalCore": "..." }` | — |
+| `SKILLSHELF_GLOBAL_CORE` | where global-core skills are symlinked | `~/.claude/skills` |
+
+Library path resolution: `SKILLSHELF_LIBRARY` → `config.json` → default. See the
+[AI taxonomy](#ai-taxonomy--inference) section for the `SKILLSHELF_LLM_*` / `OPENAI_*` /
+`SKILLSHELF_ENV_FILE` inference variables.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Tests run on Bun:
+
+```bash
+bun test
+```
+
+## License
+
+[MIT](./LICENSE) © skillshelf contributors.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "skillshelf",
+  "version": "0.1.0",
+  "description": "Agent-first skill registry + manager for Claude Code and compatible agents.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Wang-Cankun (https://github.com/Wang-Cankun)",
+  "homepage": "https://github.com/Wang-Cankun/skillshelf#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Wang-Cankun/skillshelf.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Wang-Cankun/skillshelf/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "skills",
+    "agent",
+    "cli",
+    "registry",
+    "bun"
+  ],
+  "bin": {
+    "skl": "./src/cli.ts"
+  },
+  "scripts": {
+    "skl": "bun run src/cli.ts",
+    "test": "bun test"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/adapters/inference/agent.ts

@@ -0,0 +1,253 @@
+// Agent-driven inference adapter (LLM-FREE core).
+//
+// `skl infer` is dual-mode but its deterministic core never calls an LLM:
+//   - emit : assemble an InferenceCorpus + JSON schema + instruction and print it
+//            to stdout so the HOST agent (Claude Code) can reason over it and
+//            produce a proposal file.
+//   - apply: read the agent's proposal JSON and write proposed domains/tags into
+//            each skill's `<name>.shelf.json` overlay (never upstream SKILL.md).
+//
+// The api.ts adapter reuses buildCorpus() + applyProposal() to close the loop
+// automatically against any OpenAI-compatible LLM endpoint.
+
+import type { InferenceCorpus, Overlay, Skill } from "../../types.ts";
+import { listDomains } from "../../core/library.ts";
+import { readOverlay, writeOverlay } from "../../core/overlay.ts";
+import { parseFrontmatter } from "../../lib/frontmatter.ts";
+
+/** Max characters of SKILL.md body included per skill in the corpus preview. */
+const BODY_PREVIEW_CHARS = 1200;
+
+/**
+ * The proposal shape the host agent (or the gateway) must return: a map of
+ * skill name -> proposed domains, plus optional primary + notes. Authors apply
+ * `domains` into each overlay (unioned with existing, never destructive).
+ */
+export interface InferenceProposalEntry {
+  name: string;
+  domains: string[];
+  primaryDomain?: string | null;
+  notes?: string;
+}
+
+export interface InferenceProposal {
+  /** vocabulary the model settled on (may surface new domains) */
+  domains?: string[];
+  /** per-skill assignments */
+  assignments: InferenceProposalEntry[];
+}
+
+/** JSON Schema describing the InferenceProposal the agent must produce. */
+export const PROPOSAL_SCHEMA = {
+  type: "object",
+  required: ["assignments"],
+  properties: {
+    domains: {
+      type: "array",
+      items: { type: "string" },
+      description: "The domain vocabulary you settled on. Surface new domains freely.",
+    },
+    assignments: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["name", "domains"],
+        properties: {
+          name: { type: "string", description: "Exact skill name from the corpus." },
+          domains: {
+            type: "array",
+            items: { type: "string" },
+            description: "Domain tags for this skill, primary first. Lowercase, hyphenated.",
+          },
+          primaryDomain: {
+            type: ["string", "null"],
+            description: "The single primary domain (usually domains[0]).",
+          },
+          notes: { type: "string", description: "Optional one-line rationale." },
+        },
+        additionalProperties: false,
+      },
+    },
+  },
+  additionalProperties: false,
+} as const;
+
+/** Instruction text handed to the host agent alongside the corpus + schema. */
+export const INFER_INSTRUCTION = [
+  "You are the taxonomy inference pass for a personal skill library.",
+  "Read the `corpus` below: each entry is a skill with its name, description,",
+  "current domain tags, and a body preview. Cluster the skills into a small,",
+  "coherent set of domains. You MAY invent domains the author did not think of",
+  "(e.g. `coding`) when the evidence supports it. Assign each skill a primary",
+  "domain plus any honest secondary tags (a dual-use skill belongs to multiple).",
+  "Keep domain tokens lowercase and hyphenated.",
+  "Return ONE JSON object that validates against `schema` (no prose, no markdown",
+  "fences). Then run `skl infer --apply <file.json>` to write it into the overlays.",
+].join(" ");
+
+/** Build the deterministic InferenceCorpus snapshot from loaded skills. */
+export async function buildCorpus(
+  skills: Skill[],
+  opts: { generatedAt?: string; includeRetired?: boolean } = {},
+): Promise<InferenceCorpus> {
+  const pool = opts.includeRetired ? skills : skills.filter((s) => !s.retired);
+  // Prefer canonical copies: skip .agents bridge mirrors so each name appears once.
+  const seen = new Set<string>();
+  const corpusSkills: InferenceCorpus["skills"] = [];
+  for (const s of pool) {
+    if (s.mirrorOf) continue;
+    if (seen.has(s.name)) continue;
+    seen.add(s.name);
+    corpusSkills.push({
+      name: s.name,
+      description: s.description,
+      currentDomains: s.domains,
+      bodyPreview: await readBodyPreview(s),
+    });
+  }
+  corpusSkills.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return {
+    skills: corpusSkills,
+    observedDomains: listDomains(pool),
+    generatedAt: opts.generatedAt ?? new Date().toISOString(),
+  };
+}
+
+/** Read + trim the SKILL.md body (frontmatter stripped) for a corpus preview. */
+async function readBodyPreview(skill: Skill): Promise<string> {
+  let raw = "";
+  try {
+    raw = await Bun.file(skill.bodyPath).text();
+  } catch {
+    return "";
+  }
+  const { body } = parseFrontmatter(raw);
+  const flat = body.replace(/\s+/g, " ").trim();
+  if (flat.length <= BODY_PREVIEW_CHARS) return flat;
+  return flat.slice(0, BODY_PREVIEW_CHARS - 1).trimEnd() + "…";
+}
+
+/** The full emit payload: instruction + schema + corpus. */
+export interface InferEmitPayload {
+  instruction: string;
+  schema: typeof PROPOSAL_SCHEMA;
+  corpus: InferenceCorpus;
+}
+
+/** Assemble the emit payload a host agent reasons over. */
+export async function buildEmitPayload(
+  skills: Skill[],
+  opts: { generatedAt?: string; includeRetired?: boolean } = {},
+): Promise<InferEmitPayload> {
+  return {
+    instruction: INFER_INSTRUCTION,
+    schema: PROPOSAL_SCHEMA,
+    corpus: await buildCorpus(skills, opts),
+  };
+}
+
+/** Coerce arbitrary parsed JSON into a normalized InferenceProposal. */
+export function normalizeProposal(raw: unknown): InferenceProposal {
+  const obj = (raw && typeof raw === "object" ? raw : {}) as Record<string, unknown>;
+  // Accept either {assignments:[...]} or a bare {name:domains} map.
+  let assignmentsRaw: unknown = obj.assignments;
+  if (!Array.isArray(assignmentsRaw)) {
+    // try a plain map form: { "skill-a": ["x","y"], ... }
+    const map = obj as Record<string, unknown>;
+    const fromMap: InferenceProposalEntry[] = [];
+    for (const [k, v] of Object.entries(map)) {
+      if (k === "domains" || k === "assignments") continue;
+      if (Array.isArray(v)) {
+        fromMap.push({ name: k, domains: v.map((x) => String(x).trim()).filter(Boolean) });
+      }
+    }
+    assignmentsRaw = fromMap;
+  }
+  const assignments: InferenceProposalEntry[] = [];
+  for (const a of assignmentsRaw as unknown[]) {
+    if (!a || typeof a !== "object") continue;
+    const e = a as Record<string, unknown>;
+    const name = typeof e.name === "string" ? e.name.trim() : "";
+    if (name === "") continue;
+    const domains = Array.isArray(e.domains)
+      ? e.domains.map((x) => String(x).trim()).filter(Boolean)
+      : [];
+    const entry: InferenceProposalEntry = { name, domains };
+    if (typeof e.primaryDomain === "string") entry.primaryDomain = e.primaryDomain.trim();
+    else if (e.primaryDomain === null) entry.primaryDomain = null;
+    if (typeof e.notes === "string" && e.notes.trim() !== "") entry.notes = e.notes.trim();
+    assignments.push(entry);
+  }
+  const domains = Array.isArray(obj.domains)
+    ? obj.domains.map((x) => String(x).trim()).filter(Boolean)
+    : undefined;
+  return domains ? { domains, assignments } : { assignments };
+}
+
+export interface ApplyResult {
+  /** skill name -> domains written into its overlay */
+  applied: Array<{ name: string; domains: string[]; added: string[] }>;
+  /** assignment names with no matching skill in the library */
+  unmatched: string[];
+  /** assignment names skipped because they proposed no domains */
+  skipped: string[];
+}
+
+/**
+ * Apply a proposal into each skill's overlay. Domains are UNIONED with the
+ * skill's existing effective domains (never destructive), written to
+ * `<name>.shelf.json` only — upstream SKILL.md is never touched.
+ */
+export async function applyProposal(
+  skills: Skill[],
+  proposal: InferenceProposal,
+): Promise<ApplyResult> {
+  const byName = new Map<string, Skill>();
+  for (const s of skills) {
+    // prefer canonical (non-mirror) copy when a name appears twice
+    const existing = byName.get(s.name);
+    if (!existing || (existing.mirrorOf && !s.mirrorOf)) byName.set(s.name, s);
+  }
+
+  const applied: ApplyResult["applied"] = [];
+  const unmatched: string[] = [];
+  const skipped: string[] = [];
+
+  for (const a of proposal.assignments) {
+    const skill = byName.get(a.name);
+    if (!skill) {
+      unmatched.push(a.name);
+      continue;
+    }
+    // Order: primaryDomain first (if given), then proposed domains, de-duped.
+    const ordered: string[] = [];
+    const push = (d: string | null | undefined) => {
+      const s = (d ?? "").trim();
+      if (s !== "" && !ordered.includes(s)) ordered.push(s);
+    };
+    push(a.primaryDomain);
+    for (const d of a.domains) push(d);
+    if (ordered.length === 0) {
+      skipped.push(a.name);
+      continue;
+    }
+
+    const prev = await readOverlay(skill);
+    const existingDomains = Array.isArray(prev?.domains) ? prev!.domains : [];
+    const merged: string[] = [...existingDomains];
+    const added: string[] = [];
+    for (const d of ordered) {
+      if (!merged.includes(d)) {
+        merged.push(d);
+        added.push(d);
+      }
+    }
+
+    const next: Overlay = { ...(prev ?? {}), domains: merged };
+    if (a.notes) next.notes = a.notes;
+    await writeOverlay(skill, next);
+    applied.push({ name: a.name, domains: merged, added });
+  }
+
+  return { applied, unmatched, skipped };
+}