skillshop 2.1.0 → 4.0.0

package/skills-content/skillshop/SKILL.md

@@ -1,18 +1,41 @@
 ---
 name: skillshop
-description: Manage repository-local agent skills from the installed skillshop registry. Use when a repository has a .skillshop-lock or the user asks to install, uninstall, pin, list, or update local skills with skillshop.
+description: Manage personal folder skill libraries, GitHub skill downloads, owned-copy sync, repository-local agent skills, Skillshop upgrades, and project agent instructions. Use when the user asks to initialize or list a personal library, download or install @owner/skill, install a bare personal skill name, sync personal sources, manage Skillshop copies, upgrade Skillshop, or initialize, render, or check project AGENTS.md instructions.
 metadata:
   author: Daniel Fosco
-  version: "2026.10.1"
+  version: "2026.10.23.1"
 ---
 
-# Skillshop — Local Skill Registry
+# Skillshop — Personal Skill Libraries and Local Registry
 
-Use the `skillshop` CLI to manage skills in this repository. The project-root `.skillshop-lock` is the source of truth for which skill directories are managed by skillshop; directories absent from the lock belong to the project or another installer.
+Use the `skillshop` CLI to manage personal folder libraries and their recorded installed copies. A personal library is the source of truth for user-authored skills; `.skillshop-lock` and `~/.skillshop/global-skills.json` record which project and global directories Skillshop installed from those sources. Directories absent from ownership records belong to the project or another installer.
+
+## Personal folder libraries
+
+```bash
+skillshop library init                 # selects ~/skillshop-library
+skillshop library init ./my-skills     # creates or adopts an existing folder
+skillshop library list
+skillshop download @alice/review       # adds source without installing
+skillshop install @alice/review        # downloads if missing, then installs locally
+skillshop install @alice/review --global
+skillshop install review               # installs an existing selected source
+skillshop sync                         # syncs all recorded personal copies
+```
+
+The library is an ordinary folder. It needs no `package.json`, npm author metadata, build step, or version field. `skillshop library init` selects the visible default `~/skillshop-library` or creates/adopts the explicit directory. It preserves existing library skills and config. `skillshop library list` shows the selected source folder.
+
+The plain `skillshop-library.json` config names a relative `skillsDirectory` (default `skills`). Each skill is a directory with `SKILL.md` declaring `name` and `description`; references, scripts, hidden files, binary assets, and executable modes are included in the full directory.
+
+`skillshop download @owner/skill` fetches `https://github.com/owner/skillshop-library.git` and adds only the requested `skills/skill` directory to the personal library. The leading `@` marks remote syntax and is stripped from the GitHub owner; the repository URL contains no `@`. Unprefixed `owner/skill` inputs are rejected. Download does not install the skill. Same-name authored or different-source collisions fail. `skillshop download @owner/skill --force` explicitly replaces that source after validating the remote tree. `skillshop install @owner/skill` downloads only when the source is absent. An existing same-origin source, including local edits, is reused without an upstream fetch. `skillshop install name` uses a bare name for a source already in the selected personal library.
+
+`skillshop sync` updates copies recorded as personal-library installs and is the explicit migration step for tracked legacy bundled copies. It compares and copies the complete source tree, including path and mode changes, repairs edits made inside an installed copy, and removes stale extras inside that owned skill directory. It uses the source root recorded at install time, even after another library is selected. Sync does not fetch upstream. `skillshop library init` never migrates. For a tracked bundle copy, an existing selected-library source wins. If the source is missing, it is imported only when every surviving tracked project and global copy agrees in paths, bytes, and modes. Divergence, unknown source kinds, unreadable ownership state, unmanaged directories, and package-import snapshots are preserved and reported. A missing personal source reports an error and preserves existing destinations. Missing destinations are pruned from their ownership records and are not recreated. Keep durable edits in the personal source; sync replaces edits made in its owned installed copies.
 
 This registry is hand-maintained. `metadata.author` is original-author attribution, not ownership. The user can adapt skills locally. skillshop does not read other installers' state or update their skills; the user resolves name collisions.
 
