@lythos/skill-deck 0.5.0 → 0.6.0

package/README.md

@@ -49,8 +49,9 @@ skills = ["report-generation-combo"]
 
 | Situation | Command |
 |-----------|---------|
-| Sync `.claude/skills/` with `skill-deck.toml` | `bunx @lythos/skill-deck link` |
+| 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
@@ -59,6 +60,7 @@ skills = ["report-generation-combo"]
 |---------|------|-------------|
 | `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
 
@@ -66,6 +68,11 @@ skills = ["report-generation-combo"]
 |------|-------------|---------|
 | `--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
 
@@ -106,25 +113,43 @@ bunx @lythos/skill-deck link
 |---------|-----------|
 | **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. |
 
-## Skill Documentation
+### Agent skill scan locations
 
-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)
+Different agents look for skills in different directories. `skill-deck.toml` configures the working set to match your agent:
 
-## Architecture
+| Agent | Default skills directory |
+|-------|--------------------------|
+| Claude Code | `.claude/skills/` |
+| Cursor | `.cursor/skills/` |
+| Generic / custom | Configure `working_set` in `skill-deck.toml` |
 
-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).
+> **If you are an agent**: verify where your platform scans for skills, then set `working_set` to that path before running `deck link`.
 
-```
-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
-```
+### Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `❌ Skill not found: <name>` | Skill declared in deck but not in cold pool | `bunx @lythos/skill-deck add github.com/owner/repo/skill` or clone manually into cold pool |
+| `link` skips entries with warnings | Real files/directories exist in working set (not symlinks) | Delete the real directories in `working_set` and re-run `link`. Never create directories manually there |
+| `link` refuses with "budget exceeded" | Declared skills > `max_cards` | Increase `max_cards` in `skill-deck.toml` or remove unused skills |
+| `link` refuses with "unsafe working_set" | `working_set` resolves to `~` or `/` | Check `skill-deck.toml` has correct relative path (e.g. `.claude/skills/`) |
+| Agent doesn't see skills after `link` | `working_set` path doesn't match agent's scan location | Claude Code: `.claude/skills/`; Cursor: `.cursor/skills/`; Kimi: check your platform docs. Set `working_set` correctly |
+| Broken symlinks in working set | Skill moved or deleted from cold pool | Re-run `link` — it recreates symlinks automatically |
+| `deck add` fails with 404 | Locator format wrong or repo doesn't exist | Format: `github.com/owner/repo/skill-name` (path to skill directory inside repo) |
+| `skill-deck.toml not found` | Running `link` outside project tree | Run from project root, or use `--deck ./path/to/skill-deck.toml` |
+
+## More Documentation
+
+- **Skill layer** (agent-facing instructions):  
+  [`packages/lythoskill-deck/skill/SKILL.md`](https://github.com/lythos-labs/lythoskill/blob/main/packages/lythoskill-deck/skill/SKILL.md)
+- **Full project README** (ecosystem overview, cold pool setup):  
+  [`README.md`](https://github.com/lythos-labs/lythoskill#readme)
+- **Architecture** (thin-skill pattern, three-layer separation):  
+  [`AGENTS.md`](https://github.com/lythos-labs/lythoskill/blob/main/AGENTS.md)
 
 ## License
 

package/package.json

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

package/src/add.ts

@@ -105,6 +105,11 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
     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')
 
@@ -113,13 +118,23 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
       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' })
     }
 
+    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)
 

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,37 +165,100 @@ 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 });
 }
 
 if (errors.length > 0) {
-  for (const e of errors) console.error(`❌ ${e}`);
+  for (const e of errors) {
+    console.error(`❌ ${e}`);
+    // 智能引导：如果 skill 在工作集中以真实目录存在，提示移到冷池
+    const match = e.match(/^Skill not found: (.+)$/);
+    if (match) {
+      const skillName = match[1];
+      const wsEntry = join(WORKING_SET, skillName);
+      if (existsSync(wsEntry)) {
+        const st = lstatSync(wsEntry);
+        if (st.isDirectory() && !st.isSymbolicLink()) {
+          console.error(`   → Found a real directory at ${relative(PROJECT_DIR, wsEntry)}`);
+          const cpRel = relative(PROJECT_DIR, COLD_POOL);
+          const cpHint = cpRel === "" ? `skills/${skillName}` : `${cpRel}/${skillName}`;
+          console.error(`     Move it to your cold pool (${cpHint}) and retry.`);
+        }
+      }
+    }
+  }
   // 继续执行已找到的 skill，不因个别缺失中断全部
+
+  // 引导：如果 cold pool 为空，给出更明确的指引
+  const hasSkills = existsSync(COLD_POOL) && readdirSync(COLD_POOL).filter(e => !e.startsWith('.')).length > 0;
+  if (!hasSkills) {
+    console.error(`\n💡 Cold pool is empty. To add skills:`);
+    console.error(`   bunx @lythos/skill-deck add github.com/owner/repo/skill`);
+    console.error(`   # or manually: git clone <repo> ~/.agents/skill-repos/github.com/owner/repo`);
+  } else {
+    console.error(`\n💡 To install missing skills:`);
+    console.error(`   bunx @lythos/skill-deck add github.com/owner/repo/skill`);
+  }
 }
 
 // ── 预算检查（硬约束，链接前检查）──────────────────────────
 
 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}`);
+          console.warn(`   → ${entry} is a real directory, not a symlink. Deck only manages symlinks.`);
+          const cpRel2 = relative(PROJECT_DIR, COLD_POOL);
+          const cpHint2 = cpRel2 === "" ? `skills/${entry}` : `${cpRel2}/${entry}`;
+          console.warn(`     Move it to your cold pool (${cpHint2}) and run link again.`);
+          continue;
+        }
+      } catch { continue; }
+      rmSync(entryPath, { recursive: true, force: true });
+      console.log(`  🗑️  Removed: ${entry}`);
     }
   }
 } catch {}
@@ -216,7 +279,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 +323,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 +345,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 +360,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 +389,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 +399,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)`);
 }
 }