@skilldeck/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kitasid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @skilldeck/core
+
+The installer library behind [`@skilldeck/cli`](https://www.npmjs.com/package/@skilldeck/cli) and every SkillDeck pack. Use it to ship your own SKILL.md pack as an npm package.
+
+```js
+import { install, uninstall, status, runPackCli } from '@skilldeck/core'
+
+const pack = {
+  name: 'my-pack',
+  version: '1.0.0',
+  root: '/abs/path/to/package',          // contains skills/<name>/SKILL.md
+  skills: ['my-skill'],
+  hook: {                                 // optional, Claude Code only
+    event: 'SessionStart',
+    matcher: 'startup|clear|compact',
+    script: 'hooks/session-start',
+    include: ['hooks/session-start'],     // copied to ~/.claude/skilldeck/my-pack/
+  },
+}
+
+install(pack, { agent: 'claude', project: false })   // or agent: 'all'
+uninstall('my-pack', { agent: 'claude' })
+status()
+```
+
+For a ready-made `install | uninstall | status` CLI, call `await runPackCli(pack, process.argv.slice(2))` from your package's bin.
+
+Behaviour:
+- Existing folders SkillDeck didn't create are never overwritten without `force`.
+- Hooks are merged into `settings.json` idempotently, and the file is backed up first.
+- Hook and script files are made executable after copying.
+- Options `home` and `cwd` override the target locations (useful in tests).
+
+MIT licensed. Node 20+.

package/index.mjs

@@ -0,0 +1,5 @@
+export { install, uninstall, status } from './lib/install.mjs'
+export { AGENTS, expandAgents, resolveTarget } from './lib/targets.mjs'
+export { addHook, removeHook } from './lib/settings.mjs'
+export { readManifest, MANIFEST } from './lib/manifest.mjs'
+export { runPackCli, parse, toOpts, printInstall, printUninstall, printStatus, OPTIONS_HELP, bold, dim, green, red, yellow } from './lib/cli.mjs'

package/lib/cli.mjs

@@ -0,0 +1,100 @@
+import os from 'node:os'
+import path from 'node:path'
+import { parseArgs } from 'node:util'
+import { install, status, uninstall } from './install.mjs'
+
+export const COMMON_OPTIONS = {
+  agent: { type: 'string', short: 'a', default: 'claude' },
+  project: { type: 'boolean', short: 'p', default: false },
+  force: { type: 'boolean', short: 'f', default: false },
+  'dry-run': { type: 'boolean', default: false },
+  help: { type: 'boolean', short: 'h', default: false },
+  version: { type: 'boolean', short: 'v', default: false },
+}
+
+export const OPTIONS_HELP = `Options:
+  -a, --agent <name>   claude (default), codex, agents, all, or a comma list
+  -p, --project        install into ./.claude (or ./.codex, ./.agents) instead of your home
+  -f, --force          replace skill folders that SkillDeck didn't install
+      --dry-run        show what would happen without writing anything
+  -h, --help           show help
+  -v, --version        show version`
+
+const c = process.stdout.isTTY && !process.env.NO_COLOR
+const paint = (code) => (s) => (c ? `\x1b[${code}m${s}\x1b[0m` : String(s))
+export const dim = paint(2)
+export const bold = paint(1)
+export const green = paint(32)
+export const yellow = paint(33)
+export const red = paint(31)
+
+const tilde = (p) => (p.startsWith(os.homedir()) ? '~' + p.slice(os.homedir().length) : p)
+
+export function parse(argv, extra = {}) {
+  return parseArgs({ args: argv, options: { ...COMMON_OPTIONS, ...extra }, allowPositionals: true, strict: true })
+}
+
+export function toOpts(values) {
+  return { agent: values.agent, project: values.project, force: values.force, dryRun: values['dry-run'] }
+}
+
+export function printInstall(pack, results) {
+  for (const r of results) {
+    const verb = r.dryRun ? 'would install' : r.upgraded ? 'updated' : 'installed'
+    console.log(`${green('✓')} ${bold(pack.name)}@${pack.version} ${verb} for ${r.label} ${dim('→ ' + tilde(r.skillsDir))}`)
+    console.log(dim(`  skills: ${r.skills.join(', ')}`))
+    if (r.hook) console.log(dim(`  hook:   ${r.hook.event} in ${tilde(r.hook.settingsFile)}`))
+    if (r.note) console.log(yellow(`  note:   ${r.note}`))
+  }
+}
+
+export function printUninstall(name, results) {
+  for (const r of results) {
+    if (r.removed) console.log(`${green('✓')} removed ${bold(name)} from ${r.label}${r.hook ? dim(' (and its hook)') : ''}`)
+    else console.log(dim(`- ${name} is not installed for ${r.label}`))
+  }
+}
+
+export function printStatus(rows) {
+  if (rows.length === 0) {
+    console.log(dim('No SkillDeck packs installed yet.'))
+    return
+  }
+  for (const r of rows) {
+    if (r.error) console.log(red(`! ${r.label}: ${r.error}`))
+    else console.log(`${bold(r.pack)}@${r.version}  ${r.label}${r.hook ? ' + hook' : ''}  ${dim(tilde(r.skillsDir))}`)
+  }
+}
+
+/** Standard `install | uninstall | status` CLI for a single pack. `extra` adds pack-specific commands. */
+export async function runPackCli(pack, argv, { extraCommands = {}, extraHelp = '' } = {}) {
+  const [cmd, ...rest] = argv
+  const bin = path.basename(process.argv[1] ?? pack.name).replace(/\.mjs$/, '')
+  const help = `${bold(pack.name)} ${pack.version}
+
+Usage:
+  npx @skilldeck/${pack.name} install [options]     install the skills for your agent
+  npx @skilldeck/${pack.name} uninstall [options]   remove them again
+  npx @skilldeck/${pack.name} status                show where they're installed
+${extraHelp}
+${OPTIONS_HELP}`
+
+  try {
+    if (extraCommands[cmd]) return await extraCommands[cmd](rest)
+    if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') return void console.log(help)
+    if (cmd === '--version' || cmd === '-v') return void console.log(pack.version)
+    const { values } = parse(rest)
+    if (values.help) return void console.log(help)
+    const opts = toOpts(values)
+    if (cmd === 'install') printInstall(pack, install(pack, opts))
+    else if (cmd === 'uninstall' || cmd === 'remove') printUninstall(pack.name, uninstall(pack.name, opts))
+    else if (cmd === 'status') printStatus(status(opts).filter((r) => r.pack === pack.name || r.error))
+    else {
+      console.error(red(`Unknown command "${cmd}".`) + ` Run ${bin} --help.`)
+      process.exitCode = 1
+    }
+  } catch (e) {
+    console.error(red('✗ ') + e.message)
+    process.exitCode = 1
+  }
+}

package/lib/copy.mjs

@@ -0,0 +1,18 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+const EXECUTABLE = (rel) => /(^|\/)hooks\/[^/.]+$/.test(rel) || /(^|\/)(scripts|bin)\/[^/]+\.(mjs|js|sh)$/.test(rel)
+
+/** Recursive copy that also restores the executable bit on hooks and scripts (tarballs can drop it). */
+export function copyTree(src, dst) {
+  fs.cpSync(src, dst, { recursive: true, force: true })
+  const walk = (dir) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, e.name)
+      if (e.isDirectory()) walk(p)
+      else if (EXECUTABLE(path.relative(path.dirname(dst), p).split(path.sep).join('/'))) fs.chmodSync(p, 0o755)
+    }
+  }
+  if (fs.statSync(dst).isDirectory()) walk(dst)
+  else if (EXECUTABLE(src.split(path.sep).join('/'))) fs.chmodSync(dst, 0o755)
+}