-Every invocation, including help, version, and failed commands, reconciles the current project's lockfile, registration, and Git exclusions. It removes missing installation paths and stale repository registrations. Tracked installed frontmatter is repaired without replacing bodies or extra fields: names match directory names, author/version use the installation record, and missing descriptions use the bundled skill. Incomplete records fall back to installed or bundled metadata. Valid files are not rewritten. Invalid lockfiles, unsafe paths, and unsupported frontmatter must be reported, not discarded. Do not silently untrack Git files; that remains an explicit migration operation.
+Most ordinary non-agent commands reconcile the current project's lockfile, registration, and Git exclusions. Personal library, download, qualified install, sync, upgrade, and agent-instruction commands bypass that legacy reconciliation. In personal mode, `skillshop list` and named installs also bypass it. Upgrade installs the npm package first, then starts the installed CLI in a fresh process to refresh changed-version bundled copies recorded in Skillshop's project/global ownership files. Personal-source copies are excluded from bundled refresh. A failed npm install must not touch managed copies; report any partial copy refresh and return failure. Never adopt unmanaged directories or package-import snapshots, and do not recreate deleted paths. Reconciliation removes missing installation paths and stale repository registrations. Tracked bundled installed frontmatter is repaired without replacing bodies or extra fields. Invalid lockfiles, unsafe paths, and unsupported frontmatter must be reported, not discarded. Do not silently untrack Git files; that remains an explicit migration operation.
+
+`skillshop init` is optional for upgrade. It configures agent destinations but does not install the npm package or refresh managed skill copies. Upgrade never generates or edits `AGENTS.md` files or project instruction templates.
 
 ## Configure agents
 
@@ -21,9 +44,50 @@ skillshop init
 skillshop config agents
 ```
 
-The first `skillshop init` prompts for one or more agents and stores the system-wide selection in `~/.skillshop/config.json`. `skillshop config agents` replaces that selection. Copilot uses `.github/skills` locally and `~/.copilot/skills` globally; Claude uses `.claude/skills` in both scopes; Codex, OpenCode, and Others use `.agents/skills` in both scopes. Shared paths are deduplicated.
+The first `skillshop init` prompts for one or more agents and stores the system-wide selection in `~/.skillshop/config.json`. `skillshop init` is optional for project skill installs: without saved agent selection, Skillshop uses the nearest existing `.agents`, `.github`, or `.codex` directory and falls back to project-root `.agents/skills`. `skillshop config agents` replaces the system-wide selection. Copilot uses `.github/skills` locally and `~/.copilot/skills` globally; Claude uses `.claude/skills` in both scopes; Codex, OpenCode, and Others use `.agents/skills` in both scopes. Shared paths are deduplicated.
+
+## Manage project agent instructions
 
-## Install a skill
+```bash
+skillshop agents init
+skillshop agents
+skillshop agents --check
+skillshop agents --global
+```
+
+`skillshop agents init` opts into project-owned instruction sources at `.agents/instructions/AGENTS.template.md` and sibling `*.block.md` files. Skillshop writes their output to a separate managed region in the project-root `AGENTS.md`, preserving surrounding text and older managed guidance. Edit the template and source blocks, not the generated region. Repeated `skillshop agents init` preserves source edits. If the initialized source template is removed, plain `skillshop agents` reports an error instead of restoring bundled personal guidance.
+
+Before project sources are configured, plain `skillshop agents` keeps the bounded legacy behavior: it updates the nearest existing `AGENTS.md` inside the selected boundary, or creates the root output when none exists. The boundary is the nearest Git repository/worktree root, or the current directory outside Git. `--project <directory>` explicitly selects another boundary relative to the current working directory. Use it for nested projects so every script stays inside the nested package:
+
+```json
+{
+  "scripts": {
+    "agents": "skillshop agents --project .",
+    "agents:init": "skillshop agents init --project .",
+    "agents:check": "skillshop agents --check --project ."
+  }
+}
+```
+
+`--check` is read-only and suitable for CI. It compares generated output in the working tree with current sources; it does not inspect the Git index or commit. Symlink components in project source, block, template, and output paths are rejected, including dangling symlinks. `--global` retains user-level instruction updates.
+
+Source templates support `{{ include "name.block.md" }}`, `{{ include 'name.block.md' }}`, the legacy `{{ fragments["name.block.md"] }}` lookup, and `{{ blocks }}` for remaining blocks in filename order. Explicitly included blocks are excluded from the aggregate. Repeated includes are allowed. Block text is inserted literally and is not evaluated recursively.
+
+For npm consumers, declare explicit scripts rather than relying on an install hook:
+
+```json
+{
+  "scripts": {
+    "agents": "skillshop agents",
+    "agents:init": "skillshop agents init",
+    "agents:check": "skillshop agents --check"
+  }
+}
+```
+
+Commit the template and block sources together with the rendered root `AGENTS.md`; commit `package.json` and the npm lockfile when Skillshop is a development dependency. Run `npm run agents:check` in CI to detect stale or missing generated output.
+
+## Install a bundled skill when no personal library is selected
 
 Run commands from anywhere inside the repository:
 
@@ -34,7 +98,7 @@ skillshop i <name>
 skillshop add <name>
 ```
 
