sdtk-kit 0.3.3 → 0.3.4

package/README.md

@@ -36,7 +36,9 @@ sdtk generate --feature-key USER_PROFILE --feature-name "User Profile"
 Initialize SDTK workspace in the current or specified project directory.
 
 ```bash
-sdtk init --runtime <codex|claude> [--project-path <path>] [--force] [--skip-skills]
+sdtk init --runtime <codex|claude> [--project-path <path>] [--force] [--runtime-scope <project|user>] [--skip-runtime-assets]
+
+# Deprecated: --skip-skills (use --skip-runtime-assets instead)
 ```
 
 Creates:
@@ -44,7 +46,9 @@ Creates:
 - `sdtk.config.json` -- project configuration
 - `sdtk.config.profiles.example.json` -- stack profile examples
 - `CODEX.md` or `CLAUDE.md` -- runtime adapter
-- for `--runtime claude`, local `.claude/skills` and `.claude/skills/references` are installed unless `--skip-skills` is used
+- for `--runtime claude`, skill files are installed into `.claude/skills/` (project scope, default) or `~/.claude/skills/` (user scope) unless `--skip-runtime-assets` is used
+- for `--runtime codex`, skill files are installed into `$CODEX_HOME/skills/` or `~/.codex/skills/` (user scope only) unless `--skip-runtime-assets` is used
+- `--skip-skills` is deprecated; use `--skip-runtime-assets` instead
 
 ### `sdtk auth`
 
