skills-package-manager 0.1.1

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "skills-package-manager",
+  "version": "0.1.1",
+  "type": "module",
+  "bin": {
+    "skills-pm": "dist/bin/skills-pm.js",
+    "skills": "dist/bin/skills.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@rslib/core": "^0.20.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.0"
+  },
+  "scripts": {
+    "build": "rslib build"
+  }
+}

package/rslib.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from '@rslib/core'
+
+export default defineConfig({
+  lib: [
+    {
+      format: 'esm',
+      dts: true,
+      source: {
+        entry: {
+          index: './src/index.ts',
+          'bin/skills-pm': './src/bin/skills-pm.ts',
+          'bin/skills': './src/bin/skills.ts',
+        },
+      },
+      output: {
+        target: 'node',
+        cleanDistPath: true,
+      },
+    },
+  ],
+})

package/src/bin/skills-pm.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from '../cli/runCli'
+
+runCli(process.argv).catch((error) => {
+  console.error(error instanceof Error ? error.message : error)
+  process.exitCode = 1
+})

package/src/bin/skills.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from '../cli/runCli'
+
+runCli(process.argv).catch((error) => {
+  console.error(error instanceof Error ? error.message : error)
+  process.exitCode = 1
+})

package/src/cli/prompt.ts

@@ -0,0 +1,36 @@
+import * as p from '@clack/prompts'
+import type { SkillInfo } from '../github/types'
+
+export async function promptSkillSelection(skills: SkillInfo[]): Promise<SkillInfo[]> {
+  if (skills.length === 0) {
+    throw new Error('No skills found in repository')
+  }
+
+  // Single skill — auto-select
+  if (skills.length === 1) {
+    return skills
+  }
+
+  const options = skills.map((skill) => ({
+    value: skill,
+    label: skill.name,
+    hint: skill.description
+      ? skill.description.length > 60
+        ? `${skill.description.slice(0, 57)}...`
+        : skill.description
+      : undefined,
+  }))
+
+  const selected = await p.multiselect({
+    message: 'Select skills to install',
+    options,
+    required: true,
+  })
+
+  if (p.isCancel(selected)) {
+    p.cancel('Installation cancelled')
+    process.exit(0)
+  }
+
+  return selected as SkillInfo[]
+}

package/src/cli/runCli.ts

@@ -0,0 +1,45 @@
+import { addCommand } from '../commands/add'
+import { installCommand } from '../commands/install'
+
+function parseArgs(args: string[]): { positionals: string[]; flags: Record<string, string> } {
+  const positionals: string[] = []
+  const flags: Record<string, string> = {}
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2)
+      const next = args[i + 1]
+      if (next && !next.startsWith('--')) {
+        flags[key] = next
+        i++
+      } else {
+        flags[key] = 'true'
+      }
+    } else {
+      positionals.push(arg)
+    }
+  }
+
+  return { positionals, flags }
+}
+
+export async function runCli(argv: string[]) {
+  const [, , command, ...rest] = argv
+  const cwd = process.cwd()
+
+  if (command === 'add') {
+    const { positionals, flags } = parseArgs(rest)
+    const specifier = positionals[0]
+    if (!specifier) {
+      throw new Error('Missing required specifier')
+    }
+    return addCommand({ cwd, specifier, skill: flags.skill })
+  }
+
+  if (command === 'install') {
+    return installCommand({ cwd })
+  }
+
+  throw new Error(`Unknown command: ${command}`)
+}

package/src/commands/add.ts

