@lythos/skill-deck 0.3.0 → 0.5.0

package/README.md

@@ -1,40 +1,130 @@
 # @lythos/skill-deck
 
-> Declarative skill deck governance. Reconcile declared skills against your cold pool via symlinks.
+> Declarative skill deck governance. Reconcile declared skills against your cold pool via symlinks — deny-by-default, max-cards budgeting, transient expiry.
 
-Part of the [lythoskill](https://github.com/lythos-labs/lythoskill) meta-skill ecosystem.
+## For AI Agents
 
-## What it does
+This package exposes a **CLI**. Invoke via:
 
-Manages your agent's working set of skills. You declare which skills you want in `skill-deck.toml`; `deck link` creates symlinks from the cold pool to `.claude/skills/`. Supports deny-by-default isolation, max_cards budgeting, transient expiry, and managed directory overlap detection.
+```bash
+bunx @lythos/skill-deck <command> [options]
+```
 
-## Install
+No installation required. `bunx` auto-downloads the package.
 
-```bash
-bun add -d @lythos/skill-deck
-# or
-bunx @lythos/skill-deck <command>
+### skill-deck.toml (minimal)
+
+```toml
+[deck]
+max_cards = 10
+
+[tool]
+skills = ["lythoskill-deck"]
 ```
 
-## Commands
+### skill-deck.toml (full reference)
+
+```toml
+[deck]
+max_cards = 10              # Hard limit on total skills
+working_set = ".claude/skills"      # Where symlinks are created
+cold_pool = "~/.agents/skill-repos" # Where skills are downloaded
+
+[innate]                    # Always-loaded skills
+skills = ["lythoskill-deck"]
+
+[tool]                      # Auto-triggered skills
+skills = ["skill-a", "skill-b"]
+
+[combo]                     # Multi-skill bundles
+skills = ["report-generation-combo"]
+
+[transient]                 # Temporary skills with expiry
+  [transient.handoff]
+  path = "./skills/handoff" # Local path (not cold pool)
+  expires = "2026-05-01"    # ISO date; warns at ≤14 days
+```
+
+### When to invoke
+
+| Situation | Command |
+|-----------|---------|
+| Sync `.claude/skills/` with `skill-deck.toml` | `bunx @lythos/skill-deck link` |
+| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck validate` |
+| Use a custom deck file or working dir | `bunx @lythos/skill-deck link --deck ./my-deck.toml --workdir /path/to/project` |
+
+### Commands
+
+| Command | Args | Description |
+|---------|------|-------------|
+| `link` | `[--deck <path>] [--workdir <dir>]` | Sync working set. Removes undeclared skills (deny-by-default). |
+| `validate` | `[deck.toml] [--workdir <dir>]` | Validate deck config without modifying files. |
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--deck <path>` | Path to skill-deck.toml | Find upward from cwd |
+| `--workdir <dir>` | Working directory | cwd |
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Validation failed, deck not found, or budget exceeded |
+
+---
+
+## For Humans
+
+### Why
+
+When an AI agent has access to 50+ skills, context window pollution and silent conflicts become real problems. Two skills claiming the same niche, redundant descriptions, incompatible assumptions — all invisible until the agent hallucinates.
+
+`skill-deck.toml` solves this by declaring *exactly* which skills the agent should see. `deck link` creates symlinks from the cold pool to `.claude/skills/` and **removes everything else**. Deny-by-default means undeclared skills physically do not exist in the agent's view.
+
+### Quick Start
 
 ```bash
-# Link declared skills to working set
+# 1. Create a skill-deck.toml
+cat > skill-deck.toml << 'EOF'
+[deck]
+max_cards = 10
+
+[tool]
+skills = ["lythoskill-deck"]
+EOF
+
+# 2. Link — creates symlinks in .claude/skills/
 bunx @lythos/skill-deck link
+```
 
-# Link with custom deck file
-bunx @lythos/skill-deck link --deck ./my-deck.toml
+### Key Concepts
 
-# Show current deck status
-bunx @lythos/skill-deck status
+| Concept | One-liner |
+|---------|-----------|
+| **Cold Pool** | All downloaded skills (`~/.agents/skill-repos/`). Agent cannot see here. |
+| **skill-deck.toml** | Declares desired state: "this project uses these skills." |
+| **`deck link`** | Reconciler. Makes `.claude/skills/` match the declaration. |
+| **Working Set** | `.claude/skills/` — symlinks only. What the agent actually scans. |
+| **deny-by-default** | Undeclared skills are physically absent from the working set. |
 
-# Migrate from old deck format
-bunx @lythos/skill-deck migrate
-```
+## Skill Documentation
+
+This package is the **Starter** layer (CLI implementation).  
+The agent-visible **Skill** layer documentation is here:  
+[packages/lythoskill-deck/skill/SKILL.md](../../packages/lythoskill-deck/skill/SKILL.md)
 
 ## Architecture
 
-This is the **Starter** layer of the thin-skill pattern. The agent-visible **Skill** layer lives in `packages/lythoskill-deck/skill/` and is built to `skills/lythoskill-deck/`.
+Part of the [lythoskill](https://github.com/lythos-labs/lythoskill) ecosystem — the thin-skill pattern separates heavy logic (this npm package) from lightweight agent instructions (SKILL.md).
+
+```
+Starter (this package) → npm publish → bunx @lythos/skill-deck ...
+Skill   (packages/<name>/skill/)     → build → SKILL.md + thin scripts
+Output  (skills/<name>/)             → git commit → agent-visible skill
+```
 
 ## License
 

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "@lythos/skill-deck",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
+  "keywords": [
+    "ai-agent",
+    "skill",
+    "claude-code",
+    "agent-skills",
+    "llm-tooling",
+    "lythoskill"
+  ],
+  "author": "lythos-labs",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -14,6 +23,16 @@
   ],
   "dependencies": {
     "@iarna/toml": "^2.2.5",
+    "yaml": "^2.8.3",
     "zod": "^4.3.6"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lythos-labs/lythoskill.git",
+    "directory": "packages/lythoskill-deck"
+  },
+  "bugs": {
+    "url": "https://github.com/lythos-labs/lythoskill/issues"
+  },
+  "homepage": "https://github.com/lythos-labs/lythoskill/tree/main/packages/lythoskill-deck#readme"
 }