@@ -83,6 +87,36 @@ sdtk generate --feature-key <UPPER_SNAKE_CASE> --feature-name "<text>" [--projec
 
 Output files include: project initiation, BA spec, flow-action spec, PRD, backlog, architecture design, database spec, API specs (OpenAPI + endpoints + design detail + flow list), UI design layout, implementation plan, test cases, and QA release report.
 
+### `sdtk runtime`
+
+Manage runtime skill assets independently of `sdtk init`.
+
+```bash
+sdtk runtime install --runtime <codex|claude> [--scope <project|user>]
+sdtk runtime uninstall --runtime <codex|claude> [--scope <project|user>]
+sdtk runtime status --runtime <codex|claude>
+```
+
+Scope defaults:
+- `claude`: `project` (installs to `.claude/skills/`); `user` installs to `~/.claude/skills/`
+- `codex`: `user` only (installs to `$CODEX_HOME/skills/` or `~/.codex/skills/`); project scope is not supported (Gate C0)
+
+Examples:
+
+```bash
+# Install Claude skills at project scope (default)
+sdtk runtime install --runtime claude
+
+# Install Claude skills at user scope
+sdtk runtime install --runtime claude --scope user
+
+# Check installed runtime assets
+sdtk runtime status --runtime claude
+
+# Remove runtime assets
+sdtk runtime uninstall --runtime claude --scope project
+```
+
 ### `sdtk --help` / `sdtk --version`
 
 ```bash

package/assets/manifest/toolkit-bundle.manifest.json

@@ -1,5 +1,5 @@
 {
-    "buildTimestamp":  "2026-03-07T00:53:22Z",
+    "buildTimestamp":  "2026-03-07T02:40:24Z",
     "files":  [
                   {
                       "path":  "toolkit/AGENTS.md",
@@ -8,8 +8,8 @@
                   },
                   {
                       "path":  "toolkit/install.ps1",
-                      "sha256":  "531da17e88a05b6946a5012f7b13a2871212df1fe0d052720f9511e02aba7e32",
-                      "size":  8830
+                      "sha256":  "e717a2791fb597d7a21f57f4c4790dbc545e954f0af3ca0c47f160f78c8a2474",
+                      "size":  9777
                   },
                   {
                       "path":  "toolkit/runtimes/claude/CLAUDE_TEMPLATE.md",
@@ -26,10 +26,20 @@
                       "sha256":  "5c1f5442fd3c26b8bf62db4b25e9f1c4207258c7fe52f12ed533968f77dfbf65",
                       "size":  10557
                   },
+                  {
+                      "path":  "toolkit/scripts/install-claude-skills.ps1",
+                      "sha256":  "8c66c27262ad4abc3c42bbcbe3a97752a5f29956ac93397133e6780354911549",
+                      "size":  4315
+                  },
                   {
                       "path":  "toolkit/scripts/install-codex-skills.ps1",
-                      "sha256":  "68a82e421d0309e47cdb79e949b1044c17375ad7fd52e2ab9ccdc9dd33f8cdd0",
-                      "size":  9175
+                      "sha256":  "ca64e0c2a0f13137bc6b780a57442de46a3e0551778bbcbadd4eb779c21cb203",
+                      "size":  9427
+                  },
+                  {
+                      "path":  "toolkit/scripts/uninstall-claude-skills.ps1",
+                      "sha256":  "809ffc1f96528ac1cd453214cd1c2d231ca0753f0d3c19b4a20f11835a64a152",
+                      "size":  4482
                   },
                   {
                       "path":  "toolkit/scripts/uninstall-codex-skills.ps1",
@@ -397,7 +407,7 @@
                       "size":  3255
                   }
               ],
-    "sourceCommit":  "4437ad41659a38e9e80dcbf32cb03f9b6df64e0d",
-    "version":  "0.3.3",
-    "fileCount":  79
+    "sourceCommit":  "965d6ad1f80a42b8b49c4296ec7a96ffef2655e3",
+    "version":  "0.3.4",
+    "fileCount":  81
 }

package/assets/manifest/toolkit-bundle.sha256.txt

@@ -1,9 +1,11 @@
 868430474b46e4e8d27ed26b780a794936e84cf4f0278f2cc3d061f54877f498  toolkit/AGENTS.md
-531da17e88a05b6946a5012f7b13a2871212df1fe0d052720f9511e02aba7e32  toolkit/install.ps1
+e717a2791fb597d7a21f57f4c4790dbc545e954f0af3ca0c47f160f78c8a2474  toolkit/install.ps1
 0f3e0bfe1b5165250f0da4da5790a9e6220023752713088a0076eb7f17fd6397  toolkit/runtimes/claude/CLAUDE_TEMPLATE.md
 4154c15c71f44d2f2caf07fb41722fa65d4f9ec7e78f798ee084effd12345c62  toolkit/runtimes/codex/CODEX_TEMPLATE.md
 5c1f5442fd3c26b8bf62db4b25e9f1c4207258c7fe52f12ed533968f77dfbf65  toolkit/scripts/init-feature.ps1
-68a82e421d0309e47cdb79e949b1044c17375ad7fd52e2ab9ccdc9dd33f8cdd0  toolkit/scripts/install-codex-skills.ps1
+8c66c27262ad4abc3c42bbcbe3a97752a5f29956ac93397133e6780354911549  toolkit/scripts/install-claude-skills.ps1
+ca64e0c2a0f13137bc6b780a57442de46a3e0551778bbcbadd4eb779c21cb203  toolkit/scripts/install-codex-skills.ps1
+809ffc1f96528ac1cd453214cd1c2d231ca0753f0d3c19b4a20f11835a64a152  toolkit/scripts/uninstall-claude-skills.ps1
 e0d462bd6dcdb17cc003d459063ff341bd2e4f60b245cda9b7e9b9e94b3cf01f  toolkit/scripts/uninstall-codex-skills.ps1
 de2921da9ce504487d9c7d97bf862b65d0ba00b9f1593a4fbfadf41ac36adb49  toolkit/sdtk.config.json
 21b1b0212f85c76dc6a89ae5936b39c4c1df7837a333f7a3db337f3039babb7b  toolkit/sdtk.config.profiles.example.json

package/assets/toolkit/toolkit/install.ps1

@@ -2,9 +2,12 @@ param(
   [string]$ProjectPath,
   [switch]$Force,
   [switch]$SkipSkills,
+  [switch]$SkipRuntimeAssets,
   [switch]$Quiet,
   [ValidateSet('codex', 'claude')]
-  [string]$Runtime = 'codex'
+  [string]$Runtime = 'codex',
+  [ValidateSet('project', 'user', '')]
+  [string]$Scope = ''
 )
 
 $ErrorActionPreference = 'Stop'
@@ -181,6 +184,15 @@ if (-not $ProjectPath) {
 }
 $projectRoot = Resolve-Path -LiteralPath $ProjectPath
 
+# Merge SkipRuntimeAssets and legacy SkipSkills
+if ($SkipRuntimeAssets) { $SkipSkills = $true }
+
+# Default scope: project for Claude, user for Codex
+if (-not $Scope -or $Scope -eq '') {
+  if ($Runtime -eq 'claude') { $Scope = 'project' }
+  else { $Scope = 'user' }
+}
+
 if (-not $Quiet) {
   Write-Host "SDTK toolkit : $toolkitRoot"
   Write-Host "Project root : $projectRoot"
@@ -217,17 +229,29 @@ if (($Runtime -eq 'codex') -and (-not $SkipSkills)) {
   }
 
   Write-Host ""
-  Write-Host "Installing Codex skills globally..."
+  Write-Host "Installing Codex skills (scope: $Scope)..."
   if ($Force) {
-    & $skillInstaller -Force | Out-Host
+    & $skillInstaller -Scope $Scope -Force | Out-Host
   } else {
-    & $skillInstaller | Out-Host
+    & $skillInstaller -Scope $Scope | Out-Host
   }
 }
 elseif (($Runtime -eq 'claude') -and (-not $SkipSkills)) {
-  Write-Host ""
-  Write-Host "Installing Claude Code skills..."
-  Install-ClaudeSkills -ToolkitRoot $toolkitRoot -ProjectRoot $projectRoot -Overwrite ([bool]$Force)
+  $skillInstaller = Join-Path $toolkitRoot 'scripts/install-claude-skills.ps1'
+  if (-not (Test-Path -LiteralPath $skillInstaller)) {
+    # Fallback to inline Install-ClaudeSkills for backward compatibility
+    Write-Host ""
+    Write-Host "Installing Claude Code skills..."
+    Install-ClaudeSkills -ToolkitRoot $toolkitRoot -ProjectRoot $projectRoot -Overwrite ([bool]$Force)
+  } else {
+    Write-Host ""
+    Write-Host "Installing Claude Code skills (scope: $Scope)..."
+    if ($Force) {
+      & $skillInstaller -Scope $Scope -ProjectPath $projectRoot.ToString() -Force | Out-Host
+    } else {
+      & $skillInstaller -Scope $Scope -ProjectPath $projectRoot.ToString() | Out-Host
+    }
+  }
 }
 
 if (-not $Quiet) {

package/assets/toolkit/toolkit/scripts/install-claude-skills.ps1

@@ -0,0 +1,129 @@
+param(
+  [string]$ProjectPath,
+  [ValidateSet('project', 'user')]
+  [string]$Scope = 'project',
+  [switch]$Force
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+
+function Copy-File {
+  param(
+    [Parameter(Mandatory = $true)][string]$SourcePath,
+    [Parameter(Mandatory = $true)][string]$DestinationPath,
+    [Parameter(Mandatory = $true)][bool]$Overwrite
+  )
+
+  if (-not (Test-Path -LiteralPath $SourcePath)) {
+    throw "Missing source: $SourcePath"
+  }
+
+  if (Test-Path -LiteralPath $DestinationPath) {
+    if (-not $Overwrite) {
+      Write-Warning "Already exists (skipping). Use -Force to overwrite: $DestinationPath"
+      return
+    }
+  }
+
+  $parent = Split-Path -Parent $DestinationPath
+  if ($parent -and -not (Test-Path -LiteralPath $parent)) {
+    New-Item -ItemType Directory -Force -Path $parent | Out-Null
+  }
+
+  Copy-Item -LiteralPath $SourcePath -Destination $DestinationPath -Force
+}
+
+$toolkitRoot = Resolve-Path (Join-Path $PSScriptRoot '..')
+
+# Resolve destination based on scope
+if ($Scope -eq 'user') {
+  $skillsDest = Join-Path $HOME '.claude/skills'
+  Write-Host "Scope: user (installing to $skillsDest)"
+} else {
+  if (-not $ProjectPath) {
+    $ProjectPath = (Resolve-Path (Join-Path $toolkitRoot '..')).Path
+  }
+  $projectRoot = Resolve-Path -LiteralPath $ProjectPath
+  $skillsDest = Join-Path $projectRoot '.claude/skills'
+  Write-Host "Scope: project (installing to $skillsDest)"
+}
+
+$skillsSource = Join-Path $toolkitRoot 'skills-claude'
+if (-not (Test-Path -LiteralPath $skillsSource)) {
+  throw "Claude skills source not found: $skillsSource"
+}
+
+$skillCount = 0
+foreach ($skillDir in (Get-ChildItem -Path $skillsSource -Directory)) {
+  $srcFile = Join-Path $skillDir.FullName 'SKILL.md'
+  if (-not (Test-Path -LiteralPath $srcFile)) { continue }
+
+  $destFile = Join-Path $skillsDest "$($skillDir.Name)/SKILL.md"
+  Copy-File -SourcePath $srcFile -DestinationPath $destFile -Overwrite ([bool]$Force)
+  $skillCount++
+}
+
+# Install reference files
+$refDest = Join-Path $skillsDest 'references'
+if (-not (Test-Path -LiteralPath $refDest)) {
+  New-Item -ItemType Directory -Force -Path $refDest | Out-Null
+}
+
+$refCount = 0
+$missingRefs = @()
+
+# 6 files from toolkit/templates/docs/
+$templateRefs = @(
+  @{ Src = 'templates/docs/api/YAML_CREATION_RULES.md' },
+  @{ Src = 'templates/docs/api/API_DESIGN_FLOWCHART_CREATION_RULES.md' },
+  @{ Src = 'templates/docs/api/FLOWCHART_CREATION_RULES.md' },
+  @{ Src = 'templates/docs/api/API_DESIGN_CREATION_RULES.md' },
+  @{ Src = 'templates/docs/specs/FLOW_ACTION_SPEC_CREATION_RULES.md' },
+  @{ Src = 'templates/docs/qa/TEST_CASE_CREATION_RULES.md' }
+)
+
+foreach ($ref in $templateRefs) {
+  $srcPath = Join-Path $toolkitRoot $ref.Src
+  $fileName = Split-Path -Leaf $srcPath
+  $destPath = Join-Path $refDest $fileName
+  if (Test-Path -LiteralPath $srcPath) {
+    Copy-File -SourcePath $srcPath -DestinationPath $destPath -Overwrite ([bool]$Force)
+    $refCount++
+  } else {
+    $missingRefs += $srcPath
+  }
+}
+
+# 3 files from toolkit/skills/sdtk-screen-design-spec/references/
+$screenRefs = @('numbering-rules.md', 'figma-mcp.md', 'excel-image-export.md')
+foreach ($fileName in $screenRefs) {
+  $srcPath = Join-Path $toolkitRoot "skills/sdtk-screen-design-spec/references/$fileName"
+  $destPath = Join-Path $refDest $fileName
+  if (Test-Path -LiteralPath $srcPath) {
+    Copy-File -SourcePath $srcPath -DestinationPath $destPath -Overwrite ([bool]$Force)
+    $refCount++
+  } else {
+    $missingRefs += $srcPath
+  }
+}
+
+# Fail-fast: abort if any reference files are missing
+if ($missingRefs.Count -gt 0) {
+  $list = ($missingRefs | ForEach-Object { "  - $_" }) -join "`n"
+  throw "Claude install failed. Missing reference files:`n$list"
+}
+
+# Strict count assertions
+$expectedSkills = 13
+$expectedRefs = 9
+if ($skillCount -ne $expectedSkills) {
+  throw "Claude install failed. Expected $expectedSkills skills but installed $skillCount."
+}
+if ($refCount -ne $expectedRefs) {
+  throw "Claude install failed. Expected $expectedRefs reference files but installed $refCount."
+}
+
+Write-Host "  Skills installed: $skillCount"
+Write-Host "  Reference files : $refCount"
+Write-Host "  Destination     : $skillsDest"

