@lythos/skill-deck 0.3.0 → 0.4.0

package/README.md

@@ -1,40 +1,78 @@
 # @lythos/skill-deck
 
-> Declarative skill deck governance. Reconcile declared skills against your cold pool via symlinks.
+> Declarative skill deck governance for AI agents. Reconcile declared skills against your cold pool via symlinks — deny-by-default, max-cards budgeting, transient expiry.
 
-Part of the [lythoskill](https://github.com/lythos-labs/lythoskill) meta-skill ecosystem.
+## Why
 
-## What it does
+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.
 
-Manages your agent's working set of skills. You declare which skills you want in `skill-deck.toml`; `deck link` creates symlinks from the cold pool to `.claude/skills/`. Supports deny-by-default isolation, max_cards budgeting, transient expiry, and managed directory overlap detection.
+`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.
 
 ## Install
 
 ```bash
 bun add -d @lythos/skill-deck
-# or
+# or use directly
 bunx @lythos/skill-deck <command>
 ```
 
-## Commands
+## Quick Start
 
 ```bash
-# Link declared skills to working set
+# 1. Create a skill-deck.toml
+cat > skill-deck.toml << 'EOF'
+[deck]
+max_cards = 10
+
+[tool]
+skills = ["lythoskill-deck"]
+EOF
+
+# 2. Link — creates symlinks in .claude/skills/
 bunx @lythos/skill-deck link
+```
+
+## Commands
+
+```
+lythoskill-deck — Declarative skill deck governance — cold pool, working set, deny-by-default
 
-# Link with custom deck file
-bunx @lythos/skill-deck link --deck ./my-deck.toml
+Usage: lythoskill-deck link | lythoskill-deck validate [deck.toml]
 
-# Show current deck status
-bunx @lythos/skill-deck status
+Commands:
+  link                  Sync working set with skill-deck.toml
+  validate [deck.toml]  Validate deck configuration
 
-# Migrate from old deck format
-bunx @lythos/skill-deck migrate
+Options:
+  --deck <path>    Specify skill-deck.toml path
+  --workdir <dir>  Specify working directory
 ```
 
+## 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. |
+| **deny-by-default** | Undeclared skills are physically absent from the working set. |
+
+## 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
 
-This is the **Starter** layer of the thin-skill pattern. The agent-visible **Skill** layer lives in `packages/lythoskill-deck/skill/` and is built to `skills/lythoskill-deck/`.
+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
+```
 
 ## License
 

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "@lythos/skill-deck",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
+  "keywords": [
+    "ai-agent",
+    "skill",
+    "claude-code",
+    "agent-skills",
+    "llm-tooling",
+    "lythoskill"
+  ],
+  "author": "lythos-labs",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -14,6 +23,16 @@
   ],
   "dependencies": {
     "@iarna/toml": "^2.2.5",
+    "yaml": "^2.8.3",
     "zod": "^4.3.6"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lythos-labs/lythoskill.git",
+    "directory": "packages/lythoskill-deck"
+  },
+  "bugs": {
+    "url": "https://github.com/lythos-labs/lythoskill/issues"
+  },
+  "homepage": "https://github.com/lythos-labs/lythoskill/tree/main/packages/lythoskill-deck#readme"
 }

package/src/link.ts

@@ -8,6 +8,7 @@
  */
 
 import { parse as parseToml } from "@iarna/toml";
+import YAML from "yaml";
 import { createHash } from "crypto";
 import {
   existsSync, mkdirSync, readFileSync, readdirSync,
@@ -36,49 +37,17 @@ export function expandHome(p: string, base: string): string {
 function hashContent(content: string): string {
   return createHash("sha256").update(content).digest("hex");
 }
-
 // ── Front matter 提取 ───────────────────────────────────────
 
-function getFrontMatter(skillMdPath: string): string {
+function parseSkillFrontmatter(skillMdPath: string): Record<string, any> {
   try {
     const c = readFileSync(skillMdPath, "utf-8");
-    if (!c.startsWith("---")) return "";
-    const parts = c.split("---");
-    return parts.length >= 3 ? parts[1] : "";
-  } catch { return ""; }
-}
-
-function extractField(fm: string, field: string): string {
-  const m = fm.match(new RegExp(`^${field}:\\s*(.+)$`, "m"));
-  return m ? m[1].trim() : "";
+    const match = c.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+    if (!match) return {};
+    return YAML.parse(match[1]) || {};
+  } catch { return {}; }
 }
 
-function extractArrayField(fm: string, field: string): string[] {
-  const lines = fm.split("\n");
-  const results: string[] = [];
-  let collecting = false;
-  for (const line of lines) {
-    if (line.match(new RegExp(`^${field}:\\s*$`))) {
-      collecting = true;
-      continue;
-    }
-    if (line.match(new RegExp(`^${field}:\\s*\\[`))) {
-      const inline = line.match(/\[(.+)\]/);
-      if (inline) return inline[1].split(",").map(s => s.trim().replace(/^["']|["']$/g, ""));
-      collecting = true;
-      continue;
-    }
-    if (collecting) {
-      const item = line.match(/^\s+-\s+(.+)/);
-      if (item) {
-        results.push(item[1].trim().replace(/^["']|["']$/g, ""));
-      } else if (line.trim() !== "" && !line.match(/^\s*#/)) {
-        break;
-      }
-    }
-  }
-  return results;
-}
 
 // ── 冷池查找 ────────────────────────────────────────────────
 
@@ -253,9 +222,13 @@ for (const item of declared) {
 
   // 提取元数据
   const skillMdPath = join(item.sourcePath, "SKILL.md");
-  const fm = getFrontMatter(skillMdPath);
-  const niche = extractField(fm, "deck_niche");
-  const managedDirs = extractArrayField(fm, "deck_managed_dirs");
+  const fm = parseSkillFrontmatter(skillMdPath);
+  const niche = String(fm["deck_niche"] || "");
+  const managedDirs = Array.isArray(fm["deck_managed_dirs"])
+    ? fm["deck_managed_dirs"].map(String)
+    : fm["deck_managed_dirs"]
+      ? [String(fm["deck_managed_dirs"])]
+      : [];
   let contentHash: string | undefined;
   try {
     contentHash = hashContent(readFileSync(skillMdPath, "utf-8"));