lythoskill-deck: Declarative Skill Deck Governance

lythoskill-deck: Declarative Skill Deck Governance

What matters is not how many skills you have, but which ones the agent sees at the same time.

Core Model

skill-deck.toml declares desired state. deck link makes the working set (default .claude/​skills/) match — creates symlinks for declared skills, removes everything else. Deny-by-default: undeclared skills do not exist in the agent's view.

Cold Pool (~/​.agents/​skill-repos/)  →  deck add  →  skill-deck.toml  →  deck link  →  .claude/​skills/
     (all downloaded skills)              (declare)      (desired state)    (reconcile)    (working set — what agent sees)

Multi-File Phase Decks (BEST PRACTICE)

When a task spans different skill sets, use separate deck files per phase instead of editing a single toml:

# Phase 1 — brand design
deck link --deck phase1-brand.toml --cold-pool ~/​.agents/​skill-repos

# Phase 2 — content creation (atomic switch, Phase 1 skills gone)
deck link --deck phase2-content.toml --cold-pool ~/​.agents/​skill-repos

# Done — restore parent deck
deck link --deck ./​skill-deck.toml

Each phase deck is independently auditable. Never add/​remove entries in-place when switching contexts — a wrong edit silently breaks the previous phase's composition. The reconciler handles the transition: old symlinks removed, new ones created, no state leaks.

Seed Bootstrap

Start with a minimal deck (only lythoskill-deck as innate). The agent reads deck SKILL.md → learns schema → uses curator name LIKE '%keyword%' to discover skills → deck add + deck link → self-expands. Governance skill is the only irreducible dependency.

[deck]
max_cards = 8
cold_pool = "~/​.agents/​skill-repos"
working_set = ".claude/​skills"

[innate.skills.lythoskill-deck]
path = "github.com/​lythos-labs/​lythoskill/​skills/​lythoskill-deck"

Commands

# ── Core (use these every time) ──

# Reconcile working set to match declaration
bunx @lythos/​[email protected] link
bunx @lythos/​[email protected] link --deck ./​phase1-brand.toml

# Add skill from cold pool or download URL
bunx @lythos/​[email protected] add github.com/​owner/​repo/​skill-name
bunx @lythos/​[email protected] add github.com/​owner/​repo/​skill-name --alias my-skill --type tool

# ── Maintenance ──

bunx @lythos/​[email protected] refresh              # plan-only scan for updates
bunx @lythos/​[email protected] refresh --exec       # actually git pull (self-heals dirty cold pool; non-zero exit + trailing ⚠️ on failure)
bunx @lythos/​[email protected] remove <alias>       # remove from deck + working set
bunx @lythos/​[email protected] validate                   # check current deck
bunx @lythos/​[email protected] validate --deck <path>     # check specific deck
bunx @lythos/​[email protected] validate --remote          # probe locators against GitHub
# Cold-pool-missing skills warn (not error) — they may exist on GitHub.
# HATEOAS output: each warning suggests curator add <locator> as next step.

# ── Advanced ──

bunx @lythos/​[email protected] to-symlink <alias>   # snapshot → symlink
bunx @lythos/​[email protected] to-snapshot <alias>  # symlink → snapshot (pin HEAD)
bunx @lythos/​[email protected] per-run kimi          # render per-run CLI call from deck state (zero side effects)
bunx @lythos/​[email protected] reconcile            # drift report vs cold pool
bunx @lythos/​[email protected] reconcile --apply    # converge
bunx @lythos/​[email protected] migrate-schema       # old string-array → alias-as-key

link is a reconciler: undeclared symlinks → removed; broken symlinks → recreated; non-symlink entities → backed up then removed; missing declared skills → linked from cold pool. It also prints best-effort ⚠️ warnings when a cold-pool repo is behind origin, dirty, or on a non-default branch — drift is surfaced at the step every boot already runs. The health probe never blocks and swallows its own errors by design; set LYTHOS_DEBUG=1 to print a caught probe error (🔍 whisper) when you suspect the probe itself is broken.

refresh defaults to plan-only (no git pull). Use --exec to apply, or let an agent read the plan and execute per target — the agent can probe remotes, switch mirrors, handle divergence.

deck update is deprecated. Use refresh.

Format Detection (agent duty)

Before running any deck command, check the toml format. If you see skills = [...] (string array), it's the deprecated format. Ask before migrating:

⚠️  This deck uses the deprecated string-array format. Run migrate?
   bunx @lythos/​[email protected] migrate-schema
   bunx @lythos/​[email protected] migrate-schema --dry-run  # preview first

Do NOT silently migrate.

Key Concepts

lock vs state — what to commit and why

The deck writes two machine files with opposite git policies (ADR-20260616000939948 — born from a real incident: a ZK agent saw the old all-in-one lock dirty after a routine link and asked whether to commit).

