@lythos/skill-deck 0.4.0 → 0.5.1

package/README.md

@@ -1,22 +1,97 @@
 # @lythos/skill-deck
 
-> Declarative skill deck governance for AI agents. Reconcile declared skills against your cold pool via symlinks — deny-by-default, max-cards budgeting, transient expiry.
+> Declarative skill deck governance. Reconcile declared skills against your cold pool via symlinks — deny-by-default, max-cards budgeting, transient expiry.
 
-## Why
+## For AI Agents
 
-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.
+This package exposes a **CLI**. Invoke via:
 
-`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.
+```bash
+bunx @lythos/skill-deck <command> [options]
+```
 
-## Install
+No installation required. `bunx` auto-downloads the package.
 
-```bash
-bun add -d @lythos/skill-deck
-# or use directly
-bunx @lythos/skill-deck <command>
+### skill-deck.toml (minimal)
+
+```toml
+[deck]
+max_cards = 10
+
+[tool]
+skills = ["lythoskill-deck"]
+```
+
+### 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
 ```
 
-## Quick Start
+### When to invoke
+
+| Situation | Command |
+|-----------|---------|
+| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck link` |
+| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck validate` |
+| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck add owner/repo` |
+| 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. |
+| `add` | `<locator> [--via <backend>] [--deck <path>]` | Download skill to cold pool and append to skill-deck.toml. |
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--deck <path>` | Path to skill-deck.toml | Find upward from cwd |
+| `--workdir <dir>` | Working directory | cwd |
+| `--via <backend>` | Download backend for `add`: `git` or `skills.sh` | `git` |
+
+### Safety guards
+
+`link` refuses to operate if `working_set` resolves to your home directory or root (`/`). It also only removes **symlinks** from the working set — real files or directories are skipped with a warning.
+
+### 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
 # 1. Create a skill-deck.toml
@@ -32,32 +107,28 @@ EOF
 bunx @lythos/skill-deck link
 ```
 
-## Commands
-
-```
-lythoskill-deck — Declarative skill deck governance — cold pool, working set, deny-by-default
-
-Usage: lythoskill-deck link | lythoskill-deck validate [deck.toml]
-
-Commands:
-  link                  Sync working set with skill-deck.toml
-  validate [deck.toml]  Validate deck configuration
-
-Options:
-  --deck <path>    Specify skill-deck.toml path
-  --workdir <dir>  Specify working directory
-```
-
-## Key Concepts
+### Key Concepts
 
 | 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. |
+| **`deck link`** | Reconciler. Makes the working set match the declaration. |
+| **Working Set** | Symlinks only. Default: `.claude/skills/` — where agents scan for skills. |
 | **deny-by-default** | Undeclared skills are physically absent from the working set. |
 
+### Agent skill scan locations
+
+Different agents look for skills in different directories. `skill-deck.toml` configures the working set to match your agent:
+
+| Agent | Default skills directory |
+|-------|--------------------------|
+| Claude Code | `.claude/skills/` |
+| Cursor | `.cursor/skills/` |
+| Generic / custom | Configure `working_set` in `skill-deck.toml` |
+
+> **If you are an agent**: verify where your platform scans for skills, then set `working_set` to that path before running `deck link`.
+
 ## Skill Documentation
 
 This package is the **Starter** layer (CLI implementation).  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/skill-deck",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
   "keywords": [
     "ai-agent",

package/src/add.ts

@@ -0,0 +1,181 @@
+#!/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)
+  }
+
+  if (!existsSync(coldPool)) {
+    console.log(`📁 Creating cold pool: ${coldPool}`)
+    mkdirSync(coldPool, { recursive: true })
+  }
+
+  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' })
+    } else {
+      const gitUrl = `https://${parsed.host}/${parsed.owner}/${parsed.repo}.git`
+      console.log(`📦 Cloning: ${gitUrl}`)
+      execSync(`git clone --depth 1 ${gitUrl} ${tmpRepo}`, { stdio: 'inherit' })
+    }
+
+    if (!existsSync(tmpRepo)) {
+      if (backend === 'skills.sh' || backend === 'vercel') {
+        console.error(`❌ skills.sh backend installs globally, not to cold pool.`)
+        console.error(`   Please manually place the skill at: ${targetDir}`)
+        console.error(`   Or use: deck add ${locator} --via git`)
+        process.exit(1)
+      }
+      console.error(`❌ Download failed: expected output not found at ${tmpRepo}`)
+      process.exit(1)
+    }
+
+    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

