lythoskill-deck

Files (15)

• SKILL.md
• skill-deck.toml.template · assets/
• architecture.md · references/
• arena-integration.md · references/
• cold-pool-setup.md · references/
• custom-fields.md · references/
• deck-building.md · references/
• glossary.md · references/
• intent-plan-execute.md · references/
• skill-repo-states.md · references/
• skill-types.md · references/
• toml-format.md · references/
• deck-migrate.sh · scripts/
• deck-status.sh · scripts/
• link.sh · scripts/

SKILL.md (first lines)

# 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.

> **Invocation.** Body text uses the `deck <cmd>` shorthand. Run commands as
> `bunx @lythos/skill-deck@{{PACKAGE_VERSION}} <cmd>` (no install), or
> `lythoskill-deck <cmd>` if installed globally. The bare `deck` name is an
> in-repo alias convention in the lythoskill monorepo only — NOT a registered
> bin (the npm package registers `lythoskill-deck`). Same mapping: `arena` →
> `@lythos/skill-arena`, `curator` → `@lythos/skill-curator`, `cortex` →
> `@lythos/project-cortex`.
> Want the shorthand? Register it yourself — e.g.
> `alias deck='bunx @lythos/skill-deck@latest'` in your shell config.
> Optional, your machine, your choice.

## 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:

```bash
# Phase 1 — brand design (full form: bunx @lythos/skill-deck@<version> link …)
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} link --deck phase1-brand.toml --cold-pool ~/.agents/skill-repos

# Phase 2 — content creation (atomic switch, Phase 1 skills gone)
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} link --deck phase2-content.toml --cold-pool ~/.agents/skill-repos

# Done — restore parent deck
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} 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.

```toml
[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

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

# Reconcile working set to match declaration
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} link
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} link --deck ./phase1-brand.toml

# Add skill from cold pool or download URL
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} add github.com/owner/repo/skill-name
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} add github.com/owner/repo/skill-name --alias my-skill --type tool

# ── Maintenance ──

bunx @lythos/skill-deck@{{PACKAGE_VERSION}} refresh              # plan-only scan for updates
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} refresh --exec       # actually git pull (self-heals dirty cold pool; non-zero exit + trailing ⚠️ on failure)
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} remove <alias>       # remove from deck + working set
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} validate                   # check current deck
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} validate --deck <path>     # check specific deck
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} 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/skill-deck@{{PACKAGE_VERSION}} to-symlink <alias>   # snapshot → symlink
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} to-snapshot <alias>  # symlink → snapshot (pin HEAD)
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} per-run kimi          # render per-run CLI call from deck state (zero side effects)
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} reconcile            # drift report vs cold pool
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} reconcile --apply    # converge
bunx @lythos/skill-deck@{{PACKAGE_VERSION}} 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/skill-deck@{{PACKAGE_VERSION}} migrate-schema
   bunx @lythos/skill-deck@{{PACKAGE_VERSION}} migrate-schema --dry-run  # preview first
```

Do NOT silently migrate.

## Key Concepts

| Concept | One-liner |
|---------|-----------|
| Cold Pool | All downloaded skills (`~/.agents/skill-repos/`). Agent cannot see here. |
| skill-deck.toml | Declares desired state. Alias-as-key dict format. |
| deck link | Reconciler. Makes the working set match the declaration. |
| Working Set | Symlinks only. What the agent actually scans. Default: `.claude/skills/` (configurable per platform). |
| skill-deck.lock | Machine-generated snapshot: resolved paths, hashes, constraints. |

## 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

From lythos-labs/lythoskill, MIT.

More from lythos-labs/lythoskill