package/lib/install.mjs

@@ -0,0 +1,128 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { copyTree } from './copy.mjs'
+import { ownerOf, readManifest, writeManifest } from './manifest.mjs'
+import { addHook, removeHook } from './settings.mjs'
+import { AGENTS, expandAgents, resolveTarget } from './targets.mjs'
+
+/**
+ * A pack describes itself as:
+ *   { name, version, root, skills: string[],
+ *     hook?: { event, matcher, script, include: string[] } }   // paths relative to root
+ */
+
+function hookCommandFor(target, pack) {
+  return target.hookCommand(`${pack.name}/${pack.hook.script}`)
+}
+
+/** Install a pack for each requested agent. Throws before writing anything if a conflict is found. */
+export function install(pack, opts = {}) {
+  const { force = false, dryRun = false } = opts
+  const agents = expandAgents(opts.agent)
+  const plans = agents.map((agent) => {
+    const target = resolveTarget(agent, opts)
+    const manifest = readManifest(target.skillsDir)
+    const conflicts = pack.skills.filter((s) => {
+      const owner = ownerOf(manifest, s)
+      return owner !== pack.name && (owner || fs.existsSync(path.join(target.skillsDir, s)))
+    })
+    return { target, manifest, conflicts }
+  })
+
+  const blocked = plans.filter((p) => p.conflicts.length)
+  if (blocked.length && !force) {
+    const lines = blocked.map((p) => `  ${p.target.label}: ${p.conflicts.map((c) => path.join(p.target.skillsDir, c)).join(', ')}`)
+    throw new Error(`These skill folders already exist and weren't installed by ${pack.name}:\n${lines.join('\n')}\nRe-run with --force to replace them.`)
+  }
+
+  return plans.map(({ target, manifest }) => {
+    const previous = manifest.packs[pack.name]
+    const result = { agent: target.agent, label: target.label, skillsDir: target.skillsDir, skills: pack.skills, hook: null, upgraded: Boolean(previous), dryRun }
+
+    if (!dryRun) {
+      for (const skill of pack.skills) {
+        const dst = path.join(target.skillsDir, skill)
+        fs.rmSync(dst, { recursive: true, force: true })
+        fs.mkdirSync(target.skillsDir, { recursive: true })
+        copyTree(path.join(pack.root, 'skills', skill), dst)
+      }
+      // Drop skills a previous version shipped but this one doesn't.
+      for (const old of previous?.skills ?? []) {
+        if (!pack.skills.includes(old)) fs.rmSync(path.join(target.skillsDir, old), { recursive: true, force: true })
+      }
+    }
+
+    const entry = { version: pack.version, skills: pack.skills, installedAt: new Date().toISOString() }
+
+    if (pack.hook && target.hooks) {
+      const hookDir = path.join(target.hookRoot, pack.name)
+      const command = hookCommandFor(target, pack)
+      if (!dryRun) {
+        fs.rmSync(hookDir, { recursive: true, force: true })
+        for (const rel of pack.hook.include) {
+          const dst = path.join(hookDir, rel)
+          fs.mkdirSync(path.dirname(dst), { recursive: true })
+          copyTree(path.join(pack.root, rel), dst)
+        }
+        addHook(target.settingsFile, { event: pack.hook.event, matcher: pack.hook.matcher, command })
+      }
+      entry.hook = { event: pack.hook.event, command, dir: hookDir, settingsFile: target.settingsFile }
+      result.hook = entry.hook
+    } else if (pack.hook) {
+      result.note = `${target.label} has no hook system: skills installed, but the session-start bootstrap won't run automatically.`
+    }
+
+    if (!dryRun) {
+      manifest.packs[pack.name] = entry
+      writeManifest(target.skillsDir, manifest)
+    }
+    return result
+  })
+}
+
+/** Remove exactly what the manifest says this pack installed. */
+export function uninstall(packName, opts = {}) {
+  const agents = expandAgents(opts.agent)
+  return agents.map((agent) => {
+    const target = resolveTarget(agent, opts)
+    const manifest = readManifest(target.skillsDir)
+    const entry = manifest.packs[packName]
+    if (!entry) return { agent, label: target.label, removed: false }
+    if (!opts.dryRun) {
+      for (const s of entry.skills ?? []) fs.rmSync(path.join(target.skillsDir, s), { recursive: true, force: true })
+      if (entry.hook) {
+        removeHook(entry.hook.settingsFile, { event: entry.hook.event, command: entry.hook.command })
+        fs.rmSync(entry.hook.dir, { recursive: true, force: true })
+        const parent = path.dirname(entry.hook.dir)
+        if (fs.existsSync(parent) && fs.readdirSync(parent).length === 0) fs.rmdirSync(parent)
+      }
+      delete manifest.packs[packName]
+      writeManifest(target.skillsDir, manifest)
+    }
+    return { agent, label: target.label, removed: true, skills: entry.skills, hook: entry.hook ?? null }
+  })
+}
+
+/** Installed packs per agent target, for both user and project scope. */
+export function status(opts = {}) {
+  const rows = []
+  const seen = new Set()
+  for (const project of [false, true]) {
+    for (const agent of AGENTS) {
+      const target = resolveTarget(agent, { ...opts, project })
+      if (seen.has(target.skillsDir)) continue
+      seen.add(target.skillsDir)
+      let manifest
+      try {
+        manifest = readManifest(target.skillsDir)
+      } catch (e) {
+        rows.push({ agent, label: target.label, skillsDir: target.skillsDir, error: e.message })
+        continue
+      }
+      for (const [name, entry] of Object.entries(manifest.packs)) {
+        rows.push({ agent, label: target.label, skillsDir: target.skillsDir, pack: name, version: entry.version, skills: entry.skills, hook: Boolean(entry.hook) })
+      }
+    }
+  }
+  return rows
+}