@@ -14,7 +14,7 @@ import {
   existsSync, mkdirSync, readFileSync, readdirSync,
   symlinkSync, lstatSync, rmSync, writeFileSync,
 } from "fs";
-import { resolve, dirname, join } from "path";
+import { resolve, dirname, join, basename, relative } from "path";
 import { homedir } from "os";
 import {
   SkillDeckLockSchema,
@@ -152,7 +152,7 @@ for (const section of ["innate", "tool", "combo"] as const) {
     if (!name || typeof name !== "string") continue;
     const src = findSource(name, COLD_POOL, PROJECT_DIR);
     if (!src) {
-      errors.push(`skill 未找到: ${name}`);
+      errors.push(`Skill not found: ${name}`);
       continue;
     }
     declared.push({ name, type: section, sourcePath: src });
@@ -165,7 +165,7 @@ for (const [key, value] of Object.entries(deck.transient || {})) {
   if (!t?.path) continue;
   const src = resolve(PROJECT_DIR, t.path);
   if (!existsSync(src)) {
-    errors.push(`transient 路径不存在: ${key} → ${src}`);
+    errors.push(`Transient path does not exist: ${key} → ${src}`);
     continue;
   }
   declared.push({ name: key, type: "transient", sourcePath: src, expires: t.expires });
@@ -179,23 +179,54 @@ if (errors.length > 0) {
 // ── 预算检查（硬约束，链接前检查）──────────────────────────
 
 if (declared.length > MAX_CARDS) {
-  console.error(`❌ 超出预算: 声明 ${declared.length} 个，上限 ${MAX_CARDS}`);
-  console.error(`   减少 skill-deck.toml 中的声明，或调整 max_cards`);
+  console.error(`❌ Budget exceeded: declared ${declared.length}, max ${MAX_CARDS}`);
+  console.error(`   Reduce declarations in skill-deck.toml or increase max_cards`);
   process.exit(1);
 }
 
+// ── 工作目录安全 guard ──────────────────────────────────────
+
+const resolvedWorkingSet = resolve(WORKING_SET);
+const resolvedHome = resolve(homedir());
+const resolvedCwd = resolve(process.cwd());
+const resolvedColdPool = resolve(COLD_POOL);
+
+if (resolvedWorkingSet === resolvedHome || resolvedWorkingSet === "/") {
+  console.error(`❌ Refusing operation: working_set resolves to home or root directory (${resolvedWorkingSet})`);
+  console.error(`   Check working_set in skill-deck.toml`);
+  process.exit(1);
+}
+
+const relWs = relative(resolvedColdPool, resolvedWorkingSet);
+if (
+  resolvedWorkingSet.startsWith(resolvedColdPool + "/") &&
+  !relWs.split("/").some(p => p.startsWith("."))
+) {
+  console.warn(`⚠️  working_set is inside cold_pool and not hidden — may be picked up by cold-pool scans`);
+  console.warn(`   working_set: ${resolvedWorkingSet}`);
+  console.warn(`   cold_pool:   ${resolvedColdPool}`);
+}
+
 // ── 收束 working set ────────────────────────────────────────
 
 mkdirSync(WORKING_SET, { recursive: true });
 
-// 清理未声明的条目
+// 清理未声明的条目（只删 symlink，防呆）
 const declaredNames = new Set(declared.map(d => d.name.split("/")[0]));
 try {
   for (const entry of readdirSync(WORKING_SET)) {
     if (entry.startsWith("_")) continue;
     if (!declaredNames.has(entry)) {
-      rmSync(join(WORKING_SET, entry), { recursive: true, force: true });
-      console.log(`  🗑️  移除: ${entry}`);
+      const entryPath = join(WORKING_SET, entry);
+      try {
+        const st = lstatSync(entryPath);
+        if (!st.isSymbolicLink()) {
+          console.warn(`⚠️  Skipping non-symlink entry: ${entry}`);
+          continue;
+        }
+      } catch { continue; }
+      rmSync(entryPath, { recursive: true, force: true });
+      console.log(`  🗑️  Removed: ${entry}`);
     }
   }
 } catch {}
@@ -216,7 +247,7 @@ for (const item of declared) {
     mkdirSync(dirname(dest), { recursive: true });
     symlinkSync(item.sourcePath, dest);
   } catch (err: any) {
-    console.error(`❌ 链接失败: ${item.name}: ${err.message}`);
+    console.error(`❌ Link failed: ${item.name}: ${err.message}`);
     continue;
   }
 
@@ -260,9 +291,9 @@ for (const s of linkedSkills) {
   const days = Math.ceil((exp - now) / 86400000);
   transientWarnings.push({ name: s.name, expires: s.expires, days_remaining: days });
   if (days <= 0) {
-    console.warn(`⚠️  过期: ${s.name}（到期 ${s.expires}）— 评估是否仍需要`);
+    console.warn(`⚠️  Expired: ${s.name} (expires ${s.expires}) — evaluate if still needed`);
   } else if (days <= 14) {
-    console.warn(`⏰ 即将过期: ${s.name}（剩余 ${days} 天）`);
+    console.warn(`⏰ Expiring soon: ${s.name} (${days} days remaining)`);
   }
 }
 
@@ -282,7 +313,7 @@ const dirOverlaps: { dir: string; skills: string[] }[] = [];
 for (const [dir, owners] of dirOwners) {
   if (owners.length > 1) {
     dirOverlaps.push({ dir, skills: owners });
-    console.warn(`⚠️  目录重叠: ${dir} ← ${owners.join(", ")}`);
+    console.warn(`⚠️  Directory overlap: ${dir} ← ${owners.join(", ")}`);
   }
 }
 
@@ -297,7 +328,7 @@ for (let i = 0; i < allDirs.length; i++) {
       const cross = parentOwners.filter(o => !childOwners.includes(o));
       if (cross.length > 0) {
         const msg = `${allDirs[i]} (${parentOwners.join(",")}) 包含 ${allDirs[j]} (${childOwners.join(",")})`;
-        console.warn(`⚠️  目录包含关系: ${msg}`);
+        console.warn(`⚠️  Directory containment: ${msg}`);
         dirOverlaps.push({ dir: `${allDirs[i]} ⊃ ${allDirs[j]}`, skills: [...new Set([...parentOwners, ...childOwners])] });
       }
     }
@@ -326,7 +357,7 @@ const lock: SkillDeckLock = {
 
 const parsed = SkillDeckLockSchema.safeParse(lock);
 if (!parsed.success) {
-  console.error("❌ Lock schema 校验失败:", JSON.stringify(parsed.error.format(), null, 2));
+  console.error("❌ Lock schema validation failed:", JSON.stringify(parsed.error.format(), null, 2));
   process.exit(1);
 }
 
@@ -336,10 +367,10 @@ writeFileSync(LOCK_PATH, JSON.stringify(parsed.data, null, 2) + "\n");
 // ── 报告 ────────────────────────────────────────────────────
 
 console.log("");
-console.log(`✅ 同步完成: ${linkedSkills.length}/${MAX_CARDS} skill`);
+console.log(`✅ Sync complete: ${linkedSkills.length}/${MAX_CARDS} skills`);
 console.log(`   lock: ${LOCK_PATH}`);
 if (dirOverlaps.length > 0) {
-  console.log(`   ⚠️  ${dirOverlaps.length} 个目录重叠（详见上方警告）`);
+  console.log(`   ⚠️  ${dirOverlaps.length} directory overlap(s) (see warnings above)`);
 }
 }