@@ -0,0 +1,110 @@
+import * as p from '@clack/prompts'
+import pc from 'picocolors'
+import { readSkillsLock } from '../config/readSkillsLock'
+import { readSkillsManifest } from '../config/readSkillsManifest'
+import { syncSkillsLock } from '../config/syncSkillsLock'
+import { writeSkillsLock } from '../config/writeSkillsLock'
+import { writeSkillsManifest } from '../config/writeSkillsManifest'
+import type { AddCommandOptions } from '../config/types'
+import { normalizeSpecifier } from '../specifiers/normalizeSpecifier'
+import { listRepoSkills, parseOwnerRepo, parseGitHubUrl } from '../github/listSkills'
+import { promptSkillSelection } from '../cli/prompt'
+
+function isProtocolSpecifier(specifier: string): boolean {
+  return /^[a-z]+:/.test(specifier)
+}
+
+function buildGitHubSpecifier(owner: string, repo: string, skillPath: string): string {
+  return `https://github.com/${owner}/${repo}.git#path:${skillPath}`
+}
+
+async function addSingleSkill(
+  cwd: string,
+  specifier: string,
+): Promise<{ skillName: string; specifier: string }> {
+  const normalized = normalizeSpecifier(specifier)
+  const existingManifest = (await readSkillsManifest(cwd)) ?? {
+    installDir: '.agents/skills',
+    linkTargets: [],
+    skills: {},
+  }
+
+  const existing = existingManifest.skills[normalized.skillName]
+  if (existing && existing !== normalized.normalized) {
+    throw new Error(`Skill ${normalized.skillName} already exists with a different specifier`)
+  }
+
+  existingManifest.skills[normalized.skillName] = normalized.normalized
+  await writeSkillsManifest(cwd, existingManifest)
+
+  const existingLock = await readSkillsLock(cwd)
+  const lockfile = await syncSkillsLock(cwd, existingManifest, existingLock)
+  await writeSkillsLock(cwd, lockfile)
+
+  return {
+    skillName: normalized.skillName,
+    specifier: normalized.normalized,
+  }
+}
+
+export async function addCommand(options: AddCommandOptions) {
+  const { cwd, specifier, skill } = options
+
+  // Try owner/repo shorthand first
+  const shorthand = parseOwnerRepo(specifier)
+  // Try GitHub URL (https://github.com/owner/repo)
+  const githubUrl = !shorthand ? parseGitHubUrl(specifier) : null
+  const parsed = shorthand ?? githubUrl
+
+  if (parsed) {
+    const { owner, repo } = parsed
+    const source = `${owner}/${repo}`
+
+    p.intro(pc.bgCyan(pc.black(' skills-pm ')))
+
+    const spinner = p.spinner()
+
+    // --skill flag provided — non-interactive, need to discover path
+    if (skill) {
+      spinner.start(`Cloning ${source}...`)
+      const skills = await listRepoSkills(owner, repo)
+      spinner.stop(`Found ${pc.green(String(skills.length))} skill${skills.length !== 1 ? 's' : ''}`)
+
+      const found = skills.find((s) => s.name === skill)
+      const skillPath = found?.path ?? `/${skill}`
+      const gitSpecifier = buildGitHubSpecifier(owner, repo, skillPath)
+      const result = await addSingleSkill(cwd, gitSpecifier)
+      p.outro(`Added ${pc.cyan(result.skillName)}`)
+      return result
+    }
+
+    // Interactive — clone, discover, prompt
+    spinner.start(`Cloning ${source}...`)
+    const skills = await listRepoSkills(owner, repo)
+
+    if (skills.length === 0) {
+      spinner.stop(pc.red('No skills found'))
+      p.outro(pc.red(`No valid skills found in ${source}`))
+      throw new Error(`No skills found in ${source}`)
+    }
+
+    spinner.stop(`Found ${pc.green(String(skills.length))} skill${skills.length !== 1 ? 's' : ''}`)
+
+    const selected = await promptSkillSelection(skills)
+    const results: { skillName: string; specifier: string }[] = []
+
+    for (const s of selected) {
+      const gitSpecifier = buildGitHubSpecifier(owner, repo, s.path)
+      const result = await addSingleSkill(cwd, gitSpecifier)
+      results.push(result)
+      p.log.success(`Added ${pc.cyan(result.skillName)}`)
+    }
+
+    p.outro('Done')
+    return results.length === 1 ? results[0] : results
+  }
+
+  // Protocol specifier (file:, npm:, git URL with fragment, etc.) — direct add
+  return addSingleSkill(cwd, specifier)
+}
+

