@lythos/skill-deck 0.9.48 → 0.9.49

package/README.md

@@ -2,14 +2,30 @@
 
 ![Coverage](https://img.shields.io/badge/coverage-82%25-brightgreen) ![CI](https://img.shields.io/badge/CI-71%20unit%20%2B%2021%20CLI%20BDD-brightgreen) ![Agent BDD](https://img.shields.io/badge/Agent%20BDD-5%20local-blue) ![Intent/Plan](https://img.shields.io/badge/arch-intent%2Fplan%2Fexecute-8A2BE2)
 
-> Declarative skill deck governance. Reconcile declared skills against your cold pool via symlinks — deny-by-default, max-cards budgeting, transient expiry.
+> Declarative skill deck governance. Declare skills, sync working set via symlinks — deny-by-default, max-cards budgeting, transient expiry. **Compatible with skills.sh syntax.**
+
+## Quick Start
+
+```bash
+# Add a skill from skills.sh (owner/repo syntax — no conversion needed)
+bunx @lythos/skill-deck@0.9.49 add vercel-labs/agent-skills
+
+# Or with @skill filter (same as npx skills add):
+bunx @lythos/skill-deck@0.9.49 add mattpocock/skills@tdd
+
+# Or FQ locator:
+bunx @lythos/skill-deck@0.9.49 add github.com/anthropics/skills/skills/frontend-design
+
+# Sync working set (deny-by-default):
+bunx @lythos/skill-deck@0.9.49 link
+```
 
 ## For AI Agents
 
 This package exposes a **CLI**. Invoke via:
 
 ```bash
-bunx @lythos/skill-deck@0.9.48 <command> [options]
+bunx @lythos/skill-deck@0.9.49 <command> [options]
 ```
 
 No installation required. `bunx` auto-downloads the package.
@@ -22,6 +38,7 @@ max_cards = 10
 
 [tool.skills.lythoskill-deck]
 path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
+source = "https://github.com/lythos-labs/lythoskill/blob/HEAD/skills/lythoskill-deck/SKILL.md"
 ```
 
 ### skill-deck.toml (full reference)
@@ -34,6 +51,7 @@ cold_pool = "~/.agents/skill-repos" # Where skills are downloaded
 
 [innate.skills.lythoskill-deck]     # Always-loaded skills
 path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
+source = "https://github.com/lythos-labs/lythoskill/blob/HEAD/skills/lythoskill-deck/SKILL.md"
 
 [tool.skills.tdd]                   # Auto-triggered skills
 path = "github.com/mattpocock/skills/skills/engineering/tdd"
@@ -55,15 +73,15 @@ prompt = "Search for latest info, then generate professional document with diagr
 
 | Situation | Command |
 |-----------|---------|
-| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.48 link` |
-| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.48 validate` |
-| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.48 add owner/repo` |
-| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.48 refresh` |
-| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.48 refresh tdd` |
-| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.48 remove tdd` |
-| Switch skill to symlink mode (live) | `bunx @lythos/skill-deck@0.9.48 to-symlink tdd` |
-| Switch skill to snapshot mode (pinned) | `bunx @lythos/skill-deck@0.9.48 to-snapshot tdd` |
-| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.48 link --deck ./my-deck.toml --workdir /path/to/project` |
+| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.49 link` |
+| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.49 validate` |
+| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.49 add owner/repo` |
+| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.49 refresh` |
+| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.49 refresh tdd` |
+| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.49 remove tdd` |
+| Switch skill to symlink mode (live) | `bunx @lythos/skill-deck@0.9.49 to-symlink tdd` |
+| Switch skill to snapshot mode (pinned) | `bunx @lythos/skill-deck@0.9.49 to-snapshot tdd` |
+| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.49 link --deck ./my-deck.toml --workdir /path/to/project` |
 
 ### Commands
 
@@ -71,7 +89,7 @@ prompt = "Search for latest info, then generate professional document with diagr
 |---------|------|-------------|
 | `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> [--alias <alias>] [--type <type>] [--deck <path>]` | Git clone skill to cold pool and append to skill-deck.toml. |
+| `add` | `<locator> [--alias <alias>] [--type <type>] [--deck <path>]` | Add skill to cold pool + deck.toml. Accepts skills.sh syntax (owner/repo, owner/repo@skill, github:owner/repo) and FQ locators. |
 | `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. |
 | `to-symlink` | `<alias> [--deck <path>] [--workdir <dir>]` | Switch a skill to symlink mode (live link, follows cold pool) |
@@ -121,10 +139,11 @@ max_cards = 10
 
 [tool.skills.lythoskill-deck]
 path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
+source = "https://github.com/lythos-labs/lythoskill/blob/HEAD/skills/lythoskill-deck/SKILL.md"
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/
-bunx @lythos/skill-deck@0.9.48 link
+bunx @lythos/skill-deck@0.9.49 link
 ```
 
 ### Key Concepts
@@ -210,7 +229,7 @@ Caution: deck's deny-by-default will remove any skills not declared in your deck
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| `❌ Skill not found: <name>` | Skill declared in deck but not in cold pool | `bunx @lythos/skill-deck@0.9.48 add github.com/owner/repo/skill` or clone manually into cold pool |
+| `❌ Skill not found: <name>` | Skill declared in deck but not in cold pool | `bunx @lythos/skill-deck@0.9.49 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 |
 | `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 |

package/package.json

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

package/src/add.test.ts

@@ -10,7 +10,7 @@ import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import * as childProcess from 'node:child_process'
-import { findSkillDir } from './add.ts'
+import { findSkillDir, normalizeSkillsSh } from './add.ts'
 
 // Control homedir() return value for tests that need default cold_pool under tmpdir
 let mockHomeDir = '/tmp'
@@ -256,3 +256,128 @@ describe('findSkillDir', () => {
     expect(findSkillDir(repo, null)).toBeNull()
   })
 })
+
+// ── skills.sh syntax sugar — top skills parse validation ────────
+
+describe('normalizeSkillsSh', () => {
+  // FQ locators — must pass through unchanged
+  it('passes FQ github.com locators through', () => {
+    expect(normalizeSkillsSh('github.com/anthropics/skills/skills/frontend-design'))
+      .toBe('github.com/anthropics/skills/skills/frontend-design')
+    expect(normalizeSkillsSh('github.com/vercel-labs/agent-skills'))
+      .toBe('github.com/vercel-labs/agent-skills')
+  })
+
+  it('passes localhost locators through', () => {
+    expect(normalizeSkillsSh('localhost/me/skill-a')).toBe('localhost/me/skill-a')
+  })
+
+  // skills.sh top skill owner/repo formats
+  it('normalizes vercel-labs/skills', () => {
+    expect(normalizeSkillsSh('vercel-labs/skills')).toBe('github.com/vercel-labs/skills')
+  })
+
+  it('normalizes vercel-labs/agent-skills', () => {
+    expect(normalizeSkillsSh('vercel-labs/agent-skills')).toBe('github.com/vercel-labs/agent-skills')
+  })
+
+  it('normalizes anthropics/skills', () => {
+    expect(normalizeSkillsSh('anthropics/skills')).toBe('github.com/anthropics/skills')
+  })
+
+  it('normalizes obra/superpowers', () => {
+    expect(normalizeSkillsSh('obra/superpowers')).toBe('github.com/obra/superpowers')
+  })
+
+  it('normalizes browser-use/browser-use', () => {
+    expect(normalizeSkillsSh('browser-use/browser-use')).toBe('github.com/browser-use/browser-use')
+  })
+
+  it('normalizes firecrawl/cli', () => {
+    expect(normalizeSkillsSh('firecrawl/cli')).toBe('github.com/firecrawl/cli')
+  })
+
+  it('normalizes apify/agent-skills', () => {
+    expect(normalizeSkillsSh('apify/agent-skills')).toBe('github.com/apify/agent-skills')
+  })
+
+  it('normalizes squirrelscan/skills', () => {
+    expect(normalizeSkillsSh('squirrelscan/skills')).toBe('github.com/squirrelscan/skills')
+  })
+
+  it('normalizes getsentry/sentry-for-ai', () => {
+    expect(normalizeSkillsSh('getsentry/sentry-for-ai')).toBe('github.com/getsentry/sentry-for-ai')
+  })
+
+  it('normalizes coderabbitai/skills', () => {
+    expect(normalizeSkillsSh('coderabbitai/skills')).toBe('github.com/coderabbitai/skills')
+  })
+
+  it('normalizes openai/skills', () => {
+    expect(normalizeSkillsSh('openai/skills')).toBe('github.com/openai/skills')
+  })
+
+  it('normalizes google-gemini/gemini-cli', () => {
+    expect(normalizeSkillsSh('google-gemini/gemini-cli')).toBe('github.com/google-gemini/gemini-cli')
+  })
+
+  it('normalizes coreyhaines31/marketingskills', () => {
+    expect(normalizeSkillsSh('coreyhaines31/marketingskills')).toBe('github.com/coreyhaines31/marketingskills')
+  })
+
+  it('normalizes jimliu/baoyu-skills', () => {
+    expect(normalizeSkillsSh('jimliu/baoyu-skills')).toBe('github.com/jimliu/baoyu-skills')
+  })
+
+  it('normalizes astronmer/agents', () => {
+    expect(normalizeSkillsSh('astronomer/agents')).toBe('github.com/astronomer/agents')
+  })
+
+  // owner/repo@skill syntax — normalizes to repo level, discovery at runtime
+  it('normalizes owner/repo@skill to repo-level locator', () => {
+    expect(normalizeSkillsSh('vercel-labs/skills@find-skills'))
+      .toBe('github.com/vercel-labs/skills')
+    expect(normalizeSkillsSh('mattpocock/skills@tdd'))
+      .toBe('github.com/mattpocock/skills')
+    expect(normalizeSkillsSh('google-gemini/gemini-cli@code-reviewer'))
+      .toBe('github.com/google-gemini/gemini-cli')
+  })
+
+  // owner/repo/subpath syntax
+  it('normalizes owner/repo/subpath', () => {
+    expect(normalizeSkillsSh('anthropics/skills/skills/frontend-design'))
+      .toBe('github.com/anthropics/skills/skills/frontend-design')
+  })
+
+  // github: prefix
+  it('normalizes github:owner/repo', () => {
+    expect(normalizeSkillsSh('github:vercel-labs/agent-skills'))
+      .toBe('github.com/vercel-labs/agent-skills')
+  })
+
+  // #ref suffix (branch/tag/commit) — compatible with skills.sh parseFragmentRef
+  it('preserves #ref with FQ locator', () => {
+    expect(normalizeSkillsSh('github.com/vercel-labs/skills#main'))
+      .toBe('github.com/vercel-labs/skills#main')
+  })
+
+  it('preserves #ref with owner/repo shorthand', () => {
+    expect(normalizeSkillsSh('vercel-labs/skills#v2.0'))
+      .toBe('github.com/vercel-labs/skills#v2.0')
+  })
+
+  it('preserves #ref with @skill syntax', () => {
+    expect(normalizeSkillsSh('vercel-labs/skills#main@find-skills'))
+      .toBe('github.com/vercel-labs/skills#main')
+  })
+
+  it('preserves #ref with subpath', () => {
+    expect(normalizeSkillsSh('anthropics/skills/skills/frontend-design#abc1234'))
+      .toBe('github.com/anthropics/skills/skills/frontend-design#abc1234')
+  })
+
+  it('preserves #ref with github: prefix', () => {
+    expect(normalizeSkillsSh('github:vercel-labs/agent-skills#dev'))
+      .toBe('github.com/vercel-labs/agent-skills#dev')
+  })
+})

package/src/add.ts

@@ -29,6 +29,7 @@ import {
   type Locator,
 } from '@lythos/cold-pool'
 import { findDeckToml, expandHome } from './link.js'
+import { validateAlias } from './path-guard.js'
 
 export function findSkillDir(repoPath: string, skill: string | null): string | null {
   if (skill) {
@@ -80,12 +81,77 @@ function fqOf(loc: Locator): string {
   return formatLocator(loc)
 }
 
+/**
+ * Normalize skills.sh syntax to FQ locator (UX sugar — internal rep stays git-only).
+ *
+ *   owner/repo@skill            → github.com/owner/repo (skillFilter handled by discovery)
+ *   owner/repo/subpath          → github.com/owner/repo/subpath
+ *   github:owner/repo           → github.com/owner/repo
+ *   owner/repo                  → github.com/owner/repo
+ */
+export function normalizeSkillsSh(input: string): string {
+  // localhost: always pass through (parseLocator handles multi-segment validation)
+  if (input.startsWith('localhost/')) return input
+
+  // Extract #ref suffix (branch/tag/commit) — compatible with skills.sh parseFragmentRef.
+  // #ref comes before @skill: owner/repo#main@skill-name → ref=main, skill=skill-name
+  let ref = ''
+  let base = input
+  const hashIdx = input.indexOf('#')
+  if (hashIdx >= 0) {
+    base = input.slice(0, hashIdx)
+    const afterHash = input.slice(hashIdx + 1)
+    const atInRef = afterHash.indexOf('@')
+    if (atInRef >= 0) {
+      ref = `#${afterHash.slice(0, atInRef)}`
+      base = `${base}@${afterHash.slice(atInRef + 1)}`
+    } else {
+      ref = input.slice(hashIdx) // includes '#'
+    }
+  }
+
+  // Already an FQ locator: host.tld/owner/repo[/...] — pass through with ref
+  if (base.match(/^[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\/.+\/.+/)) return input
+
+  // github: prefix
+  const ghPrefix = base.match(/^github:(.+)$/)
+  if (ghPrefix) return `github.com/${ghPrefix[1]}${ref}`
+
+  // owner/repo@skill shorthand — normalizes to repo-level locator.
+  // Skill discovery at runtime (scanSkill → name match) because the
+  // actual path within the repo is unknown until after clone.
+  // e.g. gemini-cli has skills at .gemini/skills/, not skills/.
+  const atMatch = base.match(/^([^/]+)\/([^/@]+)@(.+)$/)
+  if (atMatch && !base.includes(':') && !base.startsWith('.')) {
+    const [, owner, repo] = atMatch
+    return `github.com/${owner}/${repo}${ref}`
+  }
+
+  // owner/repo[/subpath] shorthand (no dot in first segment → not a hostname)
+  const shortMatch = base.match(/^([^/.]+)\/([^/]+)(?:\/(.+?))?\/?$/)
+  if (shortMatch && !base.includes(':') && !base.startsWith('.')) {
+    const [, owner, repo, subpath] = shortMatch
+    const fq = subpath
+      ? `github.com/${owner}/${repo}/${subpath}`
+      : `github.com/${owner}/${repo}`
+    return `${fq}${ref}`
+  }
+
+  return input
+}
+
 function exitInvalidLocator(locator: string): never {
   console.error(`❌ Invalid locator: ${locator}`)
-  console.error(`   Expected FQ form (per ADR-20260502012643244):`)
-  console.error(`     host.tld/owner/repo[/skill]   — remote skill`)
-  console.error(`     localhost/<name>              — local-only skill`)
-  console.error(`   Bare names and shorthand 'owner/repo' are rejected.`)
+  console.error(`   Accepted formats:`)
+  console.error(`     github.com/owner/repo[/skill]   — FQ locator (cold pool path, NOT a browser URL)`)
+  console.error(`     owner/repo                      — GitHub shorthand`)
+  console.error(`     owner/repo@skill                — skills.sh syntax`)
+  console.error(`     owner/repo/subpath              — subdirectory`)
+  console.error(`     github:owner/repo               — explicit GitHub prefix`)
+  console.error(`     localhost/<name>                — local-only skill`)
+  console.error(``)
+  console.error(`   Note: FQ locators look like URLs but map to cold pool paths:`)
+  console.error(`     github.com/o/r/skills/s → ~/.agents/skill-repos/github.com/o/r/skills/s/SKILL.md`)
   process.exit(1)
 }
 
