@lythos/skill-deck 0.5.1 → 0.6.0

package/README.md

@@ -129,21 +129,27 @@ Different agents look for skills in different directories. `skill-deck.toml` con
 
 > **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).  
-The agent-visible **Skill** layer documentation is here:  
-[packages/lythoskill-deck/skill/SKILL.md](../../packages/lythoskill-deck/skill/SKILL.md)
-
-## Architecture
-
-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
-```
+### 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.1",
+  "version": "0.6.0",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
   "keywords": [
     "ai-agent",

package/src/link.ts

@@ -172,8 +172,36 @@ for (const [key, value] of Object.entries(deck.transient || {})) {
 }
 
 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`);
+  }
 }
 
 // ── 预算检查（硬约束，链接前检查）──────────────────────────
@@ -222,6 +250,10 @@ 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; }