-The CLI installs the full skill package into every configured project path, refreshes every skill already listed in `.skillshop-lock`, and updates the lockfile. Changing the configured agents migrates managed local copies on the next install or update. Local installs are recorded in `~/.skillshop/repositories.json`; `.skillshop-lock` and its managed skill paths are added to the repository's Git `info/exclude`.
+Without a selected personal library, the CLI installs the full skill package into every configured project path, refreshes every skill already listed in `.skillshop-lock`, and updates the lockfile. Changing the configured agents migrates managed local copies on the next install or update. Local installs are recorded in `~/.skillshop/repositories.json`; `.skillshop-lock` and its managed skill paths are added to the repository's Git `info/exclude`. With a personal library selected, `skillshop list` and unqualified named installs use that library only; they do not reconcile bundled copies or add bundled `skillshop` guidance.
 
 To require the exact version currently available from the local registry:
 
@@ -45,7 +109,7 @@ skillshop install <name> --version <version>
 skillshop <name> --global
 ```
 
-`--global` (or `-g`) installs into every configured system skill path without a project lockfile. Installs are recorded in `~/.skillshop/global-skills.json` so every command can repair their frontmatter and prune missing paths. Older installs are recorded on explicit reinstall; do not adopt other global skills. Global copies are not migrated when the agent setting changes, so remove unwanted global skills before reconfiguration. The local registry contains one current version per skill. `--version` (or `-v`) is an exact compatibility check; do not claim that an unavailable historical version can be resolved.
+`--global` (or `-g`) installs into every configured system skill path without a project lockfile. Installs are recorded in `~/.skillshop/global-skills.json`. For bundled tracked installs, most ordinary commands can repair frontmatter and prune missing paths. Personal library, download, qualified install, sync, upgrade, and agent-instruction commands bypass that legacy reconciliation. In personal mode, `skillshop list` and named installs bypass it too. `skillshop upgrade` refreshes recorded bundled global and registered project copies only after npm succeeds and a fresh CLI starts. Same-version bundled copies keep local body edits; a changed-version refresh replaces that managed copy and overwrites its local edits. For durable personal edits, select a folder library, use explicit sync to adopt agreeing tracked copies, and edit the library source. Personal-library copies are excluded from bundled refresh. Explicit `skillshop sync` never scans untracked directories. Global copies are not migrated when the agent setting changes, so remove unwanted global skills before reconfiguration. The local registry contains one current version per skill. `--version` (or `-v`) is an exact compatibility check; do not claim that an unavailable historical version can be resolved.
 
 ## Update managed skills
 
@@ -60,6 +124,16 @@ skillshop up --push
 
 `update` with no name replaces every skill listed in the current repository's `.skillshop-lock` and updates its locked metadata. A name updates only that managed skill. `--push` updates every centrally registered repository and cannot be combined with a skill name. Updates and installs replace local edits; keep edits in the registry if they should survive these operations. Global installs cannot be updated with this command; reinstall them by name with `--global`.
 
+## Upgrade Skillshop
+
+```bash
+skillshop upgrade
+```
+
+Upgrade targets the npm installation that supplied the invoked CLI. A local npm dependency updates in its owning project and stays in its existing dependency section; only that project's locked Skillshop copies are refreshed. A global npm installation updates its active prefix and refreshes recorded global copies plus copies in registered projects without changing those projects' npm manifests. A source checkout retains the compatibility behavior of installing Skillshop globally, without editing the checkout's `package.json`.
+
+After npm succeeds, the new package's CLI starts in a fresh process. It replaces existing recorded copies only when the bundled skill version changed, preserving local bodies for same-version copies. Changed-version replacement overwrites local edits in that managed copy. For durable personal edits, select a library, explicitly sync to adopt agreeing tracked copies, then edit the library source and sync. Missing paths are pruned from records rather than recreated. Unmanaged skills and imported snapshots remain untouched. Install failure prevents refresh; refresh failure reports the npm stage as successful and returns nonzero with a partial-result summary. Upgrade does not run agent initialization or project instruction generation.
+
 ## Migrate existing repositories
 
 ```bash