package/assets/toolkit/toolkit/scripts/install-codex-skills.ps1

@@ -1,7 +1,15 @@
 param(
+  [ValidateSet('project', 'user')]
+  [string]$Scope = 'user',
   [switch]$Force
 )
 
+# Gate C0: Codex does not support project-local skills
+if ($Scope -eq 'project') {
+  Write-Error "Codex does not support project-local skills. Use --scope user instead."
+  exit 1
+}
+
 $ErrorActionPreference = 'Stop'
 Set-StrictMode -Version Latest
 

package/assets/toolkit/toolkit/scripts/uninstall-claude-skills.ps1

@@ -0,0 +1,139 @@
+param(
+  [string]$ProjectPath,
+  [ValidateSet('project', 'user')]
+  [string]$Scope = 'project',
+  [string]$SkillName,
+  [switch]$All,
+  [switch]$BackupExisting,
+  [string]$BackupPath
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+
+function Backup-Directory {
+  param(
+    [Parameter(Mandatory = $true)][string]$SourcePath,
+    [Parameter(Mandatory = $true)][string]$BackupRoot,
+    [Parameter(Mandatory = $true)][string]$Name
+  )
+
+  if (-not (Test-Path -LiteralPath $SourcePath)) {
+    return $null
+  }
+
+  New-Item -ItemType Directory -Force -Path $BackupRoot | Out-Null
+  $dest = Join-Path $BackupRoot $Name
+  if (Test-Path -LiteralPath $dest) {
+    Remove-Item -LiteralPath $dest -Recurse -Force
+  }
+  Copy-Item -LiteralPath $SourcePath -Destination $dest -Recurse -Force
+  return $dest
+}
+
+if ($All -and $SkillName) {
+  throw "Use either -All or -SkillName, not both."
+}
+
+$toolkitRoot = Resolve-Path (Join-Path $PSScriptRoot '..')
+$skillsSrc = Join-Path $toolkitRoot 'skills-claude'
+if (-not (Test-Path -LiteralPath $skillsSrc)) {
+  throw "Missing toolkit Claude skills source directory: $skillsSrc"
+}
+
+$managedSkillNames = Get-ChildItem -LiteralPath $skillsSrc -Directory | Select-Object -ExpandProperty Name
+if (-not $managedSkillNames -or $managedSkillNames.Count -eq 0) {
+  throw "No managed Claude skills found in: $skillsSrc"
+}
+
+$targetNames = @()
+if ($SkillName) {
+  if ($managedSkillNames -notcontains $SkillName) {
+    throw "Skill '$SkillName' is not in managed Claude skills list. Known skills: $($managedSkillNames -join ', ')"
+  }
+  $targetNames = @($SkillName)
+} elseif ($All) {
+  $targetNames = @($managedSkillNames)
+} else {
+  $targetNames = @($managedSkillNames)
+}
+
+# Resolve destination based on scope
+if ($Scope -eq 'user') {
+  $skillsDest = Join-Path $HOME '.claude/skills'
+} else {
+  if (-not $ProjectPath) {
+    $ProjectPath = (Resolve-Path (Join-Path $toolkitRoot '..')).Path
+  }
+  $projectRoot = Resolve-Path -LiteralPath $ProjectPath
+  $skillsDest = Join-Path $projectRoot '.claude/skills'
+}
+
+if (-not (Test-Path -LiteralPath $skillsDest)) {
+  Write-Host "Claude skills directory not found: $skillsDest"
+  exit 0
+}
+
+$backupRootResolved = $null
+if ($BackupExisting) {
+  if (-not $BackupPath -or $BackupPath.Trim().Length -eq 0) {
+    $timestamp = Get-Date -Format 'yyyyMMdd-HHmmss'
+    $parentDir = if ($Scope -eq 'user') { Join-Path $HOME '.claude' } else { $projectRoot }
+    $BackupPath = Join-Path $parentDir (Join-Path 'skills-backups' ("uninstall-" + $timestamp))
+  }
+  New-Item -ItemType Directory -Force -Path $BackupPath | Out-Null
+  $backupRootResolved = (Resolve-Path -LiteralPath $BackupPath).Path
+  Write-Host "Backup mode enabled: $backupRootResolved"
+}
+
+$removed = New-Object System.Collections.Generic.List[string]
+$missing = New-Object System.Collections.Generic.List[string]
+
+foreach ($name in $targetNames) {
+  $dest = Join-Path $skillsDest $name
+  if (-not (Test-Path -LiteralPath $dest)) {
+    $missing.Add($name) | Out-Null
+    Write-Warning "Skill not installed, skipping: $name"
+    continue
+  }
+
+  if ($BackupExisting) {
+    $backupDest = Backup-Directory -SourcePath $dest -BackupRoot $backupRootResolved -Name $name
+    if ($backupDest) {
+      Write-Host "Backed up: $name -> $backupDest"
+    }
+  }
+
+  Remove-Item -LiteralPath $dest -Recurse -Force
+  $removed.Add($name) | Out-Null
+  Write-Host "Uninstalled: $name"
+}
+
+# Also remove references directory if uninstalling all
+if ($All -or (-not $SkillName)) {
+  $refDir = Join-Path $skillsDest 'references'
+  if (Test-Path -LiteralPath $refDir) {
+    if ($BackupExisting) {
+      Backup-Directory -SourcePath $refDir -BackupRoot $backupRootResolved -Name 'references' | Out-Null
+      Write-Host "Backed up: references -> $backupRootResolved/references"
+    }
+    Remove-Item -LiteralPath $refDir -Recurse -Force
+    Write-Host "Removed references directory."
+  }
+}
+
+Write-Host ""
+Write-Host "Uninstall summary:"
+Write-Host "- Scope: $Scope"
+Write-Host "- Destination: $skillsDest"
+Write-Host "- Removed: $($removed.Count)"
+if ($removed.Count -gt 0) {
+  $removed | ForEach-Object { Write-Host "  - $_" }
+}
+Write-Host "- Missing/Skipped: $($missing.Count)"
+if ($missing.Count -gt 0) {
+  $missing | ForEach-Object { Write-Host "  - $_" }
+}
+if ($backupRootResolved) {
+  Write-Host "- Backup directory: $backupRootResolved"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "sdtk-kit",
-    "version":  "0.3.3",
+    "version":  "0.3.4",
     "description":  "SDTK CLI toolkit for deterministic software documentation workflows",
     "bin":  {
                 "sdtk":  "./bin/sdtk.js"

package/src/commands/help.js

@@ -9,15 +9,36 @@ function cmdHelp() {
     "",
     "Commands:",
     "  init      Initialize SDTK workspace (runtime adapter + config)",
+    "  runtime   Manage runtime asset installation (install, uninstall, status)",
     "  auth      Manage GitHub authentication and entitlement",
     "  generate  Scaffold feature documentation from templates (17 files)",
     "",
     "Init options:",
-    "  --runtime <codex|claude>   Runtime adapter (default: codex)",
+    "  --runtime <codex|claude>       Runtime adapter (default: codex)",
+    "  --runtime-scope <project|user> Install scope (default: project for claude, user for codex)",
+    "  --project-path <path>          Target project directory (default: cwd)",
+    "  --force                        Overwrite existing files",
+    "  --skip-runtime-assets          Skip runtime asset installation",
+    "  --skip-skills                  (deprecated, use --skip-runtime-assets)",
+    "  --verbose                      Show detailed PowerShell script output",
+    "",
+    "Runtime subcommands:",
+    "  sdtk runtime install   --runtime <codex|claude> [--scope <project|user>]",
+    "  sdtk runtime uninstall --runtime <codex|claude> [--scope <project|user>] [--all]",
+    "  sdtk runtime status    --runtime <codex|claude>",
+    "",
+    "Runtime options:",
+    "  --runtime <codex|claude>   Target runtime (required)",
+    "  --scope <project|user>     Install scope (default: project for claude, user for codex)",
     "  --project-path <path>      Target project directory (default: cwd)",
-    "  --force                    Overwrite existing files",
-    "  --skip-skills              Skip skill installation (Codex and Claude)",
-    "  --verbose                  Show detailed PowerShell script output",
+    "  --force                    Overwrite existing skills",
+    "  --all                      Uninstall all managed skills",
+    "  --verbose                  Show detailed script output",
+    "",
+    "Scope behavior:",
+    "  project  Skills are installed inside the repo (Claude only: .claude/skills/)",
+    "  user     Skills are installed in the runtime home (~/.claude/skills/ or ~/.codex/skills/)",
+    "  Note: Codex supports user scope only. Project scope is not available for Codex.",
     "",
     "Auth options:",
     "  --token <value>            Store GitHub PAT",
@@ -60,6 +81,11 @@ function cmdHelp() {
     "  sdtk auth --verify",
     '  sdtk generate --feature-key USER_PROFILE --feature-name "User Profile"',
     "  sdtk generate --feature-key ORDER_MGMT --feature-name \"Order Management\" --validate-only",
+    "  sdtk init --runtime claude --runtime-scope user",
+    "  sdtk runtime install --runtime claude --scope project",
+    "  sdtk runtime install --runtime codex --scope user",
+    "  sdtk runtime status --runtime claude",
+    "  sdtk runtime uninstall --runtime claude --scope project --all",
     "",
     "  # Override entitlement repo (bash/zsh):",
     "  export SDTK_ENTITLEMENT_REPO=owner/repo",

package/src/commands/init.js

@@ -5,12 +5,15 @@ const { parseFlags, validateChoice } = require("../lib/args");
 const { verify, resolvePayloadFile } = require("../lib/toolkit-payload");
 const { runScript } = require("../lib/powershell");
 const { ValidationError } = require("../lib/errors");
+const { VALID_SCOPES, defaultScope, isProjectScopeSupported } = require("../lib/scope");
 
 const FLAG_DEFS = {
   runtime: { type: "string" },
   "project-path": { type: "string" },
+  "runtime-scope": { type: "string" },
   force: { type: "boolean" },
   "skip-skills": { type: "boolean" },
+  "skip-runtime-assets": { type: "boolean" },
   verbose: { type: "boolean" },
 };
 
@@ -23,6 +26,25 @@ async function cmdInit(args) {
   const runtime = flags.runtime || "codex";
   validateChoice(runtime, VALID_RUNTIMES, "runtime");
 
+  // Resolve scope
+  const scope = flags["runtime-scope"] || defaultScope(runtime);
+  validateChoice(scope, VALID_SCOPES, "runtime-scope");
+
+  // Gate C0: Codex does not support project-local skills
+  if (scope === "project" && !isProjectScopeSupported(runtime)) {
+    throw new ValidationError(
+      "Codex does not support project-local skills. Use --runtime-scope user instead."
+    );
+  }
+
+  // Handle deprecated --skip-skills
+  const skipAssets = flags["skip-runtime-assets"] || flags["skip-skills"];
+  if (flags["skip-skills"] && !flags["skip-runtime-assets"]) {
+    console.warn(
+      "Warning: --skip-skills is deprecated. Use --skip-runtime-assets instead."
+    );
+  }
+
   // Resolve project path
   const projectPath = flags["project-path"]
     ? path.resolve(flags["project-path"])
@@ -38,13 +60,15 @@ async function cmdInit(args) {
   const params = {
     ProjectPath: projectPath,
     Runtime: runtime,
+    Scope: scope,
   };
   if (flags.force) params.Force = true;
-  if (flags["skip-skills"]) params.SkipSkills = true;
+  if (skipAssets) params.SkipRuntimeAssets = true;
   if (!flags.verbose) params.Quiet = true;
 
   console.log(`Initializing SDTK workspace...`);
   console.log(`  Runtime: ${runtime}`);
+  console.log(`  Scope:   ${scope}`);
   console.log(`  Project: ${projectPath}`);
   console.log("");
 

package/src/commands/runtime.js

@@ -0,0 +1,217 @@
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+const { parseFlags, requireFlag, validateChoice } = require("../lib/args");
+const { verify, resolvePayloadFile } = require("../lib/toolkit-payload");
+const { runScript } = require("../lib/powershell");
+const { ValidationError } = require("../lib/errors");
+const {
+  VALID_SCOPES,
+  defaultScope,
+  isProjectScopeSupported,
+  resolveSkillsDir,
+  managedSkillNames,
+} = require("../lib/scope");
+
+const FLAG_DEFS = {
+  runtime: { type: "string" },
+  scope: { type: "string" },
+  "project-path": { type: "string" },
+  force: { type: "boolean" },
+  all: { type: "boolean" },
+  verbose: { type: "boolean" },
+};
+
+const VALID_RUNTIMES = ["codex", "claude"];
+const SUBCOMMANDS = ["install", "uninstall", "status"];
+
+function validateScopeForRuntime(runtime, scope) {
+  if (scope === "project" && !isProjectScopeSupported(runtime)) {
+    throw new ValidationError(
+      `Codex does not support project-local skills. Use --scope user instead.`
+    );
+  }
+}
+
+async function cmdRuntimeInstall(flags) {
+  const runtime = requireFlag(flags, "runtime", "runtime");
+  validateChoice(runtime, VALID_RUNTIMES, "runtime");
+
+  const scope = flags.scope || defaultScope(runtime);
+  validateChoice(scope, VALID_SCOPES, "scope");
+  validateScopeForRuntime(runtime, scope);
+
+  const projectPath = flags["project-path"]
+    ? path.resolve(flags["project-path"])
+    : process.cwd();
+
+  verify();
+
+  const scriptName =
+    runtime === "claude"
+      ? "toolkit/scripts/install-claude-skills.ps1"
+      : "toolkit/scripts/install-codex-skills.ps1";
+  const script = resolvePayloadFile(scriptName);
+
+  const params = { Scope: scope };
+  if (runtime === "claude") {
+    params.ProjectPath = projectPath;
+  }
+  if (flags.force) params.Force = true;
+
+  console.log(`Installing ${runtime} runtime assets...`);
+  console.log(`  Runtime: ${runtime}`);
+  console.log(`  Scope:   ${scope}`);
+  if (scope === "project") {
+    console.log(`  Project: ${projectPath}`);
+  }
+  console.log("");
+
+  const result = await runScript(script, params, {
+    silent: !flags.verbose,
+  });
+
+  if (result.exitCode !== 0) {
+    if (result.stderr) console.error(result.stderr);
+    throw new ValidationError(
+      `Runtime install failed (exit code ${result.exitCode}).`
+    );
+  }
+
+  console.log("");
+  console.log(`${runtime} runtime assets installed successfully.`);
+  return 0;
+}
+
+async function cmdRuntimeUninstall(flags) {
+  const runtime = requireFlag(flags, "runtime", "runtime");
+  validateChoice(runtime, VALID_RUNTIMES, "runtime");
+
+  const scope = flags.scope || defaultScope(runtime);
+  validateChoice(scope, VALID_SCOPES, "scope");
+  validateScopeForRuntime(runtime, scope);
+
+  const projectPath = flags["project-path"]
+    ? path.resolve(flags["project-path"])
+    : process.cwd();
+
+  verify();
+
+  const scriptName =
+    runtime === "claude"
+      ? "toolkit/scripts/uninstall-claude-skills.ps1"
+      : "toolkit/scripts/uninstall-codex-skills.ps1";
+  const script = resolvePayloadFile(scriptName);
+
+  const params = {};
+  if (runtime === "claude") {
+    params.Scope = scope;
+    params.ProjectPath = projectPath;
+  }
+  if (flags.all) params.All = true;
+
+  console.log(`Uninstalling ${runtime} runtime assets...`);
+  console.log(`  Runtime: ${runtime}`);
+  console.log(`  Scope:   ${scope}`);
+  console.log("");
+
+  const result = await runScript(script, params, {
+    silent: !flags.verbose,
+  });
+
+  if (result.exitCode !== 0) {
+    if (result.stderr) console.error(result.stderr);
+    throw new ValidationError(
+      `Runtime uninstall failed (exit code ${result.exitCode}).`
+    );
+  }
+
+  console.log("");
+  console.log(`${runtime} runtime assets uninstalled successfully.`);
+  return 0;
+}
+
+function cmdRuntimeStatus(flags) {
+  const runtime = requireFlag(flags, "runtime", "runtime");
+  validateChoice(runtime, VALID_RUNTIMES, "runtime");
+
+  const projectPath = flags["project-path"]
+    ? path.resolve(flags["project-path"])
+    : process.cwd();
+
+  console.log(`Runtime: ${runtime}`);
+  console.log("");
+
+  // Check both scopes
+  const scopes = runtime === "claude" ? ["project", "user"] : ["user"];
+
+  for (const scope of scopes) {
+    const skillsDir = resolveSkillsDir(runtime, scope, projectPath);
+    const exists = fs.existsSync(skillsDir);
+    let skillCount = 0;
+
+    const managed = managedSkillNames(runtime);
+    let installedNames = [];
+
+    if (exists) {
+      try {
+        const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+        installedNames = entries
+          .filter((e) => e.isDirectory() && managed.includes(e.name))
+          .map((e) => e.name);
+        skillCount = installedNames.length;
+      } catch {
+        // Directory not readable
+      }
+    }
+
+    const allInstalled = skillCount === managed.length;
+
+    console.log(`  Scope: ${scope}`);
+    console.log(`    Path:   ${skillsDir}`);
+    const statusLabel = !exists
+      ? "not installed"
+      : allInstalled
+        ? `installed (${skillCount}/${managed.length} SDTK skills)`
+        : `partial (${skillCount}/${managed.length} SDTK skills)`;
+    console.log(`    Status: ${statusLabel}`);
+    if (exists && skillCount < managed.length) {
+      const missing = managed.filter((n) => !installedNames.includes(n));
+      console.log(`    Missing: ${missing.join(", ")}`);
+    }
+    console.log("");
+  }
+
+  return 0;
+}
+
+async function cmdRuntime(args) {
+  const { flags, positional } = parseFlags(args, FLAG_DEFS);
+
+  const subcommand = positional[0];
+  if (!subcommand) {
+    throw new ValidationError(
+      `Missing subcommand. Usage: sdtk runtime <${SUBCOMMANDS.join("|")}> [options]`
+    );
+  }
+
+  if (!SUBCOMMANDS.includes(subcommand)) {
+    throw new ValidationError(
+      `Unknown subcommand: "${subcommand}". Must be one of: ${SUBCOMMANDS.join(", ")}`
+    );
+  }
+
+  switch (subcommand) {
+    case "install":
+      return cmdRuntimeInstall(flags);
+    case "uninstall":
+      return cmdRuntimeUninstall(flags);
+    case "status":
+      return cmdRuntimeStatus(flags);
+  }
+}
+
+module.exports = {
+  cmdRuntime,
+};

package/src/index.js

@@ -4,6 +4,7 @@ const { cmdHelp } = require("./commands/help");
 const { cmdInit } = require("./commands/init");
 const { cmdAuth } = require("./commands/auth");
 const { cmdGenerate } = require("./commands/generate");
+const { cmdRuntime } = require("./commands/runtime");
 const { ValidationError, CliError } = require("./lib/errors");
 
 function getVersion() {
@@ -25,7 +26,7 @@ function parseCommand(argv) {
   return { command: first, args: rest };
 }
 
-const COMMANDS = new Set(["help", "version", "init", "auth", "generate"]);
+const COMMANDS = new Set(["help", "version", "init", "auth", "generate", "runtime"]);
 
 async function run(argv) {
   const { command, args } = parseCommand(argv);
@@ -48,6 +49,8 @@ async function run(argv) {
       return cmdAuth(args);
     case "generate":
       return cmdGenerate(args);
+    case "runtime":
+      return cmdRuntime(args);
   }
 }
 

package/src/lib/scope.js

@@ -0,0 +1,68 @@
+"use strict";
+
+const path = require("path");
+const os = require("os");
+
+const VALID_SCOPES = ["project", "user"];
+
+/**
+ * Returns the default scope for a given runtime.
+ * Claude defaults to project-local, Codex defaults to user/global.
+ */
+function defaultScope(runtime) {
+  return runtime === "claude" ? "project" : "user";
+}
+
+/**
+ * Returns true if the given runtime supports project-local scope.
+ * Gate C0: Codex does not support project-local skills.
+ */
+function isProjectScopeSupported(runtime) {
+  return runtime === "claude";
+}
+
+/**
+ * Resolves the skills directory for a given runtime, scope, and project path.
+ */
+function resolveSkillsDir(runtime, scope, projectPath) {
+  if (runtime === "claude") {
+    if (scope === "user") {
+      return path.join(os.homedir(), ".claude", "skills");
+    }
+    return path.join(projectPath || process.cwd(), ".claude", "skills");
+  }
+
+  // Codex: always user/global scope
+  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+  return path.join(codexHome, "skills");
+}
+
+/**
+ * SDTK-managed skill directory names per runtime.
+ * Used by runtime status to distinguish SDTK skills from unrelated user skills.
+ */
+const MANAGED_CODEX_SKILLS = [
+  "sdtk-api-design-spec", "sdtk-api-doc", "sdtk-arch", "sdtk-ba",
+  "sdtk-design-layout", "sdtk-dev", "sdtk-dev-backend", "sdtk-dev-frontend",
+  "sdtk-orchestrator", "sdtk-pm", "sdtk-qa", "sdtk-screen-design-spec",
+  "sdtk-test-case-spec",
+];
+
+const MANAGED_CLAUDE_SKILLS = [
+  "api-design-spec", "api-doc", "arch", "ba",
+  "design-layout", "dev", "dev-backend", "dev-frontend",
+  "orchestrator", "pm", "qa", "screen-design-spec",
+  "test-case-spec",
+];
+
+function managedSkillNames(runtime) {
+  return runtime === "claude" ? MANAGED_CLAUDE_SKILLS : MANAGED_CODEX_SKILLS;
+}
+
+module.exports = {
+  VALID_SCOPES,
+  defaultScope,
+  isProjectScopeSupported,
+  resolveSkillsDir,
+  managedSkillNames,
+};