claude-devkit-cli 1.3.3 → 1.4.0

package/README.md

@@ -66,7 +66,7 @@ claude
 /mf-plan "describe your feature here"
 
 # 4. Write code, then test
-/mf-test
+/mf-build
 
 # 5. Review before merging
 /mf-review
@@ -109,7 +109,16 @@ cd my-project
 claude-devkit init .
 ```
 
-**Option C: Force re-install** (overwrites existing files)
+**Option C: Global skills install** (available in all projects without running `init` again)
+
+```bash
+claude-devkit init --global
+# or after per-project init, answer "yes" to the global prompt
+```
+
+Skills installed globally at `~/.claude/skills/` are available in every project. Per-project `.claude/skills/` always takes precedence over global — so projects can still override individual skills.
+
+**Option D: Force re-install** (overwrites existing files)
 
 ```bash
 npx claude-devkit-cli init --force .
@@ -118,7 +127,7 @@ npx claude-devkit-cli init --force .
 **Option D: Selective install** (only specific components)
 
 ```bash
-npx claude-devkit-cli init --only hooks,commands .
+npx claude-devkit-cli init --only hooks,skills .
 ```
 
 ### What Gets Installed
@@ -135,13 +144,13 @@ your-project/
 │   │   ├── comment-guard.js   ← Blocks placeholder comments
 │   │   ├── sensitive-guard.sh ← Blocks access to secrets
 │   │   └── self-review.sh     ← Quality checklist on stop
-│   └── commands/
-│       ├── mf-plan.md         ← /mf-plan command
-│       ├── mf-challenge.md    ← /mf-challenge command
-│       ├── mf-test.md         ← /mf-test command
-│       ├── mf-fix.md          ← /mf-fix command
-│       ├── mf-review.md       ← /mf-review command
-│       └── mf-commit.md       ← /mf-commit command
+│   └── skills/
+│       ├── mf-plan/SKILL.md         ← /mf-plan skill
+│       ├── mf-challenge/SKILL.md    ← /mf-challenge skill
+│       ├── mf-build/SKILL.md        ← /mf-build skill
+│       ├── mf-fix/SKILL.md          ← /mf-fix skill
+│       ├── mf-review/SKILL.md       ← /mf-review skill
+│       └── mf-commit/SKILL.md       ← /mf-commit skill
 ├── scripts/
 │   └── build-test.sh          ← Universal test runner
 └── docs/
@@ -187,7 +196,7 @@ npx claude-devkit-cli list
 npx claude-devkit-cli remove
 ```
 
-This removes hooks, commands, settings, and build-test.sh. It preserves `CLAUDE.md` (which you may have customized) and `docs/` (which contains your specs).
+This removes hooks, skills, settings, and build-test.sh. It preserves `CLAUDE.md` (which you may have customized) and `docs/` (which contains your specs).
 
 ---
 
@@ -202,7 +211,7 @@ This removes hooks, commands, settings, and build-test.sh. It preserves `CLAUDE.
    → Generates spec with acceptance scenarios at docs/specs/<feature>/<feature>.md.
 
 2. Implement code in chunks.
-   After each chunk: /mf-test
+   After each chunk: /mf-build
    Repeat until green.
 
 3. /mf-review (before merge)
@@ -225,7 +234,7 @@ This removes hooks, commands, settings, and build-test.sh. It preserves `CLAUDE.
    Do NOT manually edit the spec before running /mf-plan.
 
 2. Implement the code change.
-   /mf-test
+   /mf-build
    Fix until green.
 
 3. /mf-review → /mf-commit
@@ -392,21 +401,21 @@ docs/specs/<feature>/
 
 **Token cost:** 15-30k (uses parallel subagents, doesn't bloat main context)
 
-### /mf-test — Write + Run Tests
+### /mf-build — TDD Delivery Loop
 
 **Usage:**
 ```