package/src/commands/install.ts

@@ -0,0 +1,5 @@
+import { installSkills } from '../install/installSkills'
+
+export async function installCommand(options: { cwd: string }) {
+  return installSkills(options.cwd)
+}

package/src/config/readSkillsLock.ts

@@ -0,0 +1,18 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import YAML from 'yaml'
+import type { SkillsLock } from './types'
+
+export async function readSkillsLock(rootDir: string): Promise<SkillsLock | null> {
+  const filePath = path.join(rootDir, 'skills-lock.yaml')
+
+  try {
+    const raw = await readFile(filePath, 'utf8')
+    return YAML.parse(raw) as SkillsLock
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null
+    }
+    throw error
+  }
+}

package/src/config/readSkillsManifest.ts

@@ -0,0 +1,22 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import type { SkillsManifest } from './types'
+
+export async function readSkillsManifest(rootDir: string): Promise<SkillsManifest | null> {
+  const filePath = path.join(rootDir, 'skills.json')
+
+  try {
+    const raw = await readFile(filePath, 'utf8')
+    const json = JSON.parse(raw) as SkillsManifest
+    return {
+      installDir: json.installDir ?? '.agents/skills',
+      linkTargets: json.linkTargets ?? [],
+      skills: json.skills ?? {},
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null
+    }
+    throw error
+  }
+}

package/src/config/syncSkillsLock.ts

@@ -0,0 +1,75 @@
+import type { SkillsLock, SkillsLockEntry, SkillsManifest } from './types'
+import { normalizeSpecifier } from '../specifiers/normalizeSpecifier'
+import { sha256 } from '../utils/hash'
+import path from 'node:path'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+async function resolveGitCommit(url: string, ref: string | null): Promise<string> {
+  const target = ref ?? 'HEAD'
+  const { stdout } = await execFileAsync('git', ['ls-remote', url, target])
+  const line = stdout.trim().split('\n')[0]
+  const commit = line?.split('\t')[0]?.trim()
+
+  if (!commit) {
+    throw new Error(`Unable to resolve git ref ${target} for ${url}`)
+  }
+
+  return commit
+}
+
+async function createLockEntry(cwd: string, specifier: string): Promise<{ skillName: string; entry: SkillsLockEntry }> {
+  const normalized = normalizeSpecifier(specifier)
+
+  if (normalized.type === 'file') {
+    const sourceRoot = path.resolve(cwd, normalized.source.slice('file:'.length))
+    return {
+      skillName: normalized.skillName,
+      entry: {
+        specifier: normalized.normalized,
+        resolution: {
+          type: 'file',
+          path: sourceRoot,
+        },
+        digest: sha256(`${sourceRoot}:${normalized.path}`),
+      },
+    }
+  }
+
+  if (normalized.type === 'git') {
+    const commit = await resolveGitCommit(normalized.source, normalized.ref)
+    return {
+      skillName: normalized.skillName,
+      entry: {
+        specifier: normalized.normalized,
+        resolution: {
+          type: 'git',
+          url: normalized.source,
+          commit,
+          path: normalized.path,
+        },
+        digest: sha256(`${normalized.source}:${commit}:${normalized.path}`),
+      },
+    }
+  }
+
+  throw new Error(`Unsupported specifier type in 0.1.0 core flow: ${normalized.type}`)
+}
+
+export async function syncSkillsLock(cwd: string, manifest: SkillsManifest, existingLock: SkillsLock | null): Promise<SkillsLock> {
+  const nextSkills: Record<string, SkillsLockEntry> = {}
+
+  for (const specifier of Object.values(manifest.skills)) {
+    const { skillName, entry } = await createLockEntry(cwd, specifier)
+    nextSkills[skillName] = entry
+  }
+
+  return {
+    lockfileVersion: '0.1',
+    installDir: manifest.installDir ?? '.agents/skills',
+    linkTargets: manifest.linkTargets ?? [],
+    skills: nextSkills,
+  }
+}

