@lythos/skill-deck 0.4.0 → 0.5.0

package/README.md

@@ -1,22 +1,90 @@
 # @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"]
 ```
 
-## Quick Start
+### 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
 # 1. Create a skill-deck.toml
@@ -32,23 +100,7 @@ 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 |
 |---------|-----------|

package/package.json

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

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