package/src/add.ts

@@ -0,0 +1,166 @@
+#!/usr/bin/env bun
+/**
+ * deck-add.ts — Skill acquisition command
+ *
+ * Downloads a skill to the cold pool, updates skill-deck.toml, and links.
+ * Supports multiple backends (git clone, skills.sh) without locking users
+ * into a single download method.
+ */
+
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, readFileSync, readdirSync } from 'node:fs'
+import { mkdtempSync } from 'node:fs'
+import { tmpdir, homedir } from 'node:os'
+import { join, basename, dirname, resolve } from 'node:path'
+import { execSync } from 'node:child_process'
+import { parse as parseToml, stringify as stringifyToml } from '@iarna/toml'
+import { findDeckToml, expandHome } from './link.js'
+
+interface ParsedLocator {
+  host: string
+  owner: string
+  repo: string
+  skill: string | null
+  raw: string
+}
+
+function parseLocator(input: string): ParsedLocator | null {
+  // Format: host.tld/owner/repo/skill  or  host.tld/owner/repo
+  //         owner/repo/skill           or  owner/repo  (shorthand for github.com)
+  const parts = input.split('/').filter(Boolean)
+  if (parts.length < 2) return null
+
+  const hasHost = parts[0].includes('.')
+
+  if (hasHost) {
+    if (parts.length < 3) return null
+    const host = parts[0]
+    const owner = parts[1]
+    const repo = parts[2]
+    const skill = parts.length > 3 ? parts.slice(3).join('/') : null
+    return { host, owner, repo, skill, raw: input }
+  }
+
+  const host = 'github.com'
+  const owner = parts[0]
+  const repo = parts[1]
+  const skill = parts.length > 2 ? parts.slice(2).join('/') : null
+  return { host, owner, repo, skill, raw: input }
+}
+
+function findSkillDir(repoPath: string, skill: string | null): string | null {
+  if (skill) {
+    const inSkills = join(repoPath, 'skills', skill)
+    if (existsSync(join(inSkills, 'SKILL.md'))) return inSkills
+    const direct = join(repoPath, skill)
+    if (existsSync(join(direct, 'SKILL.md'))) return direct
+    return null
+  }
+  if (existsSync(join(repoPath, 'SKILL.md'))) return repoPath
+  const skillsDir = join(repoPath, 'skills')
+  if (existsSync(skillsDir)) {
+    const entries = readdirSync(skillsDir, { withFileTypes: true })
+    const dirs = entries.filter(e => e.isDirectory())
+    if (dirs.length === 1) {
+      const candidate = join(skillsDir, dirs[0].name)
+      if (existsSync(join(candidate, 'SKILL.md'))) return candidate
+    }
+  }
+  return null
+}
+
+function resolvePath(p: string): string {
+  if (p.startsWith('~/')) return join(homedir(), p.slice(2))
+  return resolve(p)
+}
+
+export async function addSkill(locator: string, options: { via?: string; deck?: string; workdir?: string }) {
+  const workdir = options.workdir ? resolvePath(options.workdir) : process.cwd()
+  const deckPath = options.deck
+    ? resolvePath(options.deck)
+    : findDeckToml(workdir) || join(workdir, 'skill-deck.toml')
+
+  const parsed = parseLocator(locator)
+  if (!parsed) {
+    console.error(`❌ Invalid locator: ${locator}`)
+    console.error(`   Expected: github.com/owner/repo[/skill] or owner/repo[/skill]`)
+    process.exit(1)
+  }
+
+  const backend = options.via || 'git'
+
+  let coldPool = join(homedir(), '.agents', 'skill-repos')
+  if (existsSync(deckPath)) {
+    try {
+      const deckRaw = readFileSync(deckPath, 'utf-8')
+      const deck = parseToml(deckRaw) as any
+      coldPool = expandHome(deck.deck?.cold_pool || '~/.agents/skill-repos', workdir)
+    } catch { /* use default */ }
+  }
+
+  const targetDir = join(coldPool, parsed.host, parsed.owner, parsed.repo)
+
+  if (existsSync(targetDir)) {
+    console.error(`❌ Already exists in cold pool: ${targetDir}`)
+    console.error(`   To update: rm -rf ${targetDir} and re-run`)
+    process.exit(1)
+  }
+
+  const tmpDir = mkdtempSync(join(tmpdir(), 'lythoskill-deck-add-'))
+  const tmpRepo = join(tmpDir, 'repo')
+
+  try {
+    if (backend === 'skills.sh' || backend === 'vercel') {
+      const skillsShLocator = `${parsed.owner}/${parsed.repo}`
+      console.log(`📦 Downloading via skills.sh: ${skillsShLocator}`)
+      execSync(`npx skills add ${skillsShLocator} -g`, { cwd: tmpDir, stdio: 'inherit' })
+      console.error(`⚠️ skills.sh backend: manual cold-pool placement may be needed`)
+    } else {
+      const gitUrl = `https://${parsed.host}/${parsed.owner}/${parsed.repo}.git`
+      console.log(`📦 Cloning: ${gitUrl}`)
+      execSync(`git clone --depth 1 ${gitUrl} ${tmpRepo}`, { stdio: 'inherit' })
+    }
+
+    mkdirSync(dirname(targetDir), { recursive: true })
+    renameSync(tmpRepo, targetDir)
+
+    const skillDir = findSkillDir(targetDir, parsed.skill)
+    if (!skillDir) {
+      console.error(`❌ No SKILL.md found in downloaded repo`)
+      console.error(`   Checked: ${targetDir}`)
+      process.exit(1)
+    }
+
+    const skillName = parsed.skill ? basename(parsed.skill) : parsed.repo
+    console.log(`✅ Skill ready: ${skillName}`)
+    console.log(`   Location: ${skillDir}`)
+
+    if (existsSync(deckPath)) {
+      const deckRaw = readFileSync(deckPath, 'utf-8')
+      const deck = parseToml(deckRaw) as any
+      const toolSkills = deck.tool?.skills || []
+      if (!toolSkills.includes(skillName)) {
+        if (!deck.tool) deck.tool = {}
+        if (!deck.tool.skills) deck.tool.skills = []
+        deck.tool.skills.push(skillName)
+        writeFileSync(deckPath, stringifyToml(deck))
+        console.log(`📝 Added "${skillName}" to ${deckPath}`)
+      } else {
+        console.log(`📝 "${skillName}" already declared in ${deckPath}`)
+      }
+    } else {
+      const minimal = { deck: { max_cards: 10 }, tool: { skills: [skillName] } }
+      writeFileSync(deckPath, stringifyToml(minimal))
+      console.log(`📝 Created ${deckPath} with "${skillName}"`)
+    }
+
+    console.log('🔗 Running deck link...')
+    const { linkDeck } = await import('./link.js')
+    linkDeck(deckPath === join(workdir, 'skill-deck.toml') ? undefined : deckPath, workdir)
+
+  } catch (err) {
+    console.error(`❌ Failed to add skill: ${err}`)
+    process.exit(1)
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true })
+  }
+}