-/mf-test                              # test all changes vs base branch
-/mf-test src/api/users.ts             # test specific file
-/mf-test "user authentication"        # test specific feature
+/mf-build                              # build all changes vs base branch
+/mf-build src/api/users.ts             # build specific file
+/mf-build "user authentication"        # build specific feature
 ```
 
 **How it works:**
 
 1. **Phase 0: Build Context** — Finds changed files vs base branch, reads the spec (acceptance scenarios in `## Stories` section are the roadmap), reads existing tests for patterns, fixtures, and naming conventions. Doesn't duplicate what already exists.
-2. **Phase 1: Write Tests** — Creates or updates tests based on acceptance scenarios. Each test covers one concept, is independent, deterministic (no random, no time-dependent, no external calls), and has a clear name.
+2. **Phase 1: Write Failing Tests** — Creates tests from acceptance scenarios (RED). Each test covers one AS, is independent, deterministic (no random, no time-dependent, no external calls), and has a clear name.
 3. **Phase 2: Compile First** — Runs typecheck/compile before executing tests. Catches syntax errors early.
-4. **Phase 3: Run Tests** — Executes the test suite.
+4. **Phase 3: Implement + Run** — Implements story code, executes tests, drives to GREEN story by story.
 5. **Phase 4: Fix Loop** — If tests fail, fixes **test code only** (max 3 attempts, then hard stop and report). If tests expect X but code does Y, asks you whether to fix production code or adjust the test.
 6. **Phase 5: Report** — Summary with test counts, results, coverage, and files touched.
 
@@ -836,12 +845,12 @@ Add project-specific rules to `.claude/CLAUDE.md`:
 - All strings must be localized via i18n keys
 ```
 
-### Adding Custom Commands
+### Adding Custom Skills
 
-Create new `.md` files in `.claude/commands/`:
+Create new skills in `.claude/skills/<name>/SKILL.md`:
 
 ```markdown
-# .claude/commands/deploy.md
+# .claude/skills/deploy/SKILL.md
 
 Run the deployment pipeline:
 1. /mf-review
@@ -858,7 +867,7 @@ Then use: `/deploy staging`
 
 | Activity | Tokens | Frequency |
 |----------|--------|-----------|
-| `/mf-test` (incremental, 1-3 files) | 5–10k | Every code chunk |
+| `/mf-build` (incremental, 1-3 files) | 5–10k | Every code chunk |
 | `/mf-fix` (single bug) | 3–5k | As needed |
 | `/mf-commit` | 2–4k | Every commit |
 | `/mf-review` (diff-based) | 10–20k | Before merge |
@@ -868,9 +877,9 @@ Then use: `/deploy staging`
 
 ### Minimizing Token Usage
 
-- **Test incrementally.** `/mf-test` after each small chunk uses 5-10k. Waiting until everything is done then running `/mf-test` on a large diff uses 50k+.
-- **Use filters.** `/mf-test src/auth/login.ts` is cheaper than `/mf-test` on the whole project.
-- **Skip `/mf-plan` for tiny changes.** Under 5 lines with no behavior change? Just `/mf-test` and `/mf-commit`.
+- **Test incrementally.** `/mf-build` after each small chunk uses 5-10k. Waiting until everything is done then running `/mf-build` on a large diff uses 50k+.
+- **Use filters.** `/mf-build src/auth/login.ts` is cheaper than `/mf-build` on the whole project.
+- **Skip `/mf-plan` for tiny changes.** Under 5 lines with no behavior change? Just `/mf-build` and `/mf-commit`.
 - **Use `/mf-review` only before merge.** Not after every commit.
 
 ---
@@ -898,7 +907,7 @@ Then use: `/deploy staging`
 
 ### Wrong base branch
 