package/src/agents-instructions.js

@@ -6,6 +6,7 @@ export class AgentsInstructionsError extends Error {}
 
 const blockSuffix = '.block.md';
 const referencePattern = /\{\{\s*([^{}]+?)\s*\}\}/g;
+const includePattern = /^include\s+(["'])([^"']+)\1$/;
 const namedReferencePattern = /^fragments\s*\[\s*(["'])([^"'\[\]]+)\1\s*\]$/;
 const aggregateExpression = 'blocks';
 const regionBeginPrefix = '<!-- skillshop agents: begin v';
@@ -13,6 +14,9 @@ const regionBeginPattern = /^<!-- (?:skillshop|skillz) agents: begin v\S+ -->$/;
 const regionEndLine = '<!-- skillshop agents: end -->';
 const oldRegionEndLine = '<!-- skillz agents: end -->';
 const legacyMarkerPattern = /^<!-- skillz agents: AGENTS\.md@\S+ -->$/;
+const projectRegionBeginPrefix = '<!-- skillshop project agents: begin v';
+const projectRegionBeginPattern = /^<!-- skillshop project agents: begin v\S+ -->$/;
+const projectRegionEndLine = '<!-- skillshop project agents: end -->';
 const fragmentsBegin = '<!-- skillshop fragments: begin -->';
 const fragmentsEnd = '<!-- skillshop fragments: end -->';
 
@@ -32,12 +36,12 @@ export function discoverBlocks(contentDirectory) {
 function invalidReference(expression, line) {
   return new AgentsInstructionsError(
     `invalid fragment reference {{ ${expression} }} at line ${line} of the agents base template; ` +
-      'use {{ fragments["name.block.md"] }} or {{ blocks }}'
+      'use {{ include "name.block.md" }} or {{ blocks }}'
   );
 }
 
-export function composeAgentsInstructions(contentDirectory) {
-  const basePath = path.join(contentDirectory, 'AGENTS.md');
+export function composeAgentsInstructions(contentDirectory, baseFileName = 'AGENTS.md') {
+  const basePath = path.join(contentDirectory, baseFileName);
   if (!fs.existsSync(basePath)) {
     throw new AgentsInstructionsError(`missing agents base template: ${basePath}`);
   }
@@ -54,7 +58,7 @@ export function composeAgentsInstructions(contentDirectory) {
       references.push({ kind: 'aggregate', start: match.index, end: match.index + match[0].length });
       continue;
     }
-    const named = expression.match(namedReferencePattern);
+    const named = expression.match(includePattern) ?? expression.match(namedReferencePattern);
     if (!named || named[2].includes('/') || named[2].includes('\\')) {
       throw invalidReference(expression, line);
     }
@@ -91,6 +95,39 @@ export function composeAgentsInstructions(contentDirectory) {
   return { content };
 }
 
+export function applyProjectInstructions(existing, composed, version) {
+  const composedText = composed.trimEnd();
+  const region = `${projectRegionBeginPrefix}${version} -->\n${composedText}\n${projectRegionEndLine}`;
+  const lines = existing.split('\n');
+  const begins = [];
+  const ends = [];
+  lines.forEach((line, index) => {
+    if (projectRegionBeginPattern.test(line)) begins.push(index);
+    else if (line === projectRegionEndLine) ends.push(index);
+  });
+
+  if (begins.length !== ends.length || begins.length > 1 || (begins.length && begins[0] >= ends[0])) {
+    throw new AgentsInstructionsError('project agents markers are malformed');
+  }
+  if (!begins.length) return { action: 'installed', text: appendRegion(existing, region) };
+
+  const [start] = begins;
+  const [end] = ends;
+  const installedVersion = lines[start].match(/<!-- skillshop project agents: begin v(\S+) -->/)[1];
+  const inner = lines.slice(start + 1, end).join('\n');
+  if (installedVersion === version && inner === composedText && lines[end] === projectRegionEndLine) {
+    return { action: 'unchanged', text: existing };
+  }
+  return {
+    action: 'refreshed',
+    text: [...lines.slice(0, start), ...region.split('\n'), ...lines.slice(end + 1)].join('\n')
+  };
+}
+
+export function hasProjectInstructions(existing) {
+  return existing.split('\n').some((line) => projectRegionBeginPattern.test(line) || line === projectRegionEndLine);
+}
+
 function regionText(version, composed) {
   return `${regionBeginPrefix}${version} -->\n${composed}\n${regionEndLine}`;
 }

package/src/cli.js

@@ -11,22 +11,18 @@ import { parseLibrarySkillReference, skillName } from './specifier.js';
 
 function help() {
   console.log(`
-Library commands:
+Personal folder library commands:
 
-  skillshop library init
+  skillshop library init [directory]
   skillshop library list
-  skillshop export skill:<name> <directory>
-  skillshop export skill:<name> --from <package> [--skill skill:<source-name>]
-  skillshop unexport skill:<name>
-  skillshop validate
-  skillshop build
-  skillshop resolve <library>:<skill>
-  skillshop import <library>:<skill> [--global] [--to <directory>] [--force]
-  skillshop install-user [package-dir] [--if-global] [--to <skills-dir>]
+  skillshop download @<owner>/<skill> [--force]
+  skillshop install @<owner>/<skill> [--global]
+  skillshop install <name> [--global]
+  skillshop sync
 
-A library publishes skills by portable specifier, for example skill:review.
-Import uses the short <library>:<skill> form and copies to .agents/skills/<skill> by default.
---global copies to ~/.agents/skills/<skill> and replaces an existing directory.`);
+Create or select a source folder with skillshop library init. Download @owner/skill adds a GitHub skill to that folder without installing it.
+Install @owner/skill downloads when needed, then installs the complete source tree. Bare install names use the selected personal library. Sync updates recorded project and global copies from their saved source roots.
+No npm package manifest or author metadata is required. Existing npm package export/import APIs remain available for compatibility.`);
 }
 
 function flag(args, name) {
@@ -47,7 +43,7 @@ const libraryCommands = new Set(['export', 'unexport', 'validate', 'build', 'res
 async function main(argv, { libraryNamespace = false } = {}) {
   const [command, ...args] = argv;
   if (!libraryNamespace && command === 'library') {
-    if (args[0] === 'init' || args[0] === 'list') return main(args, { libraryNamespace: true });
+    if (args[0] === 'init' || args[0] === 'list') return runLegacyCli(argv);
     if (!args.length || args[0] === '--help' || args[0] === '-h') return help();
     throw new Error('Usage: skillshop library init | list');
   }
@@ -146,13 +142,14 @@ async function main(argv, { libraryNamespace = false } = {}) {
 
 const argv = process.argv.slice(2);
 const usingLibraryCommands = argv[0] === 'library' || libraryCommands.has(argv[0]);
+const personalLibraryCommand = argv[0] === 'library' && ['init', 'list'].includes(argv[1]);
 
 try {
-  if (usingLibraryCommands) reconcileLegacyState();
+  if (usingLibraryCommands && !personalLibraryCommand) reconcileLegacyState();
   try {
     await main(argv);
   } finally {
-    if (usingLibraryCommands) reconcileLegacyState();
+    if (usingLibraryCommands && !personalLibraryCommand) reconcileLegacyState();
   }
 } catch (error) {
   console.error(`skillshop: ${error.message}`);

package/src/github-library.js

@@ -0,0 +1,310 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  commitDownloadedPersonalSkill,
+  initPersonalLibrary,
+  inspectPersonalLibrary,
+  libraryConfigFileName,
+  libraryOriginsFileName,
+  librarySelectionFileName,
+  readPersonalLibraryOrigins,
+  selectedLibraryRoot,
+  validatePersonalSkillDirectory
+} from './personal-library.js';
+
+const githubOwnerPattern = /^[A-Za-z0-9-]+$/;
+const skillNamePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const reservedRootNames = new Set([libraryConfigFileName, 'README.md', libraryOriginsFileName]);
+
+export class GitHubLibraryError extends Error {}
+
+function fail(message) {
+  return new GitHubLibraryError(message);
+}
+
+export function parseGitHubSkillReference(reference) {
+  if (typeof reference !== 'string') throw fail('expected GitHub skill reference @<owner>/<skill>');
+  if (!reference.startsWith('@')) {
+    throw fail(`invalid GitHub skill reference ${reference}; prefix remote references with @ as @<owner>/<skill>`);
+  }
+  const parts = reference.slice(1).split('/');
+  if (parts.length !== 2 || !githubOwnerPattern.test(parts[0]) || !skillNamePattern.test(parts[1])) {
+    throw fail(`invalid GitHub skill reference ${reference}; expected @<owner>/<skill>`);
+  }
+  return { owner: parts[0], name: parts[1], repository: `https://github.com/${parts[0]}/skillshop-library.git` };
+}
+
+function gitEnvironment() {
+  return {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_CONFIG_GLOBAL: '/dev/null',
+    GIT_ALLOW_PROTOCOL: 'https:file'
+  };
+}
+
+function git(args, { cwd, encoding = 'utf8', maxBuffer = 64 * 1024 * 1024 } = {}) {
+  const result = spawnSync('git', args, { cwd, encoding, env: gitEnvironment(), maxBuffer });
+  if (result.error) throw fail(`could not run Git: ${result.error.message}`);
+  if (result.status !== 0) {
+    const message = encoding === null ? result.stderr?.toString('utf8') : result.stderr;
+    throw fail(`Git ${args[0]} failed${message?.trim() ? `: ${message.trim()}` : ''}`);
+  }
+  return result.stdout;
+}
+
+function parseTreeEntries(buffer) {
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  const entries = [];
+  for (const chunk of buffer.toString('binary').split('\0').filter(Boolean)) {
+    const separator = chunk.indexOf('\t');
+    if (separator < 0) throw fail('Git returned a malformed tree entry');
+    const [mode, type, object] = chunk.slice(0, separator).split(' ');
+    const rawPath = Buffer.from(chunk.slice(separator + 1), 'binary');
+    let entryPath;
+    try {
+      entryPath = decoder.decode(rawPath);
+    } catch {
+      throw fail('repository contains a non-UTF-8 path');
+    }
+    entries.push({ mode, type, object, path: entryPath });
+  }
+  return entries;
+}
+
+function literalPath(value) {
+  return `:(literal)${value}`;
+}
+
+function treeEntry(repositoryDir, commit, filePath) {
+  const result = git(['-C', repositoryDir, 'ls-tree', '-z', commit, '--', literalPath(filePath)], { encoding: null });
+  const entries = parseTreeEntries(result);
+  return entries.find((entry) => entry.path === filePath) ?? null;
+}
+
+function normalizeSkillsDirectory(value) {
+  if (typeof value !== 'string' || !value || value.includes('\\') || value.startsWith('/')) {
+    throw fail('skillshop-library.json skillsDirectory must be a relative repository path');
+  }
+  const normalized = path.posix.normalize(value);
+  if (normalized === '..' || normalized.startsWith('../') || normalized.startsWith('/')) {
+    throw fail('skillshop-library.json skillsDirectory contains an unsafe path');
+  }
+  return normalized;
+}
+
+function readRemoteConfig(repositoryDir, commit) {
+  const entry = treeEntry(repositoryDir, commit, libraryConfigFileName);
+  if (!entry || entry.type !== 'blob' || !['100644', '100755'].includes(entry.mode)) {
+    throw fail(`repository is missing a regular ${libraryConfigFileName}`);
+  }
+  let config;
+  try {
+    config = JSON.parse(git(['-C', repositoryDir, 'show', `${commit}:${libraryConfigFileName}`], { encoding: null }).toString('utf8'));
+  } catch (error) {
+    if (error instanceof GitHubLibraryError) throw error;
+    throw fail(`cannot parse ${libraryConfigFileName}: ${error.message}`);
+  }
+  if (config?.schemaVersion !== 1) throw fail(`${libraryConfigFileName} has an unsupported schemaVersion`);
+  const skillsDirectory = normalizeSkillsDirectory(config.skillsDirectory);
+  return { skillsDirectory };
+}
+
+function safeRelativeFilePath(skillPath, repoPath) {
+  if (!repoPath.startsWith(`${skillPath}/`)) throw fail(`repository path escapes requested skill: ${repoPath}`);
+  const relative = repoPath.slice(skillPath.length + 1);
+  const parts = relative.split('/');
+  if (!relative || relative.includes('\\') || parts.some((part) => !part || part === '.' || part === '..')) {
+    throw fail(`repository contains an unsafe skill path: ${repoPath}`);
+  }
+  return relative;
+}
+
+function stageSkill(repositoryDir, commit, skillPath, name, stagingRoot) {
+  const rootEntry = treeEntry(repositoryDir, commit, skillPath);
+  if (!rootEntry) throw fail(`repository has no skill named ${name}`);
+  if (rootEntry.mode !== '040000' || rootEntry.type !== 'tree') {
+    throw fail(`repository path for ${name} is not a skill directory`);
+  }
+  const entries = parseTreeEntries(git([
+    '-C', repositoryDir, 'ls-tree', '-r', '-z', '--full-tree', commit, '--', literalPath(skillPath)
+  ], { encoding: null }));
+  if (!entries.length) throw fail(`repository skill ${name} is empty`);
+
+  const skillDirectory = path.join(stagingRoot, 'skill');
+  fs.mkdirSync(skillDirectory, { recursive: true, mode: 0o755 });
+  const seen = new Set();
+  for (const entry of entries) {
+    const relative = safeRelativeFilePath(skillPath, entry.path);
+    if (seen.has(relative)) throw fail(`repository contains a duplicate skill path: ${relative}`);
+    seen.add(relative);
+    if (entry.type !== 'blob' || !['100644', '100755'].includes(entry.mode)) {
+      throw fail(`repository skill contains a symlink, submodule, or non-regular entry: ${entry.path}`);
+    }
+    const target = path.join(skillDirectory, ...relative.split('/'));
+    const contained = path.relative(skillDirectory, target);
+    if (contained === '..' || contained.startsWith(`..${path.sep}`) || path.isAbsolute(contained)) {
+      throw fail(`repository path escapes requested skill: ${entry.path}`);
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o755 });
+    const contents = git(['-C', repositoryDir, 'cat-file', 'blob', entry.object], { encoding: null });
+    fs.writeFileSync(target, contents, { flag: 'wx', mode: entry.mode === '100755' ? 0o755 : 0o644 });
+    fs.chmodSync(target, entry.mode === '100755' ? 0o755 : 0o644);
+  }
+  validatePersonalSkillDirectory(skillDirectory, skillDirectory, name);
+  return skillDirectory;
+}
+
+function fetchSkill(reference, temporaryRoot) {
+  const bareRepository = path.join(temporaryRoot, 'repository.git');
+  fs.mkdirSync(bareRepository, { recursive: true });
+  git(['init', '--bare', '--quiet', bareRepository]);
+  const symbolicRefs = git(['ls-remote', '--symref', reference.repository, 'HEAD']);
+  const headReference = symbolicRefs.split(/\r?\n/).find((line) => line.startsWith('ref: ') && line.endsWith('\tHEAD'));
+  const headObject = symbolicRefs.split(/\r?\n/).find((line) => /^[a-f0-9]{40,64}\tHEAD$/.test(line));
+  if (!headReference || !headObject) throw fail(`could not discover the default branch for ${reference.repository}`);
+  const branchRef = headReference.slice('ref: '.length, -'\tHEAD'.length);
+  if (!branchRef.startsWith('refs/heads/')) throw fail('GitHub repository default is not a branch');
+  git(['-C', bareRepository, 'check-ref-format', branchRef]);
+  git(['-C', bareRepository, 'fetch', '--no-tags', '--no-recurse-submodules', '--depth=1', reference.repository, branchRef]);
+  const commit = git(['-C', bareRepository, 'rev-parse', '--verify', 'FETCH_HEAD^{commit}']).trim();
+  if (!/^[a-f0-9]{40,64}$/.test(commit)) throw fail('Git returned an invalid commit identifier');
+  const config = readRemoteConfig(bareRepository, commit);
+  const skillPath = config.skillsDirectory === '.' ? reference.name : `${config.skillsDirectory}/${reference.name}`;
+  if (config.skillsDirectory === '.' && reservedRootNames.has(reference.name)) {
+    throw fail(`skill name collides with repository metadata: ${reference.name}`);
+  }
+  const skillDirectory = stageSkill(bareRepository, commit, skillPath, reference.name, temporaryRoot);
+  return { skillDirectory, origin: { repository: reference.repository, commit } };
+}
+
+function snapshotFile(filePath) {
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw fail(`${filePath} must be a regular file`);
+    return { contents: fs.readFileSync(filePath), mode: stat.mode & 0o777 };
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function restoreFile(filePath, snapshot) {
+  if (!snapshot) {
+    fs.rmSync(filePath, { force: true });
+    return;
+  }
+  fs.writeFileSync(filePath, snapshot.contents, { mode: snapshot.mode });
+  fs.chmodSync(filePath, snapshot.mode);
+}
+
+function captureInitialization(root, stateHome) {
+  let rootExisted = true;
+  let rootEmpty = false;
+  try {
+    const stat = fs.lstatSync(root);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw fail(`library root is not a regular directory: ${root}`);
+    rootEmpty = fs.readdirSync(root).length === 0;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    rootExisted = false;
+  }
+  const skillsBefore = path.join(root, 'skills');
+  let skillsExisted = false;
+  try {
+    fs.lstatSync(skillsBefore);
+    skillsExisted = true;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  return {
+    rootExisted,
+    rootEmpty,
+    skillsExisted,
+    stateHomeExisted: fs.existsSync(stateHome),
+    config: snapshotFile(path.join(root, libraryConfigFileName)),
+    readme: snapshotFile(path.join(root, 'README.md')),
+    selection: snapshotFile(path.join(stateHome, librarySelectionFileName))
+  };
+}
+
+function rollbackInitialization(root, stateHome, snapshot) {
+  if (!snapshot.rootExisted) {
+    fs.rmSync(root, { recursive: true, force: true });
+  } else if (snapshot.rootEmpty) {
+    for (const entry of fs.readdirSync(root)) fs.rmSync(path.join(root, entry), { recursive: true, force: true });
+  } else {
+    restoreFile(path.join(root, libraryConfigFileName), snapshot.config);
+    restoreFile(path.join(root, 'README.md'), snapshot.readme);
+    if (!snapshot.skillsExisted) fs.rmSync(path.join(root, 'skills'), { recursive: true, force: true });
+  }
+  restoreFile(path.join(stateHome, librarySelectionFileName), snapshot.selection);
+  if (!snapshot.stateHomeExisted && fs.existsSync(stateHome) && fs.readdirSync(stateHome).length === 0) {
+    fs.rmdirSync(stateHome);
+  }
+}
+
+function targetInfo(layout, name) {
+  if (path.resolve(layout.skillsDirectory) === path.resolve(layout.root) && reservedRootNames.has(name)) {
+    throw fail(`skill name collides with library metadata: ${name}`);
+  }
+  const target = path.join(layout.skillsDirectory, name);
+  try {
+    const stat = fs.lstatSync(target);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw fail(`personal library target is not a regular skill directory: ${target}`);
+    validatePersonalSkillDirectory(layout.root, target, name);
+    return { target, exists: true };
+  } catch (error) {
+    if (error.code === 'ENOENT') return { target, exists: false };
+    throw error;
+  }
+}
+
+export function downloadPersonalSkill(referenceValue, { stateHome, templateRoot, force = false } = {}) {
+  const reference = parseGitHubSkillReference(referenceValue);
+  const selected = selectedLibraryRoot(stateHome);
+  const root = selected ?? path.resolve(os.homedir(), 'skillshop-library');
+  const layout = inspectPersonalLibrary(root);
+  const origins = layout.exists ? readPersonalLibraryOrigins(root) : { schemaVersion: 1, skills: {} };
+  const existingOrigin = origins.skills[reference.name];
+  const target = targetInfo(layout, reference.name);
+  if (target.exists && !force) {
+    if (existingOrigin?.repository === reference.repository) {
+      if (!selected) initPersonalLibrary(root, stateHome, templateRoot);
+      return { root, name: reference.name, origin: existingOrigin, alreadyPresent: true };
+    }
+    if (existingOrigin) throw fail(`${reference.name} already has a different GitHub source; use --force to replace it`);
+    throw fail(`${reference.name} already exists as a personal skill; use --force to replace it`);
+  }
+  if (existingOrigin && existingOrigin.repository !== reference.repository && !force) {
+    throw fail(`${reference.name} already has a different GitHub source; use --force to replace it`);
+  }
+  const temporaryRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'skillshop-github-download-'));
+  try {
+    const downloaded = fetchSkill(reference, temporaryRoot);
+    let initialized = false;
+    let initializationSnapshot;
+    let skillsDirectory = layout.skillsDirectory;
+    if (!selected) initializationSnapshot = captureInitialization(root, stateHome);
+    try {
+      if (!selected) {
+        initialized = true;
+        const result = initPersonalLibrary(root, stateHome, templateRoot, { includeExample: false });
+        skillsDirectory = result.skillsDirectory;
+        if (path.resolve(skillsDirectory) !== path.resolve(layout.skillsDirectory)) {
+          throw fail('default library layout changed during download');
+        }
+      }
+      const committed = commitDownloadedPersonalSkill(root, skillsDirectory, reference.name, downloaded.skillDirectory, downloaded.origin, { force });
+      return { root, name: reference.name, origin: downloaded.origin, target: committed.target, alreadyPresent: false };
+    } catch (error) {
+      if (initialized) rollbackInitialization(root, stateHome, initializationSnapshot);
+      throw error;
+    }
+  } finally {
+    fs.rmSync(temporaryRoot, { recursive: true, force: true });
+  }
+}