package/lib/manifest.mjs

@@ -0,0 +1,32 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const MANIFEST = '.skilldeck.json'
+
+/** Per-skills-directory record of what SkillDeck installed, so removal touches nothing else. */
+export function readManifest(skillsDir) {
+  const file = path.join(skillsDir, MANIFEST)
+  if (!fs.existsSync(file)) return { packs: {} }
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return data && typeof data.packs === 'object' ? data : { packs: {} }
+  } catch {
+    throw new Error(`${file} is not valid JSON. Fix or delete it, then retry.`)
+  }
+}
+
+export function writeManifest(skillsDir, manifest) {
+  const file = path.join(skillsDir, MANIFEST)
+  if (Object.keys(manifest.packs).length === 0) {
+    fs.rmSync(file, { force: true })
+    return
+  }
+  fs.mkdirSync(skillsDir, { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(manifest, null, 2) + '\n')
+}
+
+/** Which pack (if any) owns a skill directory name. */
+export function ownerOf(manifest, skill) {
+  for (const [name, entry] of Object.entries(manifest.packs)) if (entry.skills?.includes(skill)) return name
+  return null
+}

package/lib/settings.mjs

@@ -0,0 +1,53 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+function read(file) {
+  if (!fs.existsSync(file)) return {}
+  const text = fs.readFileSync(file, 'utf8')
+  if (!text.trim()) return {}
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Error(`${file} is not valid JSON; refusing to modify it. Fix it and retry.`)
+  }
+}
+
+function write(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  if (fs.existsSync(file)) fs.copyFileSync(file, file + '.bak')
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n')
+}
+
+const hasCommand = (entry, command) => entry?.hooks?.some((h) => h.command === command)
+
+/** Add a command hook for `event`. Idempotent: keyed on the exact command string. Returns true if written. */
+export function addHook(file, { event, matcher, command, timeout = 10 }) {
+  const settings = read(file)
+  settings.hooks ??= {}
+  settings.hooks[event] ??= []
+  if (settings.hooks[event].some((e) => hasCommand(e, command))) return false
+  settings.hooks[event].push({ matcher, hooks: [{ type: 'command', command, timeout }] })
+  write(file, settings)
+  return true
+}
+
+/** Remove every hook whose command matches, pruning empty entries. Returns true if written. */
+export function removeHook(file, { event, command }) {
+  if (!fs.existsSync(file)) return false
+  const settings = read(file)
+  const list = settings.hooks?.[event]
+  if (!Array.isArray(list) || !list.some((e) => hasCommand(e, command))) return false
+  settings.hooks[event] = list
+    .map((e) => ({ ...e, hooks: (e.hooks ?? []).filter((h) => h.command !== command) }))
+    .filter((e) => e.hooks.length > 0)
+  if (settings.hooks[event].length === 0) delete settings.hooks[event]
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks
+  // Nothing left but what we added: remove the file rather than leave an empty `{}` behind.
+  if (Object.keys(settings).length === 0) {
+    fs.copyFileSync(file, file + '.bak')
+    fs.rmSync(file)
+    return true
+  }
+  write(file, settings)
+  return true
+}

