@lythos/skill-deck 0.7.2 → 0.9.1

package/README.md

@@ -1,5 +1,7 @@
 # @lythos/skill-deck
 
+![Coverage](https://img.shields.io/badge/coverage-82%25-brightgreen)
+
 > Declarative skill deck governance. Reconcile declared skills against your cold pool via symlinks — deny-by-default, max-cards budgeting, transient expiry.
 
 ## For AI Agents
@@ -18,8 +20,8 @@ No installation required. `bunx` auto-downloads the package.
 [deck]
 max_cards = 10
 
-[tool]
-skills = ["github.com/lythos-labs/lythoskill/skills/lythoskill-deck"]
+[tool.skills.lythoskill-deck]
+path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
 ```
 
 ### skill-deck.toml (full reference)
@@ -30,22 +32,21 @@ 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 = ["github.com/lythos-labs/lythoskill/skills/lythoskill-deck"]
+[innate.skills.lythoskill-deck]     # Always-loaded skills
+path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
+
+[tool.skills.tdd]                   # Auto-triggered skills
+path = "github.com/mattpocock/skills/skills/engineering/tdd"
 
-[tool]                      # Auto-triggered skills
-skills = [
-  "github.com/mattpocock/skills/skills/engineering/tdd",
-  "github.com/garrytan/gstack",
-]
+[tool.skills.gstack]
+path = "github.com/garrytan/gstack"
 
-[combo]                     # Multi-skill bundles
-skills = ["github.com/anthropics/skills/skills/pdf"]
+[combo.skills.pdf]                  # Multi-skill bundles
+path = "github.com/anthropics/skills/skills/pdf"
 
-[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
+[transient.handoff]                 # Temporary skills with expiry
+path = "./skills/handoff" # Local path (not cold pool)
+expires = "2026-05-01"    # ISO date; warns at ≤14 days
 ```
 
 ### When to invoke
@@ -55,7 +56,10 @@ skills = ["github.com/anthropics/skills/skills/pdf"]
 | 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` |
-| Pull latest versions of declared skills | `bunx @lythos/skill-deck update` |
+| Pull latest versions of declared skills | `bunx @lythos/skill-deck refresh` |
+| Refresh a single skill by alias | `bunx @lythos/skill-deck refresh tdd` |
+| Remove a skill from deck and working set | `bunx @lythos/skill-deck remove tdd` |
+| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck prune` |
 | Use a custom deck file or working dir | `bunx @lythos/skill-deck link --deck ./my-deck.toml --workdir /path/to/project` |
 
 ### Commands
@@ -64,8 +68,10 @@ skills = ["github.com/anthropics/skills/skills/pdf"]
 |---------|------|-------------|
 | `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. |
-| `update` | `[--deck <path>]` | Pull latest versions of declared skills from upstream git repos. |
+| `add` | `<locator> [--via <backend>] [--as <alias>] [--type <type>] [--deck <path>]` | Download skill to cold pool and append to skill-deck.toml. |
+| `refresh` | `[<fq|alias>] [--deck <path>]` | Pull latest versions of declared skills from upstream git repos. Pass a name to refresh one skill. |
+| `remove` | `<fq|alias> [--deck <path>]` | Remove skill from deck.toml and working set. Cold pool untouched. |
+| `prune` | `[--yes] [--deck <path>]` | GC cold pool repos no longer referenced. Interactive confirm (skip with `--yes`). |
 
 ### Options
 
@@ -74,6 +80,8 @@ skills = ["github.com/anthropics/skills/skills/pdf"]
 | `--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` |
+| `--as <alias>` | Explicit alias for the skill (default: basename of path) | — |
+| `--type <type>` | Target section for `add`: `innate`, `tool`, or `combo` | `tool` |
 
 ### Safety guards
 
@@ -104,8 +112,8 @@ cat > skill-deck.toml << 'EOF'
 [deck]
 max_cards = 10
 
-[tool]
-skills = ["github.com/lythos-labs/lythoskill/skills/lythoskill-deck"]
+[tool.skills.lythoskill-deck]
+path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/
@@ -140,7 +148,8 @@ Different agents look for skills in different directories. `skill-deck.toml` con
 |---------|-------|-----|
 | `❌ 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 |
-| `update` reports "Not a git repository" | Skill was copied (not cloned) into cold pool | Re-clone with `git clone` or use `deck add` which clones by default |
+| `refresh` reports "Not a git repository" | Skill was copied (not cloned) into cold pool | Re-clone with `git clone` or use `deck add` which clones by default |
+| `deck update` prints deprecation warning | `update` was renamed to `refresh` in v0.8+ | Use `deck refresh` instead |
 | `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 |

package/package.json

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

package/src/COVERAGE-GAPS.md

@@ -0,0 +1,117 @@
+# Deck Package Coverage Gaps
+
+> Generated from `bun test --coverage packages/lythoskill-deck/src/*.test.ts`
+> Lines: 82.35% | Funcs: 73.81% | Date: 2026-05-04
+
+## 策略声明
+
+以下缺口是**故意保留**的。覆盖这些分支的意图已经看到，处理方式不是"为覆盖率改代码"，而是：
+
+1. **提取行为后单测** — 如果某段逻辑值得验证，把它提取为纯函数，单独写 test
+2. **直接说明不覆盖** — 如果分支是纯边界防护（`catch {}`、交互式确认、外部依赖），写明原因即可
+3. **拒绝为覆盖率改写代码** — 不为了触发分支而拆散可读性高的连续逻辑
+
+具体不追的类别：
+- `catch {}` silent ignore（fs 边界错误，测了也是 mock，无业务意义）
+- 需要 >1GB 文件才能触发的分支（formatSize GB）
+- 依赖外部 network 的分支（git clone 真实失败、skills.sh backend）
+- 交互式 CLI 分支（prune confirm()）
+- 仅为凑分支覆盖率而进行的微重构（降低可读性）
+
+---
+
+## add.ts — 62.37% lines
+
+| 行 | 代码 | 未覆盖原因 | 是否追 |
+|----|------|-----------|--------|
+| 44, 46–50 | `deckPath` resolve + `findDeckToml` 失败 | CLI 路径解析，可用 spawnSync 追但成本高 | ⬜ 低优先级 |
+| 55–59 | cold pool mkdir | 正常路径已覆盖，异常分支为 `catch {}` | ❌ 不追 |
+| 62–71 | `targetDir` exists 错误 | 需构造 cold pool 冲突，有意义但成本中等 | ⬜ 低优先级 |
+| 87–89 | `skills.sh` / `vercel` backend | 依赖外部 `npx skills` 命令，无 mock 价值 | ❌ 不追 |
+| 106–108 | auto-migrate string-array → dict | 有意义，但需 mock `git clone` 全流程 | ⬜ 低优先级 |
+| 123–124, 127–131 | alias resolve / `nameParts.length` | shorthand path 分支，有意义 | ⬜ 低优先级 |
+| 136–141 | invalid type rejection | **已覆盖** (C9) | ✅ |
+| 143–154 | git clone 成功后的 `findSkillDir` | 正常路径已覆盖 | ✅ |
+| 163–164 | `--as` alias | 正常路径已覆盖 | ✅ |
+| 172–174, 182–183 | error handling (catch) | `catch {}` 无意义 | ❌ 不追 |
+| 206, 210 | skills.sh 路径 | 外部依赖 | ❌ 不追 |
+| 221–227 | `writeFileSync` / `linkDeck` | 正常路径已覆盖 | ✅ |
+| 235–240 | catch final error | `catch {}` | ❌ 不追 |
+
+## link.ts — 60.71% lines
+
+link.ts 是 deck 包最大文件（~540 行）， uncovered 行最多。主要缺口：
+
+| 行 | 代码 | 未覆盖原因 | 是否追 |
+|----|------|-----------|--------|
+| 103–111 | `parseSkillFrontmatter` 异常（SKILL.md 不存在/解析失败） | 有意义，需构造无 SKILL.md 的 fixture | ⬜ 低优先级 |
+| 116, 119–123 | `calculateDirSize` 异常 / `readdirSync` 失败 | `catch {}` | ❌ 不追 |
+| 131–142 | backup 逻辑（nonSymlink > 100MB tar） | 需构造大文件或 mock `tar`，成本高 | ❌ 不追 |
+| 146–147 | backup 路径构造 | 同上 | ❌ 不追 |
+| 162–171 | transient 过期警告（`days <= 14` / `days <= 0`） | 有意义，需调系统时间或 mock Date | ⬜ 低优先级 |
+| 180 | managed_dirs 重叠检测 | 有意义，需构造父子目录冲突 | ⬜ 低优先级 |
+| 206–211, 218–225 | `readdirSync` / `symlinkSync` 异常 | `catch {}` | ❌ 不追 |
+| 237–239, 244–245 | 各种路径 resolve | 边界情况 | ❌ 不追 |
+| 247–261 | `findSource` 多种匹配策略 | 部分已覆盖，剩余为罕见 fallback | ⬜ 低优先级 |
+| 265–278 | budget exceeded 详细报告 | 正常路径已覆盖 | ✅ |
+| 285–287, 298–300, 307–310 | 各种 `existsSync` / `lstatSync` 边界 | `catch {}` | ❌ 不追 |
+| 326 | `content_hash` 计算 | 正常路径已覆盖 | ✅ |
+| 334–372 | lock 文件 schema 校验 | 正常路径已覆盖 | ✅ |
+| 407–408 | `readlinkSync` 异常 | `catch {}` | ❌ 不追 |
+| 454–461 | `parseDeck` fallback | 正常路径已覆盖 | ✅ |
+| 479–480, 488–490, 492–498 | `readdirSync` / `rmSync` 边界 | `catch {}` | ❌ 不追 |
+| 524–525, 537 | 各种 cleanup / 路径 | 边界 | ❌ 不追 |
+
+## parse-deck.ts — 92.45% lines
+
+| 行 | 代码 | 未覆盖原因 | 是否追 |
+|----|------|-----------|--------|
+| 47–50 | legacy string-array `continue`（空 name） | 有意义但 trivial | ⬜ 低优先级 |
+
+## prune.ts — 80.43% lines
+
+| 行 | 代码 | 未覆盖原因 | 是否追 |
+|----|------|-----------|--------|
+| 25–27 | `formatSize` GB 分支 | 需 >1GB 文件 | ❌ 不追 |
+| 74 | `calculateDirSize` catch | `catch {}` | ❌ 不追 |
+| 81–87 | `scanColdPoolRepos` catch | `catch {}` | ❌ 不追 |
+| 98–100 | empty cold pool | **已覆盖** (C17) | ✅ |
+| 118–122 | all-referenced no-op | **已覆盖** (C16) | ✅ |
+| 129–130 | failed > 0 exit(1) | 需构造删除失败（权限不足） | ❌ 不追 |
+| 167 | formatSize MB 分支 | 正常路径已覆盖 | ✅ |
+| 172–173 | 删除失败 catch | `catch {}` | ❌ 不追 |
+| 185–186 | formatSize 边界 | 正常路径已覆盖 | ✅ |
+
+## refresh.ts — 88.97% lines
+
+| 行 | 代码 | 未覆盖原因 | 是否追 |
+|----|------|-----------|--------|
+| 43, 49 | deck 不存在 / `findDeckToml` 失败 | CLI 路径解析 | ⬜ 低优先级 |
+| 70–71 | localhost skip | **已覆盖** (C15) | ✅ |
+| 83–85 | not-git | **已覆盖** (C16) | ✅ |
+| 101 | `result.error`（findSource 失败） | 有意义 | ⬜ 低优先级 |
+| 109–110 | `gitRoot` null 后的 skip | **已覆盖** (C16) | ✅ |
+| 125 | `pullResult.status === "failed"` | 需 mock `git pull` 返回错误 | ⬜ 低优先级 |
+| 148–150 | `updated` / `upToDate` / `failed` 计数 | **已覆盖** (C12-C14) | ✅ |
+| 199 | `failed > 0` exit(1) | 需构造 failed 状态 | ⬜ 低优先级 |
+
+## remove.ts — 91.53% lines
+
+| 行 | 代码 | 未覆盖原因 | 是否追 |
+|----|------|-----------|--------|
+| 22–24 | deck 不存在 error | CLI 路径解析 | ⬜ 低优先级 |
+| 44 | legacy string-array filter | **已覆盖** (C11.b) | ✅ |
+
+## schema.ts — 100.00%
+
+全部覆盖 ✅
+
+---
+
+## 如果未来要推到 90%+
+
+优先级排序：
+1. **link.ts `parseSkillFrontmatter` 异常** — 有业务意义（broken SKILL.md），中等成本
+2. **link.ts transient 过期警告** — 有业务意义，需 mock Date
+3. **add.ts auto-migrate** — 有业务意义，需 mock git clone
+4. **link.ts managed_dirs 重叠** — 有业务意义，需构造目录冲突

package/src/add.test.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env bun
+/**
+ * add.test.ts — unit tests for add.ts
+ *
+ * Run: bun test packages/lythoskill-deck/src/add.test.ts
+ */
+
+import { describe, it, expect, afterEach, spyOn, mock } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync, cpSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import * as childProcess from 'node:child_process'
+
+// Control homedir() return value for tests that need default cold_pool under tmpdir
+let mockHomeDir = '/tmp'
+mock.module('node:os', () => ({
+  homedir: () => mockHomeDir,
+}))
+
+let cleanup: string[] = []
+let execSpy: ReturnType<typeof spyOn> | null = null
+
+afterEach(() => {
+  if (execSpy) {
+    execSpy.mockRestore()
+    execSpy = null
+  }
+  for (const dir of cleanup) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+  cleanup = []
+})
+
+function makeTmp(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'deck-add-'))
+  cleanup.push(dir)
+  return dir
+}
+
+function mockGitClone(fixturePath: string) {
+  const originalExec = childProcess.execFileSync
+  execSpy = spyOn(childProcess, 'execFileSync').mockImplementation(((cmd: string, args: string[], options?: any) => {
+    if (cmd === 'git' && args[0] === 'clone') {
+      const dest = args[args.length - 1]
+      cpSync(fixturePath, dest, { recursive: true })
+      return Buffer.from('')
+    }
+    return originalExec(cmd, args, options)
+  }) as any)
+}
+
+describe('addSkill', () => {
+  it('C6: add to empty project creates deck.toml and cold pool', async () => {
+    const projectDir = makeTmp()
+    mockHomeDir = projectDir
+
+    const fixtureDir = makeTmp()
+    writeFileSync(join(fixtureDir, 'SKILL.md'), '---\nname: test-skill\n---\n')
+
+    mockGitClone(fixtureDir)
+
+    // Dynamic import so add.ts picks up the mocked homedir()
+    const { addSkill } = await import('./add.ts')
+
+    await addSkill('github.com/owner/repo', { workdir: projectDir })
+
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    expect(existsSync(deckPath)).toBe(true)
+
+    const deckContent = readFileSync(deckPath, 'utf-8')
+    expect(deckContent).toContain('[tool.skills.repo]')
+    expect(deckContent).toContain('path = "github.com/owner/repo"')
+
+    const coldPoolDir = join(projectDir, '.agents', 'skill-repos', 'github.com', 'owner', 'repo')
+    expect(existsSync(coldPoolDir)).toBe(true)
+    expect(existsSync(join(coldPoolDir, 'SKILL.md'))).toBe(true)
+  })
+
+  it('C7: add to existing deck appends entry', async () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+    mkdirSync(coldPool, { recursive: true })
+
+    // Pre-place skill-a in cold pool
+    const skillADir = join(coldPool, 'github.com', 'owner', 'repo-a')
+    mkdirSync(skillADir, { recursive: true })
+    writeFileSync(join(skillADir, 'SKILL.md'), '---\nname: skill-a\n---\n')
+
+    // Create deck.toml with skill-a
+    const deckContent = `[deck]\nmax_cards = 10\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.skill-a]\npath = "github.com/owner/repo-a"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    // Fixture for skill-b
+    const fixtureDir = makeTmp()
+    writeFileSync(join(fixtureDir, 'SKILL.md'), '---\nname: skill-b\n---\n')
+
+    mockGitClone(fixtureDir)
+
+    const { addSkill } = await import('./add.ts')
+    await addSkill('github.com/owner/repo-b', { workdir: projectDir, deck: deckPath })
+
+    const newContent = readFileSync(deckPath, 'utf-8')
+    expect(newContent).toContain('[tool.skills.skill-a]')
+    expect(newContent).toContain('path = "github.com/owner/repo-a"')
+    expect(newContent).toContain('[tool.skills.repo-b]')
+    expect(newContent).toContain('path = "github.com/owner/repo-b"')
+  })
+
+  it('C8: alias collision rejects', async () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+    mkdirSync(coldPool, { recursive: true })
+
+    const deckContent = `[deck]\nmax_cards = 10\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.foo]\npath = "github.com/owner/repo-a"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    const fixtureDir = makeTmp()
+    writeFileSync(join(fixtureDir, 'SKILL.md'), '---\nname: skill-b\n---\n')
+
+    mockGitClone(fixtureDir)
+
+    const errors: string[] = []
+    const errorSpy = spyOn(console, 'error').mockImplementation((msg: string) => {
+      errors.push(String(msg))
+    })
+
+    const originalExit = process.exit
+    let exitCode: number | undefined
+    process.exit = ((code?: number) => {
+      exitCode = code ?? 0
+      throw new Error(`EXIT:${code}`)
+    }) as typeof process.exit
+
+    try {
+      const { addSkill } = await import('./add.ts')
+      await addSkill('github.com/owner/repo-b', { workdir: projectDir, deck: deckPath, as: 'foo' })
+      expect(false).toBe(true) // should not reach here
+    } catch (err: any) {
+      expect(exitCode).toBe(1)
+      expect(errors.some(e => e.includes('Alias "foo" already exists'))).toBe(true)
+    } finally {
+      process.exit = originalExit
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('C9: invalid skill type rejects', async () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+    mkdirSync(coldPool, { recursive: true })
+
+    const fixtureDir = makeTmp()
+    writeFileSync(join(fixtureDir, 'SKILL.md'), '---\nname: skill\n---\n')
+
+    const originalExec = childProcess.execFileSync
+    const execSpy = spyOn(childProcess, 'execFileSync').mockImplementation(((cmd: string, args: string[], options?: any) => {
+      if (cmd === 'git' && args[0] === 'clone') {
+        const dest = args[args.length - 1]
+        cpSync(fixtureDir, dest, { recursive: true })
+        return Buffer.from('')
+      }
+      return originalExec(cmd, args, options)
+    }) as any)
+
+    const errors: string[] = []
+    const errorSpy = spyOn(console, 'error').mockImplementation((msg: string) => {
+      errors.push(String(msg))
+    })
+
+    const originalExit = process.exit
+    let exitCode: number | undefined
+    process.exit = ((code?: number) => {
+      exitCode = code ?? 0
+      throw new Error(`EXIT:${code}`)
+    }) as typeof process.exit
+
+    try {
+      const { addSkill } = await import('./add.ts')
+      await addSkill('github.com/owner/repo', { deck: join(projectDir, 'skill-deck.toml'), workdir: projectDir, type: 'invalid' })
+      expect(false).toBe(true)
+    } catch (err: any) {
+      expect(exitCode).toBe(1)
+      expect(errors.some(e => e.includes('Invalid type'))).toBe(true)
+    } finally {
+      process.exit = originalExit
+      errorSpy.mockRestore()
+      execSpy.mockRestore()
+    }
+  })
+})