@@ -99,8 +165,9 @@ export async function addSkill(
     ? resolvePath(options.deck)
     : findDeckToml(workdir) || join(workdir, 'skill-deck.toml')
 
-  const parsed = parseLocator(locator)
-  if (!parsed) exitInvalidLocator(locator)
+  const normalized = normalizeSkillsSh(locator)
+  const parsed = parseLocator(normalized)
+  if (!parsed) exitInvalidLocator(normalized)
 
   if (parsed.isLocalhost) {
     console.error(`❌ deck add does not support localhost locators (no remote to clone).`)
@@ -113,7 +180,13 @@ export async function addSkill(
   const fetchPlan = buildFetchPlan(pool, parsed)
   const fqPath = fqOf(parsed)
   const skillName = parsed.skill ? basename(parsed.skill) : parsed.repo!
-  const alias = options.alias || skillName
+  const rawAlias = options.alias || skillName
+  try { validateAlias(rawAlias) } catch (e: any) {
+    console.error(`❌ Invalid alias: ${e.message}`)
+    console.error('   Aliases may only contain letters, numbers, hyphens, and underscores.')
+    process.exit(1)
+  }
+  const alias = rawAlias
   const skillType = (options.type || 'tool').toLowerCase()
 
   if (!['innate', 'tool', 'combo'].includes(skillType)) {
@@ -190,6 +263,9 @@ export async function addSkill(
 
   console.log(`✅ Skill ready: ${skillName} (alias: ${alias})`)
   console.log(`   Location: ${skillDir}`)
+  if (parsed.host === 'github.com') {
+    console.log(`   Source:   https://github.com/${parsed.owner}/${parsed.repo}`)
+  }
 
   // ── 写 deck.toml ────────────────────────────────────────────
 
@@ -241,7 +317,18 @@ export async function addSkill(
       deck[skillType].skills = dict
     }
 
-    deck[skillType].skills[alias] = { path: fqPath }
+    const entry: Record<string, string> = { path: fqPath }
+    if (parsed.host === 'github.com') {
+      const skillRel = parsed.skill ? `/${parsed.skill}` : ''
+      const rawRef = parsed.ref || 'HEAD'
+      // Reject refs that could inject into URL (query, fragment, auth)
+      if (/[?#@]/.test(rawRef)) {
+        console.warn(`⚠️  Ref "${rawRef}" contains URL-special characters — source URL skipped`)
+      } else {
+        entry.source = `https://github.com/${parsed.owner}/${parsed.repo}/blob/${rawRef}${skillRel}/SKILL.md`
+      }
+    }
+    deck[skillType].skills[alias] = entry
     writeFileSync(deckPath, stringifyToml(deck))
     console.log(`📝 Added "${alias}" to [${skillType}.skills] in ${deckPath}`)
   } else {

package/src/link.ts

@@ -24,6 +24,7 @@ import {
 } from "./schema.js";
 import { parseDeck } from "./parse-deck.js";
 import { resolveDeckPathSync, fetchDeckUrl, isUrl } from "./resolve-deck.js";
+import { safeResolveInDir } from "./path-guard.js";
 
 // ── 路径工具 ────────────────────────────────────────────────
 
@@ -203,7 +204,13 @@ for (const entry of parsedEntries) {
     // For localhost skills, create a placeholder so the user can fill it in
     if (entry.path.startsWith('localhost/')) {
       const skill = entry.path.slice('localhost/'.length)
-      const localPath = join(COLD_POOL, skill)
+      let localPath: string
+      try {
+        localPath = safeResolveInDir(COLD_POOL, skill)
+      } catch (e: any) {
+        errors.push(`Invalid localhost path "${entry.path}": ${e.message}`)
+        continue
+      }
       if (!existsSync(join(localPath, 'SKILL.md'))) {
         const now = new Date().toISOString().slice(0, 10)
         const placeholder = [
@@ -366,8 +373,8 @@ if (nonSymlinks.length > 0) {
     mkdirSync(join(PROJECT_DIR, ".claude"), { recursive: true });
 
     const tarArgs = [
-      "czf", bakPath,
-      ...nonSymlinks.map(e => relative(PROJECT_DIR, join(WORKING_SET, e))),
+      "czf", bakPath, "--",
+      ...nonSymlinks.map(e => "./" + relative(PROJECT_DIR, join(WORKING_SET, e))),
     ];
     try {
       execFileSync("tar", tarArgs, {

package/src/parse-deck.ts

@@ -19,7 +19,12 @@ export interface ParsedDeck {
 }
 
 export function parseDeck(raw: string): ParsedDeck {
-  const parsed = parseToml(raw) as any;
+  let parsed: any;
+  try {
+    parsed = parseToml(raw) as any;
+  } catch (e: any) {
+    return { entries: [], deprecated: false, errors: [`TOML parse error: ${e.message}`] };
+  }
   const entries: ParsedSkillEntry[] = [];
   const errors: string[] = [];
   let deprecated = false;

package/src/path-guard.ts

@@ -0,0 +1,130 @@
+/**
+ * path-guard — Centralized path traversal prevention for deck CLI.
+ *
+ * All alias validation and safe-path construction MUST go through these
+ * functions. Individual commands (link, remove, to-symlink-snapshot, add)
+ * must NOT sanitize aliases or resolve paths by hand.
+ *
+ * Reference: CWE-22 (Path Traversal), OWASP A01:2021
+ */
+
+import { resolve } from 'node:path'
+import { realpathSync, existsSync } from 'node:fs'
+
+/**
+ * Characters allowed in skill aliases.
+ *
+ * Allow-list (not block-list): alphanumeric + hyphens + underscores only.
+ * Rejecting '.' '/' '\\' prevents traversal. Rejecting '..' explicitly
+ * prevents parent-directory escapes even if a '.' were to slip through.
+ */
+const ALIAS_ALLOWED = /^[A-Za-z0-9_-]+$/
+const ALIAS_MAX_LENGTH = 128
+
+/**
+ * Validate a skill alias. Returns the alias unchanged if valid, throws otherwise.
+ *
+ * Aliases serve as directory names in the working set (.claude/skills/<alias>/).
+ * They must be simple names — no path separators, no dots, no special chars.
+ */
+export function validateAlias(alias: string): string {
+  if (!alias || alias.length === 0) {
+    throw new Error(`Alias must not be empty`)
+  }
+  if (alias.length > ALIAS_MAX_LENGTH) {
+    throw new Error(`Alias too long (max ${ALIAS_MAX_LENGTH} chars): ${alias.slice(0, 50)}...`)
+  }
+  if (!ALIAS_ALLOWED.test(alias)) {
+    throw new Error(
+      `Invalid alias "${alias}". Aliases may only contain letters, numbers, hyphens, and underscores. ` +
+      `No dots, slashes, or special characters.`
+    )
+  }
+  return alias
+}
+
+/**
+ * Resolve a path segment within a root directory, rejecting traversals.
+ *
+ * Steps:
+ * 1. Resolve root + segment to absolute path
+ * 2. If root exists on disk, resolve symlinks (realpath) for both
+ * 3. Verify the resolved path stays within the resolved root
+ */
+export function safeResolveInDir(root: string, segment: string): string {
+  // Pre-check: reject segments that are obviously malicious before resolve()
+  if (segment.includes('\0')) {
+    throw new Error('Path segment contains null byte')
+  }
+  if (segment.includes('..')) {
+    throw new Error('Path segment contains parent traversal (..)')
+  }
+  if (segment.startsWith('/') || /^[A-Za-z]:/.test(segment)) {
+    throw new Error('Path segment is absolute')
+  }
+
+  const resolved = resolve(root, segment)
+
+  // If root exists, use realpath for symlink-aware boundary check
+  if (existsSync(root)) {
+    const realRoot = realpathSync(root)
+    let realPath: string
+    try {
+      realPath = realpathSync(resolved)
+    } catch {
+      // Path doesn't exist yet (e.g. mkdir first) — resolve is sufficient
+      // since we already rejected '../' and absolute paths
+      if (!resolved.startsWith(resolve(root) + '/') && resolved !== resolve(root)) {
+        throw new Error(`Path traversal blocked: ${segment} resolves outside ${root}`)
+      }
+      return resolved
+    }
+    if (!realPath.startsWith(realRoot + '/') && realPath !== realRoot) {
+      throw new Error(`Path traversal blocked: ${segment} resolves outside ${root}`)
+    }
+    return realPath
+  }
+
+  // Root doesn't exist yet — trust resolve() since we pre-checked segments
+  return resolved
+}
+
+/**
+ * Verify a working_set directory is safe for deck operations.
+ *
+ * The working set is where deck creates/removes symlinks and snapshots.
+ * It must not be a system-critical path.
+ */
+const FORBIDDEN_ROOTS = new Set([
+  '/', '/home', '/etc', '/usr', '/bin', '/sbin', '/lib', '/lib64',
+  '/var', '/tmp', '/opt', '/root', '/boot', '/dev', '/proc', '/sys',
+  '/System', '/Applications', '/Library',  // macOS
+])
+
+export function validateWorkingSet(workingSet: string, projectDir: string): void {
+  const resolved = resolve(workingSet)
+
+  if (FORBIDDEN_ROOTS.has(resolved)) {
+    throw new Error(
+      `working_set "${workingSet}" resolves to a forbidden system path "${resolved}". ` +
+      `The working set must be inside the project or under a dedicated agents directory.`
+    )
+  }
+
+  // It must be under the project, OR be a hidden directory (.claude/skills, .agents/skills, etc.)
+  const resolvedProject = resolve(projectDir)
+  if (resolved.startsWith(resolvedProject + '/')) return
+
+  // Outside project — OK only if it's a hidden dir (agent convention)
+  const basename = resolved.split('/').pop()!
+  if (!basename.startsWith('.')) {
+    throw new Error(
+      `working_set "${workingSet}" is outside the project and not a hidden directory. ` +
+      `Agent skill directories should start with '.' (e.g. .claude/skills, .agents/skills).`
+    )
+  }
+}
+
+// ── Re-exports for convenience ───────────────────────────
+
+export { ALIAS_ALLOWED, ALIAS_MAX_LENGTH }

package/src/remove.ts

@@ -13,7 +13,7 @@ import { findDeckToml, expandHome } from "./link.js";
 import { parseDeck } from "./parse-deck.js";
 import { ColdPool } from "@lythos/cold-pool";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { validateAlias } from "./path-guard.js";
 
 export function removeSkill(target: string, cliDeckPath?: string, cliWorkdir?: string): void {
   const cliDeck = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
@@ -54,6 +54,13 @@ export function removeSkill(target: string, cliDeckPath?: string, cliWorkdir?: s
   const section = match.type;
   const alias = match.alias;
 
+  // Validate alias before using as path component (CWE-22)
+  try { validateAlias(alias) } catch (e: any) {
+    console.error(`❌ Invalid alias in deck.toml: ${e.message}`)
+    console.error(`   Fix skill-deck.toml before re-running.`)
+    process.exit(1)
+  }
+
   if (deck[section]?.skills) {
     if (Array.isArray(deck[section].skills)) {
       // Legacy string-array format
@@ -106,3 +113,4 @@ export function removeSkill(target: string, cliDeckPath?: string, cliWorkdir?: s
 
   console.log(`\n💡 Cold pool untouched. Run 'bunx @lythos/cold-pool prune' to GC unreferenced repos.`);
 }
+

package/src/resolve-deck.ts

@@ -44,6 +44,14 @@ export function resolveDeckPathSync(cliArg?: string): ResolvedDeck {
 export async function fetchDeckUrl(url: string): Promise<string> {
   const normalized = normalizeUrl(url)
   const dest = resolve(process.cwd(), 'skill-deck.toml')
+  if (existsSync(dest)) {
+    throw new Error(
+      `Refusing to overwrite existing ${dest}.\n` +
+      `  A skill-deck.toml already exists in this directory.\n` +
+      `  To use a remote deck, run from an empty directory or specify a different --deck path.\n` +
+      `  To keep your existing deck, use a local file: deck link --deck ./skill-deck.toml`
+    )
+  }
   console.log(`📥 Fetching deck: ${normalized}`)
   const res = await fetch(normalized, { signal: AbortSignal.timeout(30_000) })
   if (!res.ok) {

package/src/to-symlink-snapshot.ts

@@ -16,6 +16,7 @@ import { ColdPool, parseLocator } from '@lythos/cold-pool'
 import { findSource } from './link.js'
 import { parse as parseToml } from '@iarna/toml'
 import type { SkillDeckLock } from './schema.js'
+import { validateAlias } from './path-guard.js'
 
 function readLock(projectDir: string): SkillDeckLock | null {
   const lockPath = join(projectDir, 'skill-deck.lock')
@@ -66,6 +67,11 @@ export function toSymlinkSkill(target: string, cliDeckPath?: string, cliWorkdir?
     process.exit(1)
   }
 
+  try { validateAlias(match.alias) } catch (e: any) {
+    console.error(`❌ Invalid alias in deck.toml: ${e.message}`)
+    process.exit(1)
+  }
+
   const dest = join(WORKING_SET, match.alias)
   const source = findSource(match.path, COLD_POOL, PROJECT_DIR)
 
@@ -122,6 +128,11 @@ export function toSnapshotSkill(target: string, cliDeckPath?: string, cliWorkdir
     process.exit(1)
   }
 
+  try { validateAlias(match.alias) } catch (e: any) {
+    console.error(`❌ Invalid alias in deck.toml: ${e.message}`)
+    process.exit(1)
+  }
+
   const dest = join(WORKING_SET, match.alias)
   const source = findSource(match.path, COLD_POOL, PROJECT_DIR)