-**Symptom:** `/mf-test` or `/mf-review` compares against wrong branch.
+**Symptom:** `/mf-build` or `/mf-review` compares against wrong branch.
 
 **Check:**
 ```bash
@@ -928,13 +937,13 @@ export FILE_GUARD_EXCLUDE="*.generated.swift,*.pb.go,*.min.js,*.snap"
 ## 12. FAQ
 
 **Q: Do I need specs for every tiny change?**
-A: No. Changes under 5 lines with no behavior change can skip the spec. Just `/mf-test` and `/mf-commit`. The spec-first rule is for meaningful behavior changes.
+A: No. Changes under 5 lines with no behavior change can skip the spec. Just `/mf-build` and `/mf-commit`. The spec-first rule is for meaningful behavior changes.
 
 **Q: Can I use mocks in tests?**
 A: Only for external services you can't run locally (third-party APIs, email services). Never mock your own code or database just to make tests pass faster.
 
 **Q: What if Claude writes a test that tests the wrong thing?**
-A: This usually means the spec is ambiguous. Clarify the spec first, then re-run `/mf-test`. Good specs produce good tests.
+A: This usually means the spec is ambiguous. Clarify the spec first, then re-run `/mf-build`. Good specs produce good tests.
 
 **Q: Can I use this with other AI coding tools?**
 A: The commands and hooks are Claude Code-specific. The specs, workflow, and `build-test.sh` work with any tool or manual workflow.
@@ -948,8 +957,8 @@ A: This is intentionally not a command (it's expensive and rare). When needed, p
 **Q: What if my project uses multiple languages?**
 A: `build-test.sh` detects the first match. For monorepos, you may need to run it from each sub-project directory or customize the script.
 
-**Q: Can I add more commands?**
-A: Yes. Drop a `.md` file in `.claude/commands/` and it becomes available as a slash command. See [Customization](#9-customization).
+**Q: Can I add more skills?**
+A: Yes. Create a directory `.claude/skills/<name>/SKILL.md` and it becomes available as a slash command. See [Customization](#9-customization).
 
 **Q: How do I update the kit in existing projects?**
 A: Run `npx claude-devkit-cli upgrade`. It automatically detects which files you've customized and only updates unchanged files. Use `--force` to overwrite everything.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-devkit-cli",
-  "version": "1.3.3",
+  "version": "1.4.0",
   "description": "CLI toolkit for spec-first development with Claude Code — hooks, commands, guards, and test runners",
   "bin": {
     "claude-devkit": "./bin/devkit.js",

package/src/cli.js

@@ -18,7 +18,8 @@ export function cli(argv) {
     .command('init [path]')
     .description('Initialize a project with the dev-kit')
     .option('-f, --force', 'Overwrite existing files')
-    .option('--only <components>', 'Install only specific components (comma-separated: hooks,commands,scripts,docs,config)')
+    .option('-g, --global', 'Install skills globally to ~/.claude/skills/ (available in all projects)')
+    .option('--only <components>', 'Install only specific components (comma-separated: hooks,skills,scripts,docs,config)')
     .option('--adopt', 'Adopt existing kit files without overwriting (migration from setup.sh)')
     .option('--dry-run', 'Show what would be done without making changes')
     .action(async (path, opts) => {
@@ -30,6 +31,7 @@ export function cli(argv) {
     .command('upgrade [path]')
     .description('Smart upgrade — preserves customized files')
     .option('-f, --force', 'Overwrite even customized files')
+    .option('-g, --global', 'Upgrade skills globally in ~/.claude/skills/')
     .option('--dry-run', 'Show what would be done without making changes')
     .action(async (path, opts) => {
       const { upgradeCommand } = await import('./commands/upgrade.js');
@@ -63,9 +65,10 @@ export function cli(argv) {
   program
     .command('remove [path]')
     .description('Uninstall dev-kit (preserves CLAUDE.md and docs/)')
-    .action(async (path) => {
+    .option('-g, --global', 'Remove global install (~/.claude/skills/, ~/.claude/hooks/, hook entries from ~/.claude/settings.json)')
+    .action(async (path, opts) => {
       const { removeCommand } = await import('./commands/remove.js');
-      await removeCommand(path || '.');
+      await removeCommand(path || '.', opts);
     });
 
   program.parse(argv);

package/src/commands/init.js

@@ -1,19 +1,96 @@
-import { resolve } from 'node:path';
+import { resolve, join, dirname } from 'node:path';
 import { existsSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
-import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { log } from '../lib/logger.js';
 import { detectProject } from '../lib/detector.js';
 import { readManifest, writeManifest, createManifest, setFileEntry } from '../lib/manifest.js';
 import { hashFile } from '../lib/hasher.js';
+import { homedir } from 'node:os';
+import { mkdir } from 'node:fs/promises';
 import {
   getAllFiles, getFilesForComponents, installFile,
   ensurePlaceholderDir, setPermissions, fillTemplate,
   verifySettingsJson, PLACEHOLDER_DIRS, COMPONENTS,
-  getTemplateDir,
+  getTemplateDir, installSkillGlobal, getGlobalSkillsDir,
+  installHookGlobal, getGlobalHooksDir, mergeGlobalSettings,
 } from '../lib/installer.js';
+import { readFile, writeFile } from 'node:fs/promises';
+
+const GLOBAL_MANIFEST = join(homedir(), '.claude', '.devkit-manifest.json');
+
+async function readGlobalManifest() {
+  try {
+    return JSON.parse(await readFile(GLOBAL_MANIFEST, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+async function writeGlobalManifest(data) {
+  await mkdir(join(homedir(), '.claude'), { recursive: true });
+  await writeFile(GLOBAL_MANIFEST, JSON.stringify(data, null, 2) + '\n');
+}
+
+export async function initGlobal({ force = false, hooks = false } = {}) {
+  const globalSkillsDir = getGlobalSkillsDir();
+  await mkdir(globalSkillsDir, { recursive: true });
+
+  log.blank();
+  console.log('--- Installing global skills ---');
+
+  let copied = 0; let skipped = 0; let identical = 0;
+  for (const relPath of COMPONENTS.skills) {
+    const result = await installSkillGlobal(relPath, globalSkillsDir, { force });
+    if (result === 'copied') copied++;
+    else if (result === 'identical') identical++;
+    else skipped++;
+  }
+
+  const parts = [`${copied} copied`];
+  if (identical > 0) parts.push(`${identical} identical`);
+  if (skipped > 0) parts.push(`${skipped} customized (use --force to overwrite)`);
+  log.pass(`Global skills: ${parts.join(', ')}`);
+  log.info('Skills available in all projects via ~/.claude/skills/');
+
+  if (hooks) {
+    await initGlobalHooks({ force });
+  }
+
+  // Write global manifest
+  const existing = await readGlobalManifest() || {};
+  await writeGlobalManifest({
+    ...existing,
+    globalInstalled: true,
+    globalHooksInstalled: hooks || existing.globalHooksInstalled || false,
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+export async function initGlobalHooks({ force = false } = {}) {
+  const globalHooksDir = getGlobalHooksDir();
+  await mkdir(globalHooksDir, { recursive: true });
+
+  log.blank();
+  console.log('--- Installing global hooks ---');
+
+  let copied = 0; let skipped = 0; let identical = 0;
+  for (const relPath of COMPONENTS.hooks) {
+    const result = await installHookGlobal(relPath, globalHooksDir, { force });
+    if (result === 'copied') copied++;
+    else if (result === 'identical') identical++;
+    else skipped++;
+  }
+
+  await mergeGlobalSettings(globalHooksDir);
+
+  const parts = [`${copied} copied`];
+  if (identical > 0) parts.push(`${identical} identical`);
+  if (skipped > 0) parts.push(`${skipped} customized (use --force to overwrite)`);
+  log.pass(`Global hooks: ${parts.join(', ')}`);
+  log.info('Hooks registered in ~/.claude/settings.json — active in all projects');
+}
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf-8'));
@@ -30,6 +107,12 @@ export async function initCommand(path, opts) {
   log.info(`Target: ${targetDir}`);
   log.blank();
 
+  // --- Global mode ---
+  if (opts.global) {
+    await initGlobal({ force: opts.force, hooks: true });
+    return;
+  }
+
   // --- Adopt mode ---
   if (opts.adopt) {
     await adoptExisting(targetDir);
@@ -164,7 +247,7 @@ export async function initCommand(path, opts) {
   console.log('  .claude/CLAUDE.md          — Project rules (review and customize)');
   console.log('  .claude/settings.json      — Hook configuration');
   console.log('  .claude/hooks/             — 6 guards (file, path, glob, comment, sensitive, self-review)');
-  console.log('  .claude/commands/          — /mf-plan, /mf-challenge, /mf-test, /mf-fix, /mf-review, /mf-commit');
+  console.log('  .claude/skills/            — /mf-plan, /mf-challenge, /mf-build, /mf-fix, /mf-review, /mf-commit');
   console.log('  scripts/build-test.sh      — Universal test runner');
   console.log('  docs/WORKFLOW.md           — Workflow reference');
   log.blank();
@@ -177,12 +260,84 @@ export async function initCommand(path, opts) {
   console.log('  1. Review .claude/CLAUDE.md — ensure project info is correct');
   console.log('  2. Write your first spec:   docs/specs/<feature>.md');
   console.log('  3. Generate test plan:      /mf-plan docs/specs/<feature>.md');
-  console.log('  4. Start coding + testing:  /mf-test');
+  console.log('  4. Start coding + testing:  /mf-build');
   log.blank();
 
   if (warnings > 0) {
     console.log(`⚠ ${warnings} warning(s) above — review before proceeding.`);
   }
+
+  // --- Global install prompt (first-time only) ---
+  if (!opts.global) {
+    const globalMeta = await readGlobalManifest();
+    if (globalMeta?.globalInstalled === undefined) {
+      await promptGlobalInstall(opts);
+    } else if (globalMeta?.globalInstalled === true) {
+      // Auto-upgrade global on init if previously installed
+      await initGlobal({ force: opts.force });
+    }
+  }
+}
+
+async function promptGlobalInstall(opts) {
+  log.blank();
+  console.log('─── Global Install ───');
+  console.log('');
+  console.log('Skills and hooks are installed per-project by default.');
+  console.log('You can install them globally so every project is covered without running init again.');
+  console.log('');
+  console.log('  ~/.claude/skills/   ← global skills (fallback when no per-project skills)');
+  console.log('  ~/.claude/hooks/    ← global hooks  (active in all projects)');
+  console.log('  .claude/skills/     ← per-project skills (takes precedence over global)');
+  console.log('  .claude/hooks/      ← per-project hooks  (takes precedence over global)');
+  console.log('');
+  console.log('To revert global hooks back to per-project later:');
+  console.log('  claude-devkit remove --global');
+  console.log('  then: claude-devkit init  (in each project)');
+  console.log('');
+  console.log('RECOMMENDATION: Choose A if you work across many projects.');
+  console.log('');
+
+  const answer = await askGlobalInstall();
+
+  if (answer === 'skills+hooks') {
+    await initGlobal({ force: opts.force, hooks: true });
+    await trackProjectPath(process.cwd());
+  } else if (answer === 'skills') {
+    await initGlobal({ force: opts.force, hooks: false });
+    await trackProjectPath(process.cwd());
+  } else if (answer === 'no') {
+    await writeGlobalManifest({ globalInstalled: false, updatedAt: new Date().toISOString() });
+    log.info('Skipping global install. Run `claude-devkit init --global` anytime.');
+  }
+  // 'later' = don't write anything, prompt again next time
+}
+
+async function askGlobalInstall() {
+  const { createInterface } = await import('node:readline');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    console.log('A) Skills + Hooks globally  (recommended)');
+    console.log('B) Skills only              (hooks stay per-project)');
+    console.log('C) No — keep everything per-project');
+    console.log('D) Ask me next time');
+    console.log('');
+    rl.question('Choice [A/B/C/D]: ', (answer) => {
+      rl.close();
+      const a = answer.trim().toUpperCase();
+      if (a === 'A') resolve('skills+hooks');
+      else if (a === 'B') resolve('skills');
+      else if (a === 'C') resolve('no');
+      else resolve('later');
+    });
+  });
+}
+
+async function trackProjectPath(projectPath) {
+  const meta = await readGlobalManifest() || {};
+  const projects = new Set(meta.projects || []);
+  projects.add(projectPath);
+  await writeGlobalManifest({ ...meta, projects: [...projects] });
 }
 
 /**

package/src/commands/remove.js

@@ -1,8 +1,10 @@
 import { resolve, join } from 'node:path';
 import { unlink, rmdir, rm } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { log } from '../lib/logger.js';
 import { readManifest } from '../lib/manifest.js';
+import { removeGlobalHooksFromSettings } from '../lib/installer.js';
 
 const PRESERVE = [
   '.claude/CLAUDE.md',
@@ -12,7 +14,50 @@ const PRESERVE_DIRS = [
   'docs/',
 ];
 
-export async function removeCommand(path) {
+export async function removeGlobal() {
+  log.info('Removing global claude-devkit install...');
+  log.blank();
+
+  // Remove ~/.claude/skills/
+  const globalSkillsDir = join(homedir(), '.claude', 'skills');
+  if (existsSync(globalSkillsDir)) {
+    await rm(globalSkillsDir, { recursive: true, force: true });
+    log.del('~/.claude/skills/');
+  } else {
+    log.skip('~/.claude/skills/ (not found)');
+  }
+
+  // Remove ~/.claude/hooks/
+  const globalHooksDir = join(homedir(), '.claude', 'hooks');
+  if (existsSync(globalHooksDir)) {
+    await rm(globalHooksDir, { recursive: true, force: true });
+    log.del('~/.claude/hooks/');
+  } else {
+    log.skip('~/.claude/hooks/ (not found)');
+  }
+
+  // Remove devkit hook entries from ~/.claude/settings.json
+  await removeGlobalHooksFromSettings();
+  log.del('hook entries from ~/.claude/settings.json');
+
+  // Remove global manifest
+  const globalManifest = join(homedir(), '.claude', '.devkit-manifest.json');
+  if (existsSync(globalManifest)) {
+    await unlink(globalManifest);
+    log.del('~/.claude/.devkit-manifest.json');
+  }
+
+  log.blank();
+  log.pass('Global install removed. Per-project installs are unaffected.');
+  log.info('Run `claude-devkit init` in each project to restore per-project hooks.');
+}
+
+export async function removeCommand(path, opts = {}) {
+  if (opts.global) {
+    await removeGlobal();
+    return;
+  }
+
   const targetDir = resolve(path);
   const manifest = await readManifest(targetDir);
 
@@ -56,7 +101,6 @@ export async function removeCommand(path) {
   // Clean up empty directories
   const dirsToClean = [
     '.claude/hooks',
-    '.claude/commands',
     'scripts',
   ];
 
@@ -69,6 +113,13 @@ export async function removeCommand(path) {
     }
   }
 
+  // Skills are nested dirs — use recursive rm
+  const skillsDir = join(targetDir, '.claude/skills');
+  if (existsSync(skillsDir)) {
+    await rm(skillsDir, { recursive: true, force: true });
+    log.del('.claude/skills/');
+  }
+
   log.blank();
   log.pass('Removed. CLAUDE.md and docs/ preserved.');
 }

package/src/commands/upgrade.js

@@ -1,18 +1,92 @@
-import { resolve } from 'node:path';
+import { resolve, dirname, join } from 'node:path';
 import { existsSync } from 'node:fs';
-import { copyFile as fsCopyFile, mkdir } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { copyFile as fsCopyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
 import { log } from '../lib/logger.js';
 import { hashFile } from '../lib/hasher.js';
 import { readManifest, writeManifest, setFileEntry, refreshCustomizationStatus } from '../lib/manifest.js';
-import { getAllFiles, getTemplateDir, setPermissions } from '../lib/installer.js';
+import { getAllFiles, getTemplateDir, setPermissions, COMPONENTS, installSkillGlobal, getGlobalSkillsDir, installHookGlobal, getGlobalHooksDir, mergeGlobalSettings } from '../lib/installer.js';
+
+const GLOBAL_MANIFEST = join(homedir(), '.claude', '.devkit-manifest.json');
+
+async function readGlobalManifest() {
+  try { return JSON.parse(await readFile(GLOBAL_MANIFEST, 'utf-8')); } catch { return null; }
+}
+async function writeGlobalManifest(data) {
+  await mkdir(join(homedir(), '.claude'), { recursive: true });
+  await writeFile(GLOBAL_MANIFEST, JSON.stringify(data, null, 2) + '\n');
+}
+
+export async function upgradeGlobal({ force = false } = {}) {
+  const globalSkillsDir = getGlobalSkillsDir();
+  await mkdir(globalSkillsDir, { recursive: true });
+
+  log.blank();
+  console.log('--- Upgrading global skills ---');
+  let updated = 0; let skipped = 0; let identical = 0;
+
+  for (const relPath of COMPONENTS.skills) {
+    const result = await installSkillGlobal(relPath, globalSkillsDir, { force });
+    if (result === 'copied') updated++;
+    else if (result === 'identical') identical++;
+    else skipped++;
+  }
+
+  let skillParts = [`${updated} updated`, `${identical} unchanged`];
+  if (skipped > 0) skillParts.push(`${skipped} customized (use --force to overwrite)`);
+  log.pass(`Global skills: ${skillParts.join(', ')}`);
+
+  const meta = await readGlobalManifest() || {};
+
+  // Upgrade hooks if previously installed globally
+  if (meta.globalHooksInstalled) {
+    const globalHooksDir = getGlobalHooksDir();
+    await mkdir(globalHooksDir, { recursive: true });
+
+    log.blank();
+    console.log('--- Upgrading global hooks ---');
+    let hUpdated = 0; let hSkipped = 0; let hIdentical = 0;
+
+    for (const relPath of COMPONENTS.hooks) {
+      const result = await installHookGlobal(relPath, globalHooksDir, { force });
+      if (result === 'copied') hUpdated++;
+      else if (result === 'identical') hIdentical++;
+      else hSkipped++;
+    }
+
+    await mergeGlobalSettings(globalHooksDir);
+
+    let hookParts = [`${hUpdated} updated`, `${hIdentical} unchanged`];
+    if (hSkipped > 0) hookParts.push(`${hSkipped} customized (use --force to overwrite)`);
+    log.pass(`Global hooks: ${hookParts.join(', ')}`);
+  }
+
+  await writeGlobalManifest({ ...meta, globalInstalled: true, updatedAt: new Date().toISOString() });
+
+  // Warn about per-project skills that shadow global
+  const projects = meta.projects || [];
+  const projectsWithSkills = projects.filter((p) => existsSync(join(p, '.claude/skills')));
+  if (projectsWithSkills.length > 0) {
+    log.blank();
+    log.info(`Found per-project skills in ${projectsWithSkills.length} project(s):`);
+    for (const p of projectsWithSkills) log.info(`  ${p}`);
+    log.info('Per-project skills take precedence over global. Remove them to use global instead.');
+    log.info('Run `claude-devkit remove <path>` in each project to remove per-project install.');
+  }
+}
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf-8'));
 
 export async function upgradeCommand(path, opts) {
+  // --- Global mode ---
+  if (opts.global) {
+    await upgradeGlobal({ force: opts.force });
+    return;
+  }
+
   const targetDir = resolve(path);
   const manifest = await readManifest(targetDir);
 
@@ -122,4 +196,10 @@ export async function upgradeCommand(path, opts) {
   if (skippedCustomized > 0) {
     log.warn(`${skippedCustomized} customized file(s) skipped. Run with --force to overwrite.`);
   }
+
+  // --- Auto-upgrade global if previously installed ---
+  const globalMeta = await readGlobalManifest();
+  if (globalMeta?.globalInstalled === true) {
+    await upgradeGlobal({ force: opts.force });
+  }
 }