@lythos/skill-deck 0.9.49 → 0.9.51

package/README.md

@@ -8,16 +8,16 @@
 
 ```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
+bunx @lythos/skill-deck@0.9.51 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
+bunx @lythos/skill-deck@0.9.51 add mattpocock/skills@tdd
 
 # Or FQ locator:
-bunx @lythos/skill-deck@0.9.49 add github.com/anthropics/skills/skills/frontend-design
+bunx @lythos/skill-deck@0.9.51 add github.com/anthropics/skills/skills/frontend-design
 
 # Sync working set (deny-by-default):
-bunx @lythos/skill-deck@0.9.49 link
+bunx @lythos/skill-deck@0.9.51 link
 ```
 
 ## For AI Agents
@@ -25,7 +25,7 @@ bunx @lythos/skill-deck@0.9.49 link
 This package exposes a **CLI**. Invoke via:
 
 ```bash
-bunx @lythos/skill-deck@0.9.49 <command> [options]
+bunx @lythos/skill-deck@0.9.51 <command> [options]
 ```
 
 No installation required. `bunx` auto-downloads the package.
@@ -73,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.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` |
+| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.51 link` |
+| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.51 validate` |
+| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.51 add owner/repo` |
+| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.51 refresh` |
+| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.51 refresh tdd` |
+| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.51 remove tdd` |
+| Switch skill to symlink mode (live) | `bunx @lythos/skill-deck@0.9.51 to-symlink tdd` |
+| Switch skill to snapshot mode (pinned) | `bunx @lythos/skill-deck@0.9.51 to-snapshot tdd` |
+| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.51 link --deck ./my-deck.toml --workdir /path/to/project` |
 
 ### Commands
 
@@ -143,7 +143,7 @@ source = "https://github.com/lythos-labs/lythoskill/blob/HEAD/skills/lythoskill-
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/
-bunx @lythos/skill-deck@0.9.49 link
+bunx @lythos/skill-deck@0.9.51 link
 ```
 
 ### Key Concepts
@@ -229,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.49 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.51 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.49",
+  "version": "0.9.51",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
   "keywords": [
     "ai-agent",

package/src/add.test.ts

@@ -18,366 +18,126 @@ mock.module('node:os', () => ({
   homedir: () => mockHomeDir,
 }))
 
-let cleanup: string[] = []
-let execSpy: ReturnType<typeof spyOn> | null = null
+// ── findSkillDir ───────────────────────────────────────────────
 
-afterEach(() => {
-  if (execSpy) {
-    execSpy.mockRestore()
-    execSpy = null
-  }
-  for (const dir of cleanup) {
-    rmSync(dir, { recursive: true, force: true })
-  }
-  cleanup = []
-})
-
-function makeTmp(): string {
-  const dir = mkdtempSync(join(tmpdir(), 'deck-add-'))
-  cleanup.push(dir)
+function makeRepo(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'deck-skill-repo-'))
   return dir
 }
 
-function mockGitClone(fixturePath: string) {
-  const originalExec = childProcess.execFileSync
-  execSpy = spyOn(childProcess, 'execFileSync').mockImplementation(((cmd: string, args: string[], options?: any) => {
-    if (cmd === 'git' && args[0] === 'clone') {
-      const dest = args[args.length - 1]
-      cpSync(fixturePath, dest, { recursive: true })
-      return Buffer.from('')
-    }
-    return originalExec(cmd, args, options)
-  }) as any)
+function makeSkillDir(repo: string, skillName: string): string {
+  const d = join(repo, skillName)
+  mkdirSync(d, { recursive: true })
+  writeFileSync(join(d, 'SKILL.md'), `---\nname: ${skillName}\ndescription: test\n---\n\n# ${skillName}\n`)
+  return d
 }
 