package/src/config/types.ts

@@ -0,0 +1,37 @@
+export type SkillsManifest = {
+  $schema?: string
+  installDir?: string
+  linkTargets?: string[]
+  skills: Record<string, string>
+}
+
+export type NormalizedSpecifier = {
+  type: 'git' | 'file' | 'npm'
+  source: string
+  ref: string | null
+  path: string
+  normalized: string
+  skillName: string
+}
+
+export type SkillsLockEntry = {
+  specifier: string
+  resolution:
+    | { type: 'file'; path: string }
+    | { type: 'git'; url: string; commit: string; path: string }
+    | { type: 'npm'; packageName: string; version: string; path: string; integrity?: string }
+  digest: string
+}
+
+export type SkillsLock = {
+  lockfileVersion: '0.1'
+  installDir: string
+  linkTargets: string[]
+  skills: Record<string, SkillsLockEntry>
+}
+
+export type AddCommandOptions = {
+  cwd: string
+  specifier: string
+  skill?: string
+}

package/src/config/writeSkillsLock.ts

@@ -0,0 +1,9 @@
+import { writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import YAML from 'yaml'
+import type { SkillsLock } from './types'
+
+export async function writeSkillsLock(rootDir: string, lockfile: SkillsLock): Promise<void> {
+  const filePath = path.join(rootDir, 'skills-lock.yaml')
+  await writeFile(filePath, YAML.stringify(lockfile), 'utf8')
+}

package/src/config/writeSkillsManifest.ts

@@ -0,0 +1,14 @@
+import { writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import type { SkillsManifest } from './types'
+
+export async function writeSkillsManifest(rootDir: string, manifest: SkillsManifest): Promise<void> {
+  const filePath = path.join(rootDir, 'skills.json')
+  const nextManifest = {
+    installDir: manifest.installDir ?? '.agents/skills',
+    linkTargets: manifest.linkTargets ?? [],
+    skills: manifest.skills,
+  }
+
+  await writeFile(filePath, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8')
+}

package/src/github/listSkills.ts

@@ -0,0 +1,170 @@
+import { execFile } from 'node:child_process'
+import { readdir, readFile, rm, stat, mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+import type { SkillInfo } from './types'
+
+const execFileAsync = promisify(execFile)
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '__pycache__'])
+
+function parseSkillFrontmatter(content: string): { name: string; description: string } {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/)
+  if (!fmMatch) {
+    return { name: '', description: '' }
+  }
+
+  const fm = fmMatch[1]
+  const nameMatch = fm.match(/^name:\s*(.+)$/m)
+  const descMatch = fm.match(/^description:\s*(.+)$/m)
+
+  return {
+    name: nameMatch?.[1]?.trim() ?? '',
+    description: descMatch?.[1]?.trim() ?? '',
+  }
+}
+
+async function hasSkillMd(dir: string): Promise<boolean> {
+  try {
+    const s = await stat(join(dir, 'SKILL.md'))
+    return s.isFile()
+  } catch {
+    return false
+  }
+}
+
+async function parseSkillDir(dir: string, relativePath: string): Promise<SkillInfo | null> {
+  try {
+    const content = await readFile(join(dir, 'SKILL.md'), 'utf8')
+    const meta = parseSkillFrontmatter(content)
+    const dirName = dir.split('/').pop() ?? ''
+    return {
+      name: meta.name || dirName,
+      description: meta.description,
+      path: relativePath,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Scan a directory for subdirs containing SKILL.md.
+ * Returns skills found in that directory level.
+ */
+async function scanForSkills(baseDir: string, subDir: string): Promise<SkillInfo[]> {
+  const searchDir = subDir ? join(baseDir, subDir) : baseDir
+  const skills: SkillInfo[] = []
+
+  try {
+    const entries = await readdir(searchDir, { withFileTypes: true })
+    const dirs = entries.filter((e) => e.isDirectory() && !SKIP_DIRS.has(e.name))
+
+    const checks = dirs.map(async (entry) => {
+      const fullPath = join(searchDir, entry.name)
+      if (await hasSkillMd(fullPath)) {
+        const relativePath = subDir ? `/${subDir}/${entry.name}` : `/${entry.name}`
+        return parseSkillDir(fullPath, relativePath)
+      }
+      return null
+    })
+
+    const results = await Promise.all(checks)
+    for (const r of results) {
+      if (r) skills.push(r)
+    }
+  } catch {
+    // directory doesn't exist
+  }
+
+  return skills
+}
+
+/**
+ * Clone a git repo (shallow) into a temp dir, discover skills, then clean up.
+ */
+export async function cloneAndDiscover(gitUrl: string, ref?: string): Promise<{ skills: SkillInfo[]; cleanup: () => Promise<void> }> {
+  const tempDir = await mkdtemp(join(tmpdir(), 'skills-pm-discover-'))
+
+  try {
+    const cloneArgs = ref
+      ? ['clone', '--depth', '1', '--branch', ref, gitUrl, tempDir]
+      : ['clone', '--depth', '1', gitUrl, tempDir]
+
+    await execFileAsync('git', cloneArgs, {
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+      timeout: 60_000,
+    })
+
+    const skills = await discoverSkillsInDir(tempDir)
+
+    return {
+      skills,
+      cleanup: async () => {
+        await rm(tempDir, { recursive: true, force: true }).catch(() => {})
+      },
+    }
+  } catch (error) {
+    await rm(tempDir, { recursive: true, force: true }).catch(() => {})
+    throw error
+  }
+}
+
+/**
+ * Discover skills in a local directory by scanning for SKILL.md files.
+ * Checks root-level dirs first, then common subdirs (skills/, .agents/skills/, etc.)
+ */
+export async function discoverSkillsInDir(baseDir: string): Promise<SkillInfo[]> {
+  // Scan root directory first
+  const rootSkills = await scanForSkills(baseDir, '')
+  if (rootSkills.length > 0) {
+    rootSkills.sort((a, b) => a.name.localeCompare(b.name))
+    return rootSkills
+  }
+
+  // Try common skill directories
+  const commonDirs = [
+    'skills',
+    '.agents/skills',
+    '.claude/skills',
+    '.github/skills',
+  ]
+
+  for (const dir of commonDirs) {
+    const skills = await scanForSkills(baseDir, dir)
+    if (skills.length > 0) {
+      skills.sort((a, b) => a.name.localeCompare(b.name))
+      return skills
+    }
+  }
+
+  return []
+}
+
+/**
+ * List skills in a GitHub repo by cloning and scanning.
+ * This avoids GitHub API rate limits.
+ */
+export async function listRepoSkills(owner: string, repo: string, ref?: string): Promise<SkillInfo[]> {
+  const gitUrl = `https://github.com/${owner}/${repo}.git`
+  const { skills, cleanup } = await cloneAndDiscover(gitUrl, ref)
+  await cleanup()
+  return skills
+}
+
+export function parseOwnerRepo(input: string): { owner: string; repo: string } | null {
+  const match = input.match(/^([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+)$/)
+  if (!match) {
+    return null
+  }
+  return { owner: match[1], repo: match[2] }
+}
+
+export function parseGitHubUrl(input: string): { owner: string; repo: string } | null {
+  const match = input.match(/^https?:\/\/github\.com\/([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+?)(?:\.git)?\/?$/)
+  if (!match) {
+    return null
+  }
+  return { owner: match[1], repo: match[2] }
+}

package/src/github/types.ts

@@ -0,0 +1,5 @@
+export type SkillInfo = {
+  name: string
+  description: string
+  path: string
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { addCommand } from './commands/add'
+export { installCommand } from './commands/install'
+export { runCli } from './cli/runCli'
+export { listRepoSkills, cloneAndDiscover, discoverSkillsInDir, parseOwnerRepo, parseGitHubUrl } from './github/listSkills'
+export type { SkillInfo } from './github/types'