package/src/cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import { linkDeck } from './link.js'
 import { validateDeck } from './validate.js'
+import { addSkill } from './add.js'
 import { formatHelp } from './help.js'
 
 const HELP_CONFIG = {
@@ -8,19 +9,26 @@ const HELP_CONFIG = {
   description: 'Declarative skill deck governance — cold pool, working set, deny-by-default',
   commands: [
     { name: 'link', description: 'Sync working set with skill-deck.toml' },
+    { name: 'add', description: 'Download skill to cold pool and add to deck', args: '<locator>' },
     { name: 'validate', description: 'Validate deck configuration', args: '[deck.toml]' },
   ],
   options: [
-    { flag: '--deck <path>', description: 'Specify skill-deck.toml path' },
-    { flag: '--workdir <dir>', description: 'Specify working directory' },
+    { flag: '--deck <path>', description: 'Specify skill-deck.toml path (default: find upward from cwd)' },
+    { flag: '--workdir <dir>', description: 'Specify working directory (default: cwd)' },
+    { flag: '--via <backend>', description: 'Download backend: git (default) | skills.sh' },
   ],
 }
 
-const command = process.argv[2]
-const deckFlagIdx = process.argv.indexOf('--deck')
-const workdirFlagIdx = process.argv.indexOf('--workdir')
-const deckPath = deckFlagIdx >= 0 ? process.argv[deckFlagIdx + 1] : undefined
-const workdir = workdirFlagIdx >= 0 ? process.argv[workdirFlagIdx + 1] : undefined
+const args = process.argv.slice(2)
+const command = args[0]
+
+const deckFlagIdx = args.indexOf('--deck')
+const workdirFlagIdx = args.indexOf('--workdir')
+const viaFlagIdx = args.indexOf('--via')
+
+const deckPath = deckFlagIdx >= 0 ? args[deckFlagIdx + 1] : undefined
+const workdir = workdirFlagIdx >= 0 ? args[workdirFlagIdx + 1] : undefined
+const via = viaFlagIdx >= 0 ? args[viaFlagIdx + 1] : undefined
 
 switch (command) {
   case '--help':
@@ -30,6 +38,15 @@ switch (command) {
   case 'link':
     linkDeck(deckPath, workdir)
     break
+  case 'add': {
+    const locator = args[1]
+    if (!locator) {
+      console.error('❌ Missing locator. Usage: deck add <github.com/owner/repo[/skill]>')
+      process.exit(1)
+    }
+    await addSkill(locator, { via, deck: deckPath, workdir })
+    break
+  }
   case 'validate':
     validateDeck(deckPath, workdir)
     break

package/src/link.ts

@@ -8,6 +8,7 @@
  */
 
 import { parse as parseToml } from "@iarna/toml";
+import YAML from "yaml";
 import { createHash } from "crypto";
 import {
   existsSync, mkdirSync, readFileSync, readdirSync,
@@ -36,49 +37,17 @@ export function expandHome(p: string, base: string): string {
 function hashContent(content: string): string {
   return createHash("sha256").update(content).digest("hex");
 }
-
 // ── Front matter 提取 ───────────────────────────────────────
 
-function getFrontMatter(skillMdPath: string): string {
+function parseSkillFrontmatter(skillMdPath: string): Record<string, any> {
   try {
     const c = readFileSync(skillMdPath, "utf-8");
-    if (!c.startsWith("---")) return "";
-    const parts = c.split("---");
-    return parts.length >= 3 ? parts[1] : "";
-  } catch { return ""; }
-}
-
-function extractField(fm: string, field: string): string {
-  const m = fm.match(new RegExp(`^${field}:\\s*(.+)$`, "m"));
-  return m ? m[1].trim() : "";
+    const match = c.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+    if (!match) return {};
+    return YAML.parse(match[1]) || {};
+  } catch { return {}; }
 }
 
-function extractArrayField(fm: string, field: string): string[] {
-  const lines = fm.split("\n");
-  const results: string[] = [];
-  let collecting = false;
-  for (const line of lines) {
-    if (line.match(new RegExp(`^${field}:\\s*$`))) {
-      collecting = true;
-      continue;
-    }
-    if (line.match(new RegExp(`^${field}:\\s*\\[`))) {
-      const inline = line.match(/\[(.+)\]/);
-      if (inline) return inline[1].split(",").map(s => s.trim().replace(/^["']|["']$/g, ""));
-      collecting = true;
-      continue;
-    }
-    if (collecting) {
-      const item = line.match(/^\s+-\s+(.+)/);
-      if (item) {
-        results.push(item[1].trim().replace(/^["']|["']$/g, ""));
-      } else if (line.trim() !== "" && !line.match(/^\s*#/)) {
-        break;
-      }
-    }
-  }
-  return results;
-}
 
 // ── 冷池查找 ────────────────────────────────────────────────
 
@@ -253,9 +222,13 @@ for (const item of declared) {
 
   // 提取元数据
   const skillMdPath = join(item.sourcePath, "SKILL.md");
-  const fm = getFrontMatter(skillMdPath);
-  const niche = extractField(fm, "deck_niche");
-  const managedDirs = extractArrayField(fm, "deck_managed_dirs");
+  const fm = parseSkillFrontmatter(skillMdPath);
+  const niche = String(fm["deck_niche"] || "");
+  const managedDirs = Array.isArray(fm["deck_managed_dirs"])
+    ? fm["deck_managed_dirs"].map(String)
+    : fm["deck_managed_dirs"]
+      ? [String(fm["deck_managed_dirs"])]
+      : [];
   let contentHash: string | undefined;
   try {
     contentHash = hashContent(readFileSync(skillMdPath, "utf-8"));