-describe('addSkill', () => {
-  it('C6: add to empty project creates deck.toml and cold pool', async () => {
-    const projectDir = makeTmp()
-    mockHomeDir = projectDir
-
-    const fixtureDir = makeTmp()
-    writeFileSync(join(fixtureDir, 'SKILL.md'), '---\nname: test-skill\n---\n')
-
-    mockGitClone(fixtureDir)
-
-    // Dynamic import so add.ts picks up the mocked homedir()
-    const { addSkill } = await import('./add.ts')
-
-    await addSkill('github.com/owner/repo', { workdir: projectDir })
-
-    const deckPath = join(projectDir, 'skill-deck.toml')
-    expect(existsSync(deckPath)).toBe(true)
-
-    const deckContent = readFileSync(deckPath, 'utf-8')
-    expect(deckContent).toContain('[tool.skills.repo]')
-    expect(deckContent).toContain('path = "github.com/owner/repo"')
-
-    const coldPoolDir = join(projectDir, '.agents', 'skill-repos', 'github.com', 'owner', 'repo')
-    expect(existsSync(coldPoolDir)).toBe(true)
-    expect(existsSync(join(coldPoolDir, 'SKILL.md'))).toBe(true)
-  })
-
-  it('C7: add to existing deck appends entry', async () => {
-    const projectDir = makeTmp()
-    const coldPoolRel = 'cold-pool'
-    const coldPool = join(projectDir, coldPoolRel)
-    mkdirSync(coldPool, { recursive: true })
-
-    // Pre-place skill-a in cold pool
-    const skillADir = join(coldPool, 'github.com', 'owner', 'repo-a')
-    mkdirSync(skillADir, { recursive: true })
-    writeFileSync(join(skillADir, 'SKILL.md'), '---\nname: skill-a\n---\n')
-
-    // Create deck.toml with skill-a
-    const deckContent = `[deck]\nmax_cards = 10\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.skill-a]\npath = "github.com/owner/repo-a"\n`
-    const deckPath = join(projectDir, 'skill-deck.toml')
-    writeFileSync(deckPath, deckContent)
-
-    // Fixture for skill-b
-    const fixtureDir = makeTmp()
-    writeFileSync(join(fixtureDir, 'SKILL.md'), '---\nname: skill-b\n---\n')
-
-    mockGitClone(fixtureDir)
-
-    const { addSkill } = await import('./add.ts')
-    await addSkill('github.com/owner/repo-b', { workdir: projectDir, deck: deckPath })
-
-    const newContent = readFileSync(deckPath, 'utf-8')
-    expect(newContent).toContain('[tool.skills.skill-a]')
-    expect(newContent).toContain('path = "github.com/owner/repo-a"')
-    expect(newContent).toContain('[tool.skills.repo-b]')
-    expect(newContent).toContain('path = "github.com/owner/repo-b"')
-  })
-
-  it('C8: alias collision rejects', async () => {
-    const projectDir = makeTmp()
-    const coldPoolRel = 'cold-pool'
-    const coldPool = join(projectDir, coldPoolRel)
-    mkdirSync(coldPool, { recursive: true })
-
-    const deckContent = `[deck]\nmax_cards = 10\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.foo]\npath = "github.com/owner/repo-a"\n`
-    const deckPath = join(projectDir, 'skill-deck.toml')
-    writeFileSync(deckPath, deckContent)
-
-    const fixtureDir = makeTmp()
-    writeFileSync(join(fixtureDir, 'SKILL.md'), '---\nname: skill-b\n---\n')
-
-    mockGitClone(fixtureDir)
-
-    const errors: string[] = []
-    const errorSpy = spyOn(console, 'error').mockImplementation((msg: string) => {
-      errors.push(String(msg))
-    })
-
-    const originalExit = process.exit
-    let exitCode: number | undefined
-    process.exit = ((code?: number) => {
-      exitCode = code ?? 0
-      throw new Error(`EXIT:${code}`)
-    }) as typeof process.exit
-
-    try {
-      const { addSkill } = await import('./add.ts')
-      await addSkill('github.com/owner/repo-b', { workdir: projectDir, deck: deckPath, alias: 'foo' })
-      expect(false).toBe(true) // should not reach here
-    } catch (err: any) {
-      expect(exitCode).toBe(1)
-      expect(errors.some(e => e.includes('Alias "foo" already exists'))).toBe(true)
-    } finally {
-      process.exit = originalExit
-      errorSpy.mockRestore()
-    }
-  })
-
-  it('C9: invalid skill type rejects', async () => {
-    const projectDir = makeTmp()
-    const coldPoolRel = 'cold-pool'
-    const coldPool = join(projectDir, coldPoolRel)
-    mkdirSync(coldPool, { recursive: true })
-
-    const fixtureDir = makeTmp()
-    writeFileSync(join(fixtureDir, 'SKILL.md'), '---\nname: skill\n---\n')
-
-    const originalExec = childProcess.execFileSync
-    const execSpy = spyOn(childProcess, 'execFileSync').mockImplementation(((cmd: string, args: string[], options?: any) => {
-      if (cmd === 'git' && args[0] === 'clone') {
-        const dest = args[args.length - 1]
-        cpSync(fixtureDir, dest, { recursive: true })
-        return Buffer.from('')
-      }
-      return originalExec(cmd, args, options)
-    }) as any)
-
-    const errors: string[] = []
-    const errorSpy = spyOn(console, 'error').mockImplementation((msg: string) => {
-      errors.push(String(msg))
-    })
-
-    const originalExit = process.exit
-    let exitCode: number | undefined
-    process.exit = ((code?: number) => {
-      exitCode = code ?? 0
-      throw new Error(`EXIT:${code}`)
-    }) as typeof process.exit
-
-    try {
-      const { addSkill } = await import('./add.ts')
-      await addSkill('github.com/owner/repo', { deck: join(projectDir, 'skill-deck.toml'), workdir: projectDir, type: 'invalid' })
-      expect(false).toBe(true)
-    } catch (err: any) {
-      expect(exitCode).toBe(1)
-      expect(errors.some(e => e.includes('Invalid type'))).toBe(true)
-    } finally {
-      process.exit = originalExit
-      errorSpy.mockRestore()
-      execSpy.mockRestore()
-    }
-  })
-})
-
 describe('findSkillDir', () => {
-  function makeRepo(): string {
-    const dir = mkdtempSync(join(tmpdir(), 'deck-findskill-'))
-    cleanup.push(dir)
-    return dir
-  }
-
-  function placeSkill(repo: string, relPath: string): string {
-    const skillDir = join(repo, relPath)
-    mkdirSync(skillDir, { recursive: true })
-    writeFileSync(join(skillDir, 'SKILL.md'), '---\nname: fixture\n---\n')
-    return skillDir
-  }
-
-  it('returns repoPath for standalone skill (SKILL.md at repo root)', () => {
+  it('finds skill at repo root when SKILL.md exists', () => {
     const repo = makeRepo()
-    writeFileSync(join(repo, 'SKILL.md'), '---\nname: standalone\n---\n')
+    writeFileSync(join(repo, 'SKILL.md'), '---\nname: test\n---\n')
     expect(findSkillDir(repo, null)).toBe(repo)
+    rmSync(repo, { recursive: true, force: true })
   })
 
-  it('returns skills/ subdir when single skill exists there', () => {
-    const repo = makeRepo()
-    const expected = placeSkill(repo, 'skills/my-skill')
-    expect(findSkillDir(repo, null)).toBe(expected)
-  })
-
-  it('returns flat root dir when single skill exists at repo root', () => {
+  it('finds skill at skills/<name> when name provided', () => {
     const repo = makeRepo()
-    const expected = placeSkill(repo, 'my-skill')
-    expect(findSkillDir(repo, null)).toBe(expected)
-  })
-
-  it('returns null when multiple flat skills exist at repo root (ambiguous)', () => {
-    const repo = makeRepo()
-    placeSkill(repo, 'skill-a')
-    placeSkill(repo, 'skill-b')
-    expect(findSkillDir(repo, null)).toBeNull()
-  })
-
-  it('finds skill in skills/ subdir when skill name is provided', () => {
-    const repo = makeRepo()
-    const expected = placeSkill(repo, 'skills/my-skill')
-    expect(findSkillDir(repo, 'my-skill')).toBe(expected)
-  })
-
-  it('finds skill at repo root when skill name is provided (flat)', () => {
-    const repo = makeRepo()
-    const expected = placeSkill(repo, 'my-skill')
-    expect(findSkillDir(repo, 'my-skill')).toBe(expected)
-  })
-
-  it('returns null when skill name provided but not found anywhere', () => {
-    const repo = makeRepo()
-    expect(findSkillDir(repo, 'nonexistent')).toBeNull()
+    makeSkillDir(repo, 'skills/my-skill')
+    const found = findSkillDir(repo, 'skills/my-skill')
+    expect(found).toBe(join(repo, 'skills/my-skill'))
+    rmSync(repo, { recursive: true, force: true })
   })
 
   it('returns null when no SKILL.md exists anywhere in repo', () => {
     const repo = makeRepo()
     expect(findSkillDir(repo, null)).toBeNull()
+    rmSync(repo, { recursive: true, force: true })
   })
 })
 
-// ── skills.sh syntax sugar — top skills parse validation ────────
+// ── normalizeSkillsSh — skills.sh syntax sugar ─────────────────
 
 describe('normalizeSkillsSh', () => {
-  // FQ locators — must pass through unchanged
+  // FQ locators pass through
   it('passes FQ github.com locators through', () => {
-    expect(normalizeSkillsSh('github.com/anthropics/skills/skills/frontend-design'))
+    expect(normalizeSkillsSh('github.com/anthropics/skills/skills/frontend-design').fq)
       .toBe('github.com/anthropics/skills/skills/frontend-design')
-    expect(normalizeSkillsSh('github.com/vercel-labs/agent-skills'))
+    expect(normalizeSkillsSh('github.com/vercel-labs/agent-skills').fq)
       .toBe('github.com/vercel-labs/agent-skills')
   })
 
   it('passes localhost locators through', () => {
-    expect(normalizeSkillsSh('localhost/me/skill-a')).toBe('localhost/me/skill-a')
+    expect(normalizeSkillsSh('localhost/me/skill-a').fq).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')
-  })
+  const topSkills: Array<[string, string]> = [
+    ['vercel-labs/skills', 'github.com/vercel-labs/skills'],
+    ['vercel-labs/agent-skills', 'github.com/vercel-labs/agent-skills'],
+    ['anthropics/skills', 'github.com/anthropics/skills'],
+    ['obra/superpowers', 'github.com/obra/superpowers'],
+    ['browser-use/browser-use', 'github.com/browser-use/browser-use'],
+    ['firecrawl/cli', 'github.com/firecrawl/cli'],
+    ['apify/agent-skills', 'github.com/apify/agent-skills'],
+    ['squirrelscan/skills', 'github.com/squirrelscan/skills'],
+    ['getsentry/sentry-for-ai', 'github.com/getsentry/sentry-for-ai'],
+    ['coderabbitai/skills', 'github.com/coderabbitai/skills'],
+    ['openai/skills', 'github.com/openai/skills'],
+    ['google-gemini/gemini-cli', 'github.com/google-gemini/gemini-cli'],
+    ['coreyhaines31/marketingskills', 'github.com/coreyhaines31/marketingskills'],
+    ['jimliu/baoyu-skills', 'github.com/jimliu/baoyu-skills'],
+    ['astronomer/agents', 'github.com/astronomer/agents'],
+  ]
+
+  for (const [input, expected] of topSkills) {
+    it(`normalizes ${input}`, () => {
+      expect(normalizeSkillsSh(input).fq).toBe(expected)
+    })
+  }
 
-  it('normalizes astronmer/agents', () => {
-    expect(normalizeSkillsSh('astronomer/agents')).toBe('github.com/astronomer/agents')
+  // @skill syntax
+  it('preserves skillFilter from @skill syntax', () => {
+    const r = normalizeSkillsSh('vercel-labs/skills@find-skills')
+    expect(r.fq).toBe('github.com/vercel-labs/skills')
+    expect(r.skillFilter).toBe('find-skills')
   })
 
-  // 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'))
+  it('normalizes @skill with repo-level fq', () => {
+    expect(normalizeSkillsSh('mattpocock/skills@tdd').fq)
       .toBe('github.com/mattpocock/skills')
-    expect(normalizeSkillsSh('google-gemini/gemini-cli@code-reviewer'))
-      .toBe('github.com/google-gemini/gemini-cli')
   })
 
-  // owner/repo/subpath syntax
+  // subpath
   it('normalizes owner/repo/subpath', () => {
-    expect(normalizeSkillsSh('anthropics/skills/skills/frontend-design'))
+    expect(normalizeSkillsSh('anthropics/skills/skills/frontend-design').fq)
       .toBe('github.com/anthropics/skills/skills/frontend-design')
   })
 
   // github: prefix
   it('normalizes github:owner/repo', () => {
-    expect(normalizeSkillsSh('github:vercel-labs/agent-skills'))
+    expect(normalizeSkillsSh('github:vercel-labs/agent-skills').fq)
       .toBe('github.com/vercel-labs/agent-skills')
   })
 
-  // #ref suffix (branch/tag/commit) — compatible with skills.sh parseFragmentRef
+  // #ref suffix
   it('preserves #ref with FQ locator', () => {
-    expect(normalizeSkillsSh('github.com/vercel-labs/skills#main'))
+    expect(normalizeSkillsSh('github.com/vercel-labs/skills#main').fq)
       .toBe('github.com/vercel-labs/skills#main')
   })
 
   it('preserves #ref with owner/repo shorthand', () => {
-    expect(normalizeSkillsSh('vercel-labs/skills#v2.0'))
+    expect(normalizeSkillsSh('vercel-labs/skills#v2.0').fq)
       .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')
+    const r = normalizeSkillsSh('vercel-labs/skills#main@find-skills')
+    expect(r.fq).toBe('github.com/vercel-labs/skills#main')
+    expect(r.skillFilter).toBe('find-skills')
   })
 
   it('preserves #ref with subpath', () => {
-    expect(normalizeSkillsSh('anthropics/skills/skills/frontend-design#abc1234'))
+    expect(normalizeSkillsSh('anthropics/skills/skills/frontend-design#abc1234').fq)
       .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

@@ -61,6 +61,30 @@ export function findSkillDir(repoPath: string, skill: string | null): string | n
   return null
 }
 
+/** Find a skill directory by name within a cloned repo (for @skill syntax). */
+function findSkillByName(repoPath: string, name: string): string | null {
+  try {
+    const entries = readdirSync(repoPath, { withFileTypes: true, recursive: true })
+    // First pass: match by frontmatter name:
+    for (const e of entries) {
+      if (!e.isFile() || e.name !== 'SKILL.md') continue
+      const dir = e.parentPath ?? dirname(join(repoPath, e.name))
+      try {
+        const content = readFileSync(join(dir, 'SKILL.md'), 'utf-8')
+        const fmMatch = content.match(/^---\s*\nname:\s*(.+)$/m)
+        if (fmMatch && fmMatch[1].trim() === name) return dir
+      } catch {}
+    }
+    // Second pass: fall back to directory name (skills.sh convention — dir name ≠ frontmatter name)
+    for (const e of entries) {
+      if (!e.isFile() || e.name !== 'SKILL.md') continue
+      const dir = e.parentPath ?? dirname(join(repoPath, e.name))
+      if (basename(dir) === name) return dir
+    }
+  } catch {}
+  return null
+}
+
 function resolvePath(p: string): string {
   if (p.startsWith('~/')) return join(homedir(), p.slice(2))
   return resolve(p)
@@ -89,12 +113,16 @@ function fqOf(loc: Locator): string {
  *   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
+export interface NormalizedLocator {
+  fq: string        // FQ locator for clone + parseLocator
+  skillFilter?: string  // from @skill suffix — match by name after clone
+}
+
+export function normalizeSkillsSh(input: string): NormalizedLocator {
+  // localhost: always pass through
+  if (input.startsWith('localhost/')) return { fq: 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
+  // Extract #ref suffix
   let ref = ''
   let base = input
   const hashIdx = input.indexOf('#')
@@ -106,38 +134,44 @@ export function normalizeSkillsSh(input: string): string {
       ref = `#${afterHash.slice(0, atInRef)}`
       base = `${base}@${afterHash.slice(atInRef + 1)}`
     } else {
-      ref = input.slice(hashIdx) // includes '#'
+      ref = input.slice(hashIdx)
     }
   }
 
-  // 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
+  // Already an FQ locator
+  if (base.match(/^[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\/.+\/.+/)) return { fq: input }
 
-  // github: prefix
+  // github: prefix — extract @skill from remainder before building FQ
   const ghPrefix = base.match(/^github:(.+)$/)
-  if (ghPrefix) return `github.com/${ghPrefix[1]}${ref}`
+  if (ghPrefix) {
+    const rest = ghPrefix[1]
+    const atInGh = rest.match(/^([^/]+)\/([^/@]+)@(.+)$/)
+    if (atInGh) {
+      const [, owner, repo, skill] = atInGh
+      return { fq: `github.com/${owner}/${repo}${ref}`, skillFilter: skill }
+    }
+    return { fq: `github.com/${rest}${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/.
+  // owner/repo@skill — clone repo-level, discover exact path at runtime
   const atMatch = base.match(/^([^/]+)\/([^/@]+)@(.+)$/)
   if (atMatch && !base.includes(':') && !base.startsWith('.')) {
-    const [, owner, repo] = atMatch
-    return `github.com/${owner}/${repo}${ref}`
+    const [, owner, repo, skill] = atMatch
+    return { fq: `github.com/${owner}/${repo}${ref}`, skillFilter: skill }
   }
 
-  // owner/repo[/subpath] shorthand (no dot in first segment → not a hostname)
+  // owner/repo[/subpath]
   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 {
+      fq: subpath
+        ? `github.com/${owner}/${repo}/${subpath}${ref}`
+        : `github.com/${owner}/${repo}${ref}`,
+    }
   }
 
-  return input
+  return { fq: input }
 }
 
 function exitInvalidLocator(locator: string): never {
@@ -165,9 +199,9 @@ export async function addSkill(
     ? resolvePath(options.deck)
     : findDeckToml(workdir) || join(workdir, 'skill-deck.toml')
 
-  const normalized = normalizeSkillsSh(locator)
-  const parsed = parseLocator(normalized)
-  if (!parsed) exitInvalidLocator(normalized)
+  const { fq, skillFilter } = normalizeSkillsSh(locator)
+  let parsed = parseLocator(fq)
+  if (!parsed) exitInvalidLocator(fq)
 
   if (parsed.isLocalhost) {
     console.error(`❌ deck add does not support localhost locators (no remote to clone).`)
@@ -178,15 +212,13 @@ export async function addSkill(
   const coldPoolPath = resolveColdPoolPath(deckPath, workdir)
   const pool = new ColdPool(coldPoolPath)
   const fetchPlan = buildFetchPlan(pool, parsed)
-  const fqPath = fqOf(parsed)
   const skillName = parsed.skill ? basename(parsed.skill) : parsed.repo!
-  const rawAlias = options.alias || skillName
+  let 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)) {
@@ -194,6 +226,7 @@ export async function addSkill(
     process.exit(1)
   }
 
+  const fqPathBefore = fqOf(parsed) // pre-discovery — may be repo-level for @skill
   if (dryRun) {
     console.log(`🔎 Dry-run: deck add ${locator}`)
     console.log(`   Cold pool:  ${coldPoolPath}`)
@@ -218,7 +251,7 @@ export async function addSkill(
     }
     console.log(`\n📝 Would add to skill-deck.toml:`)
     console.log(`   [${skillType}.skills.${alias}]`)
-    console.log(`   path = "${fqPath}"`)
+    console.log(`   path = "${fqPathBefore}"`)
     console.log(`\n💡 Remove --dry-run to execute.`)
     return
   }
@@ -254,7 +287,16 @@ export async function addSkill(
     console.log(`   (per ADR-20260507110332805, refresh defaults to discover-only)`)
   }
 
-  const skillDir = findSkillDir(fetchPlan.targetDir, parsed.skill)
+  const skillDir = findSkillDir(fetchPlan.targetDir, parsed.skill || null)
+    ?? (skillFilter ? findSkillByName(fetchPlan.targetDir, skillFilter) : null)
+  if (skillDir && skillFilter) {
+    // If discovered by name, update skill path and alias
+    const relPath = skillDir.slice(fetchPlan.targetDir.length + 1)
+    parsed = { ...parsed, skill: relPath }
+    if (!options.alias) rawAlias = basename(relPath)  // use discovered dir name as alias
+  }
+  const fqPath = fqOf(parsed)  // may be updated after @skill discovery
+  const alias = rawAlias       // finalized after potential @skill override
   if (!skillDir) {
     console.error(`❌ No SKILL.md found in downloaded repo`)
     console.error(`   Checked: ${fetchPlan.targetDir}`)