package/src/add.ts

@@ -11,9 +11,10 @@ import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, readFileSync,
 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 { execFileSync } from 'node:child_process'
 import { parse as parseToml, stringify as stringifyToml } from '@iarna/toml'
 import { findDeckToml, expandHome } from './link.js'
+import { parseDeck } from './parse-deck.js'
 
 const CLAUDE_SKILLS_DIR = join(homedir(), '.claude', 'skills')
 
@@ -75,7 +76,7 @@ function resolvePath(p: string): string {
   return resolve(p)
 }
 
-export async function addSkill(locator: string, options: { via?: string; deck?: string; workdir?: string }) {
+export async function addSkill(locator: string, options: { via?: string; deck?: string; workdir?: string; as?: string; type?: string }) {
   const workdir = options.workdir ? resolvePath(options.workdir) : process.cwd()
   const deckPath = options.deck
     ? resolvePath(options.deck)
@@ -129,7 +130,7 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
             .map(e => e.name))
         : new Set<string>()
 
-      execSync(`npx skills add ${skillsShLocator} -g`, { cwd: tmpDir, stdio: 'inherit' })
+      execFileSync('npx', ['skills', 'add', skillsShLocator, '-g'], { cwd: tmpDir, stdio: 'inherit' })
 
       // Detect the newly installed directory
       const afterDirs = existsSync(CLAUDE_SKILLS_DIR)
@@ -154,7 +155,7 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
     } else {
       const gitUrl = `https://${parsed.host}/${parsed.owner}/${parsed.repo}.git`
       console.log(`📦 Cloning: ${gitUrl}`)
-      execSync(`git clone --depth 1 ${gitUrl} ${tmpRepo}`, { stdio: 'inherit' })
+      execFileSync('git', ['clone', '--depth', '1', gitUrl, tmpRepo], { stdio: 'inherit' })
       skillSourceDir = tmpRepo
     }
 