Also ignore: working sets (.claude/, .agents/​skills/ — symlinks are per-machine) and non-root experiment lockfiles (.agents/​skill-deck.lock, showcase/​**/​skill-deck.lock). This repo's .gitignore is the reference implementation.

Why the lock belongs in git: a hash-only lock diff is the audit trail of "upstream skill content moved" — the alternative is silent drift. The split exists precisely so the lock behaves like a lockfile (changes only on content change) while link's operational churn lands in the ignored state file. deck link prints a drift hint when the lock changes — follow it; it stays silent when nothing moved.

Wrap-up ordering (real case, 2026-08-31 release): the session's final deck link ran at 17:46:55 — after the scribe's git-status snapshot, 80 s before the daily commit. Nobody re-checked git status; the lock sat dirty for a week and cost the next onboarding a judgment cycle. Rule: any link/​refresh is followed by a fresh git status as the LAST operation before the final commit.

Constraints

• deny-by-default — undeclared skills are physically absent from working set
• max_cards — exceeding the budget causes link to refuse
• link backs up real directories — non-symlink entries archived to .claude/​skills.bak.*.tar.gz
• transient expires — past-due transients trigger warnings
• managed_dirs overlap — two skills claiming same directory triggers warning
• Never manually create subdirectories in the working set directory — use deck link
• deck does not run post-install steps — API keys, env vars are the skill's own responsibility

Locators — Always Fully-Qualified

The deck does NOT auto-insert a skills/ prefix. Verify repo structure before writing locators.

Gotchas

deck link uses lstatSync, not existsSync — existsSync returns false for broken symlinks, causing EEXIST errors.

SKILL.md type field: Only standard or flow are valid. innate/tool/transient are deck toml section names, not SKILL.md types. deck_skill_type (custom field) for fork/transient declarations.

Network restrictions: The pre-clone connectivity probe is advisory — deck add always attempts the clone and lets git's own error be authoritative (probe false negatives on git smart-HTTP mirrors were a real incident). If a clone fails with network errors, use one of these env vars:

export LYTHOS_SOCKS_PROXY="127.0.0.1:1080"
bunx @lythos/​[email protected] add github.com/​owner/​repo/​skill

Innate priority: After compaction, read innate skills' full SKILL.md first. tool skills are lazy — read on trigger. Agent-side convention.

Never guess locators — web-search the repo structure before writing paths for unfamiliar repos.

skill-deck.lock goes dirty by design — link/refresh recompute the lock's content hashes from linked skill content, which lives OUTSIDE the repo (working-set symlinks → cold pool / upstream). The lock is the only in-repo artifact that moves, so git status can show M skill-deck.lock while no repo file changed. That is derived-state drift, not repo drift — don't burn a judgment cycle on it. Triage via git diff skill-deck.lock: hash-only lines = external content moved, safe to commit as housekeeping; path/​entry/​structure changes = real working-set change, review before committing. Never hand-edit the lock — regenerate via deck link (reverting skill-deck.toml does not revert derived state; re-run link).

Deck as Orchestrator — Task → Deck Mapping

lythos has no standalone orchestrator. The deck IS the orchestrator entry point. You (the agent) select the right pre-built deck for the user's task, link it in an isolated environment, and execute. The three-layer distribution: light orchestration in combo prompt, medium in SKILL.md, heavy mechanical in CLI.

When you encounter a deck with [combo.<name>] sections, READ the combo prompts. They are the orchestration playbook — step-by-step instructions for multi-skill pipelines. The combo section is not optional metadata; it IS the orchestrator. Skipping it means executing skills in isolation without the coordination logic.

Consumption contract: combo prompts are read and executed by the agent. The CLI only parses them into sections — there is no combo runtime, no code executes them. If you receive a deck (main or side) and skip its combos, you have not actually run the deck.

Intent → Deck mapping

Rule: deck first, don't ask. User says "调研" ("research it") → reach for deep-research.toml. User says "扫一下" ("sweep it") → qa-sweep.toml. Do NOT ask "should I use X or do it manually?" — just dispatch. The subagent works in parallel.

Full catalogue: examples/​decks/​INDEX.md.

Isolation discipline

Experiments run in /​tmp, never in committed directories. Arena's prepare-workdir creates an isolated temp dir, links the deck there, and archives only outputs. No pollution of the project working set.

# Golden rule: never run experiments in the project root
arena single --deck examples/​decks/​deep-research.toml --brief "..."  # auto-isolates in /​tmp

Orchestration weight — where does the logic go?

The agent is the orchestrator. Tools execute. You reason about conditions, pass state between calls, handle errors. Combo prompt gives you the playbook; CLI gives you the mechanical layer.

Supporting References