package/lib/targets.mjs

@@ -0,0 +1,42 @@
+import os from 'node:os'
+import path from 'node:path'
+
+export const AGENTS = ['claude', 'codex', 'agents']
+
+/**
+ * Where a given agent looks for skills, and whether it supports hooks.
+ * `project` scopes everything to `cwd` instead of the user's home.
+ */
+export function resolveTarget(agent, { home = os.homedir(), cwd = process.cwd(), project = false } = {}) {
+  const base = project ? cwd : home
+  switch (agent) {
+    case 'claude':
+      return {
+        agent,
+        label: project ? 'Claude Code (project)' : 'Claude Code',
+        skillsDir: path.join(base, '.claude', 'skills'),
+        hooks: true,
+        settingsFile: path.join(base, '.claude', 'settings.json'),
+        hookRoot: path.join(base, '.claude', 'skilldeck'),
+        // Project installs reference $CLAUDE_PROJECT_DIR so the checked-in settings work on every machine.
+        hookCommand: (rel) =>
+          project ? `"$CLAUDE_PROJECT_DIR"/.claude/skilldeck/${rel}` : `"${path.join(base, '.claude', 'skilldeck', rel)}"`,
+      }
+    case 'codex':
+      return { agent, label: project ? 'Codex (project)' : 'Codex', skillsDir: path.join(base, '.codex', 'skills'), hooks: false }
+    case 'agents':
+      return { agent, label: project ? '.agents (project)' : '.agents', skillsDir: path.join(base, '.agents', 'skills'), hooks: false }
+    default:
+      throw new Error(`Unknown agent "${agent}". Use one of: ${AGENTS.join(', ')}, all`)
+  }
+}
+
+export function expandAgents(value = 'claude') {
+  const list = String(value)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+  if (list.includes('all')) return [...AGENTS]
+  for (const a of list) if (!AGENTS.includes(a)) throw new Error(`Unknown agent "${a}". Use one of: ${AGENTS.join(', ')}, all`)
+  return [...new Set(list)]
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@skilldeck/core",
+  "version": "0.1.0",
+  "description": "Installer library for SkillDeck skill packs: copies SKILL.md folders into Claude Code, Codex or .agents and wires hooks.",
+  "type": "module",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "main": "./index.mjs",
+  "files": [
+    "index.mjs",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "agent-skills",
+    "skill-md",
+    "installer"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "kitasid"
+}