@@ -174,31 +175,84 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
     }
 
     const skillName = parsed.skill ? basename(parsed.skill) : parsed.repo
-    console.log(`✅ Skill ready: ${skillName}`)
+    const alias = options.as || skillName
+    const skillType = (options.type || 'tool').toLowerCase()
+
+    if (!['innate', 'tool', 'combo'].includes(skillType)) {
+      console.error(`❌ Invalid type: ${skillType}. Must be innate, tool, or combo.`)
+      process.exit(1)
+    }
+
+    const fqPath = parsed.skill
+      ? `${parsed.host}/${parsed.owner}/${parsed.repo}/${parsed.skill}`
+      : `${parsed.host}/${parsed.owner}/${parsed.repo}`
+
+    console.log(`✅ Skill ready: ${skillName} (alias: ${alias})`)
     console.log(`   Location: ${skillDir}`)
 
+    // ── 写 deck.toml ────────────────────────────────────────────
+
     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}`)
+
+      // Alias collision check across all sections
+      const allAliases = new Set<string>()
+      for (const section of ['innate', 'tool', 'combo'] as const) {
+        const skills = deck[section]?.skills
+        if (skills && typeof skills === 'object' && !Array.isArray(skills)) {
+          for (const key of Object.keys(skills)) allAliases.add(key)
+        } else if (Array.isArray(skills)) {
+          for (const name of skills) allAliases.add(name.split('/').pop() || name)
+        }
+      }
+      for (const key of Object.keys(deck.transient || {})) {
+        allAliases.add(key)
       }
+      if (allAliases.has(alias)) {
+        console.error(`❌ Alias "${alias}" already exists in deck`)
+        process.exit(1)
+      }
+
+      // Auto-migrate old string-array format to dict
+      for (const section of ['innate', 'tool', 'combo'] as const) {
+        const sectionData = deck[section]
+        if (sectionData && Array.isArray(sectionData.skills)) {
+          const dict: Record<string, { path: string }> = {}
+          for (const name of sectionData.skills) {
+            const a = name.split('/').pop() || name
+            dict[a] = { path: name }
+          }
+          deck[section].skills = dict
+          console.log(`📝 Auto-migrated [${section}] from string-array to dict format`)
+        }
+      }
+
+      // Ensure target section exists and is dict format
+      if (!deck[skillType]) deck[skillType] = {}
+      if (!deck[skillType].skills) deck[skillType].skills = {}
+      if (Array.isArray(deck[skillType].skills)) {
+        const dict: Record<string, { path: string }> = {}
+        for (const name of deck[skillType].skills) {
+          const a = name.split('/').pop() || name
+          dict[a] = { path: name }
+        }
+        deck[skillType].skills = dict
+      }
+
+      deck[skillType].skills[alias] = { path: fqPath }
+      writeFileSync(deckPath, stringifyToml(deck))
+      console.log(`📝 Added "${alias}" to [${skillType}.skills] in ${deckPath}`)
     } else {
-      const minimal = { deck: { max_cards: 10 }, tool: { skills: [skillName] } }
+      const minimal: any = { deck: { max_cards: 10 } }
+      minimal[skillType] = { skills: { [alias]: { path: fqPath } } }
       writeFileSync(deckPath, stringifyToml(minimal))
-      console.log(`📝 Created ${deckPath} with "${skillName}"`)
+      console.log(`📝 Created ${deckPath} with "${alias}"`)
     }
 
     console.log('🔗 Running deck link...')
     const { linkDeck } = await import('./link.js')
-    linkDeck(deckPath === join(workdir, 'skill-deck.toml') ? undefined : deckPath, workdir)
+    linkDeck(deckPath, workdir)
 
   } catch (err) {
     console.error(`❌ Failed to add skill: ${err}`)