skillshop 2.1.0 → 2.2.0

package/README.md

@@ -13,7 +13,7 @@ npm install --global skillshop
 skillshop init
 ```
 
-`init` asks which agents you use and saves their destinations in `~/.skillshop/config.json`. Change the selection later with `skillshop config agents`. Codex and OpenCode use `.agents/skills` inside projects and `~/.agents/skills` for user-level installs. Copilot and Claude use their own skill directories. Shared destinations get one copy.
+`skillshop init` asks which agents you use and saves their destinations in `~/.skillshop/config.json`. It 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`. Run `skillshop init` to choose system-wide defaults; change that selection later with `skillshop config agents`. Codex and OpenCode use `.agents/skills` inside projects and `~/.agents/skills` for user-level installs. Copilot and Claude use their own skill directories. Shared destinations get one copy.
 
 ### Install a named skill
 
@@ -34,7 +34,7 @@ skillshop one-shot --global
 # Equivalent: sk install one-shot --global
 ```
 
-For Codex or OpenCode, this writes `~/.agents/skills/one-shot`. A global install replaces an existing skill directory with that name, including local edits and extra files. Global installs use `~/.skillshop/global-skills.json` for bookkeeping. Each CLI run reconciles recorded installations; it does not install the entire bundled registry.
+For Codex or OpenCode, this writes `~/.agents/skills/one-shot`. A global install replaces an existing skill directory with that name, including local edits and extra files. Global installs use `~/.skillshop/global-skills.json` for bookkeeping. Except for `skillshop upgrade`, ordinary non-agent-instruction CLI runs reconcile recorded installations. Upgrade skips reconciliation in the old process and refreshes changed copies from the newly installed package in a fresh process. Agent instruction commands also bypass reconciliation and do not install the bundled registry.
 
 ### Update or remove skills
 
@@ -48,16 +48,74 @@ skillshop uninstall one-shot --global
 
 `update` replaces skills managed in the current project's lockfile. `update --push` updates registered projects. Neither command updates global copies; reinstall a global skill by name with `--global`. Project uninstall removes only a skill recorded in `.skillshop-lock`. Global uninstall removes the named skill from configured user directories.
 
+### Upgrade Skillshop
+
+```bash
+skillshop upgrade
+```
+
+The command upgrades the npm installation that supplied the invoked CLI. A project-local installation updates Skillshop in the owning npm project and preserves the dependency section where it is already declared. It refreshes only that project's recorded Skillshop-managed skill copies. A global installation updates its npm prefix, then refreshes recorded global copies and copies in registered projects; it does not update those projects' package manifests. Running from a source checkout keeps the historical global-install behavior and does not edit the checkout's package manifest.
+
+After npm succeeds, the newly installed CLI runs in a fresh process and refreshes only existing copies recorded in `.skillshop-lock` or `~/.skillshop/global-skills.json` whose bundled skill version changed. Same-version copies retain their local bodies. A changed-version replacement overwrites local edits in that managed copy; make durable edits in the bundled source. Deleted paths are pruned from ownership records instead of recreated. Unmanaged directories and package-import snapshots are not adopted. An npm install failure stops before copy refresh; a later refresh failure reports that Skillshop was upgraded and gives a nonzero result with the partial-refresh summary.
+
+`skillshop init` is optional. It configures agent destinations and is not required to upgrade Skillshop. The upgrade command never initializes, renders, or rewrites project `AGENTS.md` files or instruction templates.
+
 An exact version such as `skillshop one-shot@2026.8.21` checks the currently bundled version. It does not fetch a historical release. Use `skillshop migrate` to discover older lockfiles and register their repositories.
 
 ### Manage agent instructions
 
 ```bash
 skillshop agents
+skillshop agents init
+skillshop agents --check
 skillshop agents --global
 ```
 
-The local command updates a managed block in the nearest existing `AGENTS.md`. The global command updates the supported user instruction files. Sibling `*.block.md` fragments are composed in filename order. Text outside Skillshop's managed blocks is preserved.
+There are two local modes. Plain `skillshop agents` keeps the bounded legacy behavior for an uninitialized project: it updates the nearest existing `AGENTS.md` within the selected boundary, or creates one at the boundary root if none exists. After project sources are initialized, plain `skillshop agents` renders them instead. The global command remains separate and updates the supported user instruction files.
+
+Initialize project-owned instructions with `skillshop agents init`. The neutral starter template is `.agents/instructions/AGENTS.template.md`; put source blocks beside it as `*.block.md`. Skillshop renders these sources into a distinct managed region in the project-root `AGENTS.md`. Existing user text and prior Skillshop managed guidance are preserved. Edit the template and source blocks, not the generated region. Repeated `skillshop agents init` leaves existing sources alone. If an initialized project's template is removed, `skillshop agents` reports an error rather than restoring bundled personal guidance. Symlinked source, template, block, or output path components are rejected, including dangling links.
+
+The default boundary is the nearest Git repository or worktree root. Outside Git, the current working directory is the boundary. Use `--project <directory>` to choose another boundary; a relative path is resolved from the command's current directory. This is required when a nested project inside a larger repository should own its own output. Put all three explicit-boundary scripts in `packages/app/package.json` so init, rendering, and checking stay in that package:
+
+```json
+{
+  "scripts": {
+    "agents": "skillshop agents --project .",
+    "agents:init": "skillshop agents init --project .",
+    "agents:check": "skillshop agents --check --project ."
+  }
+}
+```
+
+For a local project dependency, add Skillshop as a development dependency and opt into rendering through explicit scripts:
+
+```bash
+npm install --save-dev skillshop
+```
+
+```json
+{
+  "scripts": {
+    "agents": "skillshop agents",
+    "agents:init": "skillshop agents init",
+    "agents:check": "skillshop agents --check"
+  }
+}
+```
+
+Run `npm run agents:init` once, edit the project sources, then run `npm run agents`. `npm run agents:check` exits successfully when the generated region in the working tree matches the current sources; it does not inspect Git's index or commit. CI can run `npm ci` followed by `npm run agents:check`. Commit the npm manifest and lockfile, `.agents/instructions/AGENTS.template.md`, its source blocks, and the rendered root `AGENTS.md`. There is no install hook: initialization and rendering happen only when the scripts are run.
+
+Project and bundled source templates support explicit includes:
+
+```markdown
+{{ include "020_testing.block.md" }}
+
+{{ blocks }}
+```
+
+Use `{{ include "020_testing.block.md" }}` or `{{ include '020_testing.block.md' }}` for named blocks. The older `{{ fragments["020_testing.block.md"] }}` and single-quoted lookup forms remain supported. `{{ blocks }}` inserts the remaining fragments in filename order, excluding every explicitly included file even when its include appears later in the template. Repeated includes render at each position. Fragment contents are inserted literally; placeholder-looking text inside a block is not evaluated recursively. Invalid expressions and missing fragments fail before generated output is written.
+
+These expressions apply to source templates only. Skillshop does not interpret them in destination instruction files or sibling fragments.
 
 ### Use skills from another package
 
@@ -235,7 +293,9 @@ skillshop install <name> [--global]
 skillshop update [name]
 skillshop update --push
 skillshop uninstall <name> [--global]
-skillshop agents [--global]
+skillshop agents init [--project <directory>]
+skillshop agents [--project <directory>] [--check]
+skillshop agents --global
 skillshop migrate [root ...]
 skillshop library init
 skillshop library list

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillshop",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Build, export, resolve, and install portable agent skill libraries",
   "type": "module",
   "bin": {

package/skills-content/skillshop/SKILL.md

@@ -1,9 +1,9 @@
 ---
 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 repository-local agent skills, Skillshop upgrades, and project agent instructions. Use when a repository has a .skillshop-lock or the user asks to install, uninstall, pin, list, update, or upgrade Skillshop-managed copies, or initialize, render, or check project AGENTS.md instructions.
 metadata:
   author: Daniel Fosco
-  version: "2026.10.1"
+  version: "2026.10.23"
 ---
 
 # Skillshop — Local Skill Registry
@@ -12,7 +12,9 @@ Use the `skillshop` CLI to manage skills in this repository. The project-root `.
 
 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.
+Every non-`agents` invocation, including help, version, and failed commands, reconciles the current project's lockfile, registration, and Git exclusions, except `skillshop upgrade`. Agent instruction commands also bypass reconciliation. Upgrade skips the old process's pre/post reconciliation, installs the npm package first, then starts the installed CLI in a fresh process to refresh only changed-version copies recorded in Skillshop's project/global ownership files. 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 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.
+
+`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,7 +23,48 @@ 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
+
+```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 skill
 
@@ -45,7 +88,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`. Except for `skillshop upgrade`, ordinary commands other than `skillshop agents` can repair their frontmatter and prune missing paths. Agent-instruction commands bypass that reconciliation. `skillshop upgrade` instead refreshes recorded global and registered project copies only after npm succeeds and a fresh CLI starts. Same-version copies keep local body edits; a changed-version refresh replaces the managed copy and overwrites local edits. 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.
 
 ## Update managed skills
 
@@ -60,6 +103,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; make durable changes in the bundled skill source. 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/legacy-cli.js

@@ -3,10 +3,17 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
-import { AgentsInstructionsError, applyInstructions, applyLocalFragments, composeAgentsInstructions } from './agents-instructions.js';
+import {
+  AgentsInstructionsError,
+  applyInstructions,
+  applyLocalFragments,
+  applyProjectInstructions,
+  composeAgentsInstructions,
+  hasProjectInstructions
+} from './agents-instructions.js';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const skillsContentRoot = path.join(packageRoot, 'skills-content');
@@ -21,6 +28,11 @@ const excludeBlockStart = '# >>> skillshop managed dependencies >>>';
 const excludeBlockEnd = '# <<< skillshop managed dependencies <<<';
 const legacyExcludeBlockStart = '# >>> skillz managed dependencies >>>';
 const legacyExcludeBlockEnd = '# <<< skillz managed dependencies <<<';
+const projectTemplateDirectory = path.join('.agents', 'instructions');
+const projectTemplateName = 'AGENTS.template.md';
+const defaultProjectTemplate = '# Project instructions\n\n{{ blocks }}\n';
+const internalUpgradeRefreshCommand = '__skillshop_upgrade_refresh';
+const internalUpgradeRefreshToken = 'skillshop-managed-upgrade-v1';
 const globalAgentsTargets = [
   path.join('.codex', 'AGENTS.md'),
   path.join('.agents', 'AGENTS.md'),
@@ -107,7 +119,9 @@ function printHelp() {
   console.log(`Usage:
   skillshop init
   skillshop config agents
-  skillshop agents [--global]
+  skillshop agents init [--project <directory>]
+  skillshop agents [--project <directory>] [--check]
+  skillshop agents --global
   skillshop <name> [--version <version>] [--global]
   skillshop install <name> [--version <version>] [--global]
   skillshop uninstall <name> [--global]
@@ -119,8 +133,21 @@ function printHelp() {
 
 Install, uninstall, and update skills from the local registry.
 
+Agent instructions:
+  skillshop agents init creates a neutral .agents/instructions/AGENTS.template.md and renders it into a separate managed region in the project-root AGENTS.md. Existing text and prior managed guidance are preserved. Edit the template and sibling *.block.md sources, not the generated region.
+  Plain skillshop agents keeps the bounded bundled behavior until project sources exist; afterward it renders project sources. Missing sources in an initialized project are errors.
+  skillshop agents --check reports whether generated output is current and never writes. skillshop agents --global retains user-level instruction updates.
+  The default boundary is the nearest Git/worktree root, or the current directory outside Git. --project selects another directory relative to the current working directory. Nested projects need an explicit selection.
+  Source, block, template, and output paths containing symlink components, including dangling links, are rejected.
+  Templates accept {{ include "name.block.md" }}, {{ include 'name.block.md' }}, legacy {{ fragments["name.block.md"] }}, and {{ blocks }} for unreferenced blocks. Inserted block text is literal.
+
+Upgrade:
+  skillshop upgrade updates the npm installation that supplied the CLI, then refreshes recorded Skillshop-managed copies with the newly installed CLI. skillshop init is optional and upgrade does not generate AGENTS.md files.
+
 Options:
   -g, --global             Use configured system skill directories without a project lockfile
+      --project <directory> Select the agents boundary relative to the current directory
+      --check               Check project-generated instructions without writing
       --push               Update every registered repository
   -v, --version <version>  Require an exact skill version
   -h, --help               Show this help
@@ -775,28 +802,86 @@ function installGlobal(name, requestedVersion) {
   }
 }
 
-function nearestAgentsFile(cwd) {
-  let directory = path.resolve(cwd);
-  while (true) {
+function instructionProjectRoot(cwd, selectedProject) {
+  if (selectedProject) {
+    const selected = path.resolve(cwd, selectedProject);
+    let stats;
+    try {
+      stats = fs.statSync(selected);
+    } catch {
+      throw new CliError(`project directory does not exist: ${selected}`);
+    }
+    if (!stats.isDirectory()) throw new CliError(`project path is not a directory: ${selected}`);
+    return canonicalPath(selected);
+  }
+
+  return canonicalPath(projectRoot(cwd, { required: false }) ?? cwd);
+}
+
+function isWithinDirectory(root, target) {
+  const relative = path.relative(root, target);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+function nearestAgentsFile(cwd, root) {
+  const start = canonicalPath(cwd);
+  let directory = isWithinDirectory(root, start) ? start : root;
+  while (isWithinDirectory(root, directory)) {
     const candidate = path.join(directory, 'AGENTS.md');
     if (fs.existsSync(candidate)) return candidate;
-    const parent = path.dirname(directory);
-    if (parent === directory) return null;
-    directory = parent;
+    if (directory === root) break;
+    directory = path.dirname(directory);
+  }
+  return path.join(root, 'AGENTS.md');
+}
+
+function assertLocalInstructionSources(root, contentDirectory) {
+  assertNoInstructionSymlink(root, contentDirectory, 'local instruction source directory');
+  if (!fs.existsSync(contentDirectory)) return;
+  for (const entry of fs.readdirSync(contentDirectory, { withFileTypes: true })) {
+    if (entry.name.endsWith('.block.md')) {
+      const sourcePath = path.join(contentDirectory, entry.name);
+      const label = `local instruction source ${entry.name}`;
+      assertLocalDestination(root, sourcePath, label);
+      assertNoInstructionSymlink(root, sourcePath, label);
+    }
+  }
+}
+
+function assertNoInstructionSymlink(root, target, label) {
+  const boundary = path.resolve(root);
+  const absoluteTarget = path.resolve(target);
+  const relative = path.relative(boundary, absoluteTarget);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new CliError(`${label} resolves outside the project`);
+  }
+
+  let current = boundary;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) {
+        throw new CliError(`${label} contains a symlink path component`);
+      }
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      if (error.code === 'ENOENT') break;
+      throw error;
+    }
   }
 }
 
-function installAgents(cwd, globalInstall) {
+function installAgents(cwd, globalInstall, selectedProject) {
   const composed = composeAgentsInstructions(agentsContentRoot);
   const targetPaths = [];
+  const root = globalInstall ? null : instructionProjectRoot(cwd, selectedProject);
   if (globalInstall) {
     targetPaths.push(...globalAgentsTargets.map((target) => path.join(os.homedir(), target)));
   } else {
-    const targetPath = nearestAgentsFile(cwd);
-    if (!targetPath) {
-      console.log(`No AGENTS.md found at or above ${cwd}`);
-      return;
-    }
+    const targetPath = nearestAgentsFile(cwd, root);
+    assertLocalDestination(root, targetPath, 'local agents instructions');
+    assertNoInstructionSymlink(root, targetPath, 'local agents instructions');
+    assertLocalInstructionSources(root, path.dirname(targetPath));
     targetPaths.push(targetPath);
   }
 
@@ -824,6 +909,97 @@ function installAgents(cwd, globalInstall) {
   }
 }
 
+function projectInstructionPaths(cwd, selectedProject) {
+  const root = instructionProjectRoot(cwd, selectedProject);
+  const sourceDirectory = path.join(root, projectTemplateDirectory);
+  const templatePath = path.join(sourceDirectory, projectTemplateName);
+  const outputPath = path.join(root, 'AGENTS.md');
+  const paths = [
+    [sourceDirectory, 'project instruction source directory'],
+    [templatePath, 'project instruction template'],
+    [outputPath, 'project agents output']
+  ];
+  for (const [target, label] of paths) {
+    assertLocalDestination(root, target, label);
+    assertNoInstructionSymlink(root, target, label);
+  }
+
+  if (fs.existsSync(sourceDirectory) && !fs.statSync(sourceDirectory).isDirectory()) {
+    throw new CliError(`project instruction source path is not a directory: ${sourceDirectory}`);
+  }
+  if (fs.existsSync(templatePath) && !fs.statSync(templatePath).isFile()) {
+    throw new CliError(`project instruction template is not a file: ${templatePath}`);
+  }
+  if (fs.existsSync(outputPath) && !fs.statSync(outputPath).isFile()) {
+    throw new CliError(`project agents output is not a file: ${outputPath}`);
+  }
+  if (fs.existsSync(sourceDirectory)) {
+    for (const entry of fs.readdirSync(sourceDirectory, { withFileTypes: true })) {
+      if (!entry.name.endsWith('.block.md')) continue;
+      const sourcePath = path.join(sourceDirectory, entry.name);
+      const label = `project instruction source ${entry.name}`;
+      assertLocalDestination(root, sourcePath, label);
+      assertNoInstructionSymlink(root, sourcePath, label);
+    }
+  }
+
+  return { root, sourceDirectory, templatePath, outputPath };
+}
+
+function renderProjectAgents(cwd, selectedProject, { initialize = false, check = false } = {}) {
+  let paths = projectInstructionPaths(cwd, selectedProject);
+  if (initialize) {
+    fs.mkdirSync(paths.sourceDirectory, { recursive: true });
+    if (!fs.existsSync(paths.templatePath)) {
+      fs.writeFileSync(paths.templatePath, defaultProjectTemplate);
+    }
+    paths = projectInstructionPaths(cwd, selectedProject);
+  }
+
+  if (!fs.existsSync(paths.templatePath)) {
+    throw new CliError(`project instruction template is missing; run "skillshop agents init" first: ${paths.templatePath}`);
+  }
+
+  const composed = composeAgentsInstructions(paths.sourceDirectory, projectTemplateName).content;
+  const existing = fs.existsSync(paths.outputPath) ? fs.readFileSync(paths.outputPath, 'utf8') : '';
+  const planned = applyProjectInstructions(existing, composed, packageJson.version);
+
+  if (check) {
+    if (fs.existsSync(paths.outputPath) && planned.text === existing) {
+      console.log(`Project agents instructions are current at ${paths.outputPath}`);
+      return;
+    }
+    console.error(
+      `Project agents instructions are ${fs.existsSync(paths.outputPath) ? 'stale' : 'missing'} at ${paths.outputPath}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  if (planned.text === existing) {
+    console.log(`Project agents instructions already current at ${paths.outputPath}`);
+    return;
+  }
+  fs.writeFileSync(paths.outputPath, planned.text);
+  console.log(`${planned.action === 'refreshed' ? 'Refreshed' : 'Rendered'} project agents instructions at ${paths.outputPath}`);
+}
+
+function projectAgentsConfigured(cwd, selectedProject) {
+  const root = instructionProjectRoot(cwd, selectedProject);
+  const sourceDirectory = path.join(root, projectTemplateDirectory);
+  const outputPath = path.join(root, 'AGENTS.md');
+  for (const candidate of [sourceDirectory, outputPath]) {
+    try {
+      const stat = fs.lstatSync(candidate);
+      if (candidate === sourceDirectory) return true;
+      if (stat.isFile() && hasProjectInstructions(fs.readFileSync(candidate, 'utf8'))) return true;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  return false;
+}
+
 function installLocal(name, requestedVersion, cwd) {
   const root = findLockRoot(cwd) ?? projectRoot(cwd);
   const lock = readLock(root);
@@ -983,6 +1159,208 @@ function updateAllRepositories() {
   console.log(`Updated ${retained.length} registered ${retained.length === 1 ? 'repository' : 'repositories'}`);
 }
 
+function assertNoManagedSymlink(base, target, label) {
+  const boundary = path.resolve(base);
+  const absoluteTarget = path.resolve(target);
+  const relative = path.relative(boundary, absoluteTarget);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new CliError(`${label} resolves outside its managed root`);
+  }
+
+  let current = boundary;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) {
+        throw new CliError(`${label} contains a symlink path component`);
+      }
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      if (error.code === 'ENOENT') break;
+      throw error;
+    }
+  }
+}
+
+function replaceManagedSkillDirectory(sourceDir, targetDir) {
+  const temporaryDir = `${targetDir}.skillshop-upgrade-tmp-${process.pid}`;
+  const backupDir = `${targetDir}.skillshop-upgrade-backup-${process.pid}`;
+  fs.rmSync(temporaryDir, { recursive: true, force: true });
+  fs.rmSync(backupDir, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+  fs.cpSync(sourceDir, temporaryDir, { recursive: true, force: true });
+
+  const hadTarget = fs.existsSync(targetDir);
+  if (hadTarget) fs.renameSync(targetDir, backupDir);
+  try {
+    fs.renameSync(temporaryDir, targetDir);
+    fs.rmSync(backupDir, { recursive: true, force: true });
+  } catch (error) {
+    if (hadTarget && !fs.existsSync(targetDir) && fs.existsSync(backupDir)) {
+      fs.renameSync(backupDir, targetDir);
+    }
+    throw error;
+  } finally {
+    fs.rmSync(temporaryDir, { recursive: true, force: true });
+  }
+}
+
+function upgradeSummary() {
+  return { updated: 0, unchanged: 0, missing: 0, failed: [] };
+}
+
+function validateManagedCopy(root, target, name) {
+  assertNoManagedSymlink(root, target, `managed ${name} copy`);
+  let targetStats;
+  try {
+    targetStats = fs.lstatSync(target);
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+  if (!targetStats.isDirectory()) throw new CliError(`${target} is not a managed skill directory`);
+
+  const manifestPath = path.join(target, 'SKILL.md');
+  assertNoManagedSymlink(root, manifestPath, `managed ${name} manifest`);
+  let manifestStats;
+  try {
+    manifestStats = fs.lstatSync(manifestPath);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new CliError(`${manifestPath} is missing from a recorded skill copy`);
+    throw error;
+  }
+  if (!manifestStats.isFile()) throw new CliError(`${manifestPath} is not a regular skill manifest`);
+  return true;
+}
+
+function refreshManagedLock(root, lock, { global = false, summary }) {
+  let changed = false;
+  for (const name of Object.keys(lock.skills).sort()) {
+    const entry = lock.skills[name];
+    try {
+      const metadata = skillMetadata(name);
+      const targets = global ? globalTargets(name, entry) : lockedTargets(root, name, entry);
+      const base = global ? os.homedir() : root;
+      const existingTargets = [];
+      for (const target of targets) {
+        if (validateManagedCopy(base, target, name)) existingTargets.push(target);
+        else summary.missing += 1;
+      }
+
+      if (!existingTargets.length) {
+        delete lock.skills[name];
+        changed = true;
+        continue;
+      }
+
+      const successfulTargets = [];
+      let skillFailed = false;
+      for (const target of existingTargets) {
+        const recordedVersion = global ? entry.copies?.[target]?.version : entry.version;
+        if (recordedVersion === metadata.version) {
+          summary.unchanged += 1;
+          successfulTargets.push(target);
+          continue;
+        }
+        try {
+          replaceManagedSkillDirectory(metadata.sourceDir, target);
+          summary.updated += 1;
+          successfulTargets.push(target);
+        } catch (error) {
+          summary.failed.push(`${name} at ${target}: ${error.message}`);
+          skillFailed = true;
+        }
+      }
+
+      if (global) {
+        const keptTargets = skillFailed ? targets : successfulTargets;
+        entry.paths = keptTargets;
+        entry.copies ??= {};
+        for (const target of successfulTargets) {
+          const previous = entry.copies[target] ?? {};
+          entry.copies[target] = { ...previous, author: metadata.author, version: metadata.version };
+        }
+        if (!skillFailed) changed = true;
+        if (!entry.paths.length) {
+          delete lock.skills[name];
+          changed = true;
+        }
+      } else if (!skillFailed) {
+        entry.paths = successfulTargets.map((target) => relativePath(root, target)).sort();
+        entry.author = metadata.author;
+        entry.version = metadata.version;
+        changed = true;
+      } else if (existingTargets.length !== targets.length) {
+        entry.paths = existingTargets.map((target) => relativePath(root, target)).sort();
+        changed = true;
+      }
+    } catch (error) {
+      summary.failed.push(`${name}: ${error.message}`);
+    }
+  }
+
+  if (changed) {
+    try {
+      if (global) writeGlobalSkills(lock);
+      else writeLock(root, lock);
+    } catch (error) {
+      summary.failed.push(`could not save ${global ? 'global skill manifest' : path.join(root, lockFileName)}: ${error.message}`);
+    }
+  }
+}
+
+function refreshManagedCopies(scope) {
+  const summary = upgradeSummary();
+  if (scope === 'local') {
+    const owner = localPackageOwner();
+    if (!owner) {
+      summary.failed.push('fresh Skillshop package is no longer attached to a local npm dependency');
+    } else {
+      try {
+        const lock = readLock(owner.root);
+        refreshManagedLock(owner.root, lock, { summary });
+      } catch (error) {
+        summary.failed.push(`${owner.root}: ${error.message}`);
+      }
+    }
+  } else if (scope === 'global') {
+    try {
+      const globalLock = readGlobalSkills();
+      refreshManagedLock(null, globalLock, { global: true, summary });
+    } catch (error) {
+      summary.failed.push(`global managed copies: ${error.message}`);
+    }
+
+    try {
+      const registry = readRegistry();
+      for (const root of registry.repositories) {
+        if (!hasLock(root)) continue;
+        try {
+          const lock = readLock(root);
+          refreshManagedLock(root, lock, { summary });
+        } catch (error) {
+          summary.failed.push(`${root}: ${error.message}`);
+        }
+      }
+    } catch (error) {
+      summary.failed.push(`registered project copies: ${error.message}`);
+    }
+  } else {
+    summary.failed.push(`unsupported managed-copy scope: ${scope}`);
+  }
+
+  console.log(
+    `Managed-copy refresh summary: ${summary.updated} updated, ${summary.unchanged} unchanged, ${summary.missing} missing paths pruned, ${summary.failed.length} failed.`
+  );
+  if (summary.failed.length) {
+    for (const failure of summary.failed) console.error(`skillshop: upgrade refresh: ${failure}`);
+    console.error('skillshop: npm upgrade succeeded, but managed-copy refresh was incomplete');
+    process.exitCode = 1;
+  } else {
+    console.log(`Refreshed Skillshop-managed copies for ${scope} scope.`);
+  }
+}
+
 const migrationSkipDirectories = new Set([
   '.git',
   '.skillshop',
@@ -1074,6 +1452,8 @@ function parseArgs(argv) {
   let pushUpdate = false;
   const agentsTargets = [];
   let requestedVersion = null;
+  let selectedProject = null;
+  let checkProject = false;
 
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
@@ -1081,6 +1461,15 @@ function parseArgs(argv) {
       globalInstall = true;
     } else if (argument === '--push') {
       pushUpdate = true;
+    } else if (argument === '--check') {
+      checkProject = true;
+    } else if (argument === '--project') {
+      selectedProject = argv[index + 1];
+      if (!selectedProject) throw new CliError('--project requires a directory');
+      index += 1;
+    } else if (argument.startsWith('--project=')) {
+      selectedProject = argument.slice('--project='.length);
+      if (!selectedProject) throw new CliError('--project requires a directory');
     } else if (argument === '--codex' || argument === '--copilot') {
       throw new CliError(`${argument} is no longer supported; use agents --global`);
     } else if (argument === '--version' || argument === '-v') {
@@ -1097,7 +1486,15 @@ function parseArgs(argv) {
     }
   }
 
-  return { positional, globalInstall, pushUpdate, requestedVersion, agentsTargets: [...new Set(agentsTargets)] };
+  return {
+    positional,
+    globalInstall,
+    pushUpdate,
+    requestedVersion,
+    selectedProject,
+    checkProject,
+    agentsTargets: [...new Set(agentsTargets)]
+  };
 }
 
 function listSkills() {
@@ -1107,8 +1504,128 @@ function listSkills() {
   }
 }
 
+function packageDependencySection(manifest) {
+  for (const section of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
+    if (Object.hasOwn(manifest?.[section] ?? {}, 'skillshop')) return section;
+  }
+  return null;
+}
+
+function localPackageOwner() {
+  const installedPackageRoot = canonicalPath(packageRoot);
+  let current = path.dirname(installedPackageRoot);
+  while (true) {
+    const manifestPath = path.join(current, 'package.json');
+    if (fs.existsSync(manifestPath)) {
+      try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        const section = packageDependencySection(manifest);
+        const declaredInstall = path.join(current, 'node_modules', 'skillshop');
+        if (section && fs.existsSync(declaredInstall) && canonicalPath(declaredInstall) === installedPackageRoot) {
+          return { root: current, section };
+        }
+      } catch (error) {
+        if (error instanceof SyntaxError) throw new CliError(`cannot parse ${manifestPath}: ${error.message}`);
+        throw error;
+      }
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function npmGlobalRoot() {
+  try {
+    return path.resolve(execFileSync('npm', ['root', '--global'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim());
+  } catch (error) {
+    const detail = error.stderr?.toString().trim();
+    throw new CliError(`cannot determine the active npm global package directory${detail ? `: ${detail}` : ''}`);
+  }
+}
+
+function npmPrefixFromRoot(globalRoot) {
+  const parent = path.dirname(globalRoot);
+  return path.basename(parent) === 'lib' ? path.dirname(parent) : parent;
+}
+
+function resolveUpgradeScope() {
+  const localOwner = localPackageOwner();
+  if (localOwner) return { type: 'local', root: localOwner.root, dependencySection: localOwner.section, packageRoot };
+
+  const insideNodeModules = canonicalPath(packageRoot).split(path.sep).includes('node_modules');
+  const activeGlobalRoot = npmGlobalRoot();
+  if (canonicalPath(path.join(activeGlobalRoot, 'skillshop')) === canonicalPath(packageRoot)) {
+    return { type: 'global', prefix: npmPrefixFromRoot(activeGlobalRoot), packageRoot };
+  }
+  if (insideNodeModules) {
+    throw new CliError(
+      `cannot match this installed Skillshop package to the active npm global prefix (${activeGlobalRoot}); no upgrade was run`
+    );
+  }
+
+  // Preserve the historical source-checkout behavior: install the package into
+  // the active npm global prefix without editing the checkout's package files.
+  return { type: 'global-checkout', packageRoot };
+}
+
+function runUpgradeInstall(scope) {
+  const args = scope.type === 'local'
+    ? ['install', `--save-${scope.dependencySection === 'dependencies' ? 'prod' : scope.dependencySection === 'devDependencies' ? 'dev' : scope.dependencySection === 'optionalDependencies' ? 'optional' : 'peer'}`, 'skillshop@latest']
+    : scope.type === 'global'
+      ? ['install', '--global', '--prefix', scope.prefix, 'skillshop@latest']
+      : ['install', '--global', 'skillshop@latest'];
+  try {
+    execFileSync('npm', args, {
+      cwd: scope.type === 'local' ? scope.root : process.cwd(),
+      stdio: 'inherit'
+    });
+  } catch (error) {
+    const status = Number.isInteger(error.status) ? ` (exit ${error.status})` : '';
+    throw new CliError(`npm upgrade failed${status}; managed copies were not refreshed`);
+  }
+}
+
+function freshUpgradePackageRoot(scope) {
+  if (scope.type !== 'global-checkout') return scope.packageRoot;
+  return path.join(npmGlobalRoot(), 'skillshop');
+}
+
 function upgrade() {
-  execFileSync('npm', ['install', '--global', 'skillshop'], { stdio: 'inherit' });
+  const scope = resolveUpgradeScope();
+  const scopeLabel = scope.type === 'local'
+    ? `project dependency in ${scope.root}`
+    : scope.type === 'global'
+      ? `global installation at ${scope.packageRoot}`
+      : 'global installation (source-checkout compatibility mode)';
+  console.log(`Upgrading Skillshop ${scopeLabel}...`);
+  runUpgradeInstall(scope);
+
+  let freshCliPath;
+  try {
+    freshCliPath = path.join(freshUpgradePackageRoot(scope), 'src', 'cli.js');
+    if (!fs.statSync(freshCliPath).isFile()) throw new Error('not a file');
+  } catch {
+    throw new CliError('npm upgrade succeeded, but the newly installed Skillshop CLI could not be found for managed-copy refresh');
+  }
+
+  const child = spawnSync(process.execPath, [freshCliPath, internalUpgradeRefreshCommand], {
+    cwd: scope.type === 'local' ? scope.root : process.cwd(),
+    env: {
+      ...process.env,
+      SKILLSHOP_INTERNAL_UPGRADE_TOKEN: internalUpgradeRefreshToken,
+      SKILLSHOP_INTERNAL_UPGRADE_SCOPE: scope.type === 'local' ? 'local' : 'global'
+    },
+    stdio: 'inherit'
+  });
+  if (child.error) {
+    throw new CliError(`npm upgrade succeeded, but fresh Skillshop managed-copy refresh could not start: ${child.error.message}`);
+  }
+  if (child.status !== 0) {
+    const status = child.status === null ? 'without an exit status' : `with exit ${child.status}`;
+    throw new CliError(`npm upgrade succeeded, but fresh Skillshop managed-copy refresh failed ${status}`);
+  }
 }
 
 async function main(argv) {
@@ -1121,9 +1638,25 @@ async function main(argv) {
     return;
   }
 
-  const { positional, globalInstall, pushUpdate, requestedVersion, agentsTargets } = parseArgs(argv);
+  const { positional, globalInstall, pushUpdate, requestedVersion, selectedProject, checkProject, agentsTargets } = parseArgs(argv);
   const command = positional[0];
 
+  if ((selectedProject || checkProject) && command !== 'agents') {
+    throw new CliError('--project and --check are only valid with agents');
+  }
+
+  if (command === internalUpgradeRefreshCommand) {
+    if (
+      process.env.SKILLSHOP_INTERNAL_UPGRADE_TOKEN !== internalUpgradeRefreshToken ||
+      positional.length !== 1 ||
+      requestedVersion || globalInstall || pushUpdate || selectedProject || checkProject || agentsTargets.length
+    ) {
+      throw new CliError('invalid internal upgrade continuation');
+    }
+    refreshManagedCopies(process.env.SKILLSHOP_INTERNAL_UPGRADE_SCOPE);
+    return;
+  }
+
   if (command === 'init') {
     if (positional.length !== 1 || requestedVersion || globalInstall || pushUpdate || agentsTargets.length) {
       throw new CliError('init does not accept arguments or options');
@@ -1178,10 +1711,32 @@ async function main(argv) {
   }
 
   if (command === 'agents') {
-    if (positional.length !== 1 || requestedVersion || pushUpdate) {
+    const initializeProject = positional.length === 2 && positional[1] === 'init';
+    if (
+      positional.length > 2 ||
+      (positional.length === 2 && !initializeProject) ||
+      requestedVersion ||
+      pushUpdate ||
+      agentsTargets.length
+    ) {
       throw new CliError('agents does not accept skill or update options');
     }
-    installAgents(process.cwd(), globalInstall);
+    if (globalInstall) {
+      if (initializeProject || selectedProject || checkProject) {
+        throw new CliError('--global cannot be combined with project agents options');
+      }
+      installAgents(process.cwd(), true);
+      return;
+    }
+    if (initializeProject && checkProject) throw new CliError('agents init does not accept --check');
+    if (initializeProject || checkProject || projectAgentsConfigured(process.cwd(), selectedProject)) {
+      renderProjectAgents(process.cwd(), selectedProject, {
+        initialize: initializeProject,
+        check: checkProject
+      });
+    } else {
+      installAgents(process.cwd(), false, selectedProject);
+    }
     return;
   }
 
@@ -1214,13 +1769,46 @@ async function main(argv) {
   else installLocal(name, version, process.cwd());
 }
 
+function isIsolatedAgentsInvocation(argv) {
+  // Preserve the top-level help/version routing before looking for a command.
+  // main() handles help anywhere and the standalone version form without parsing.
+  if (argv[0] === '--help' || argv[0] === '-h') return false;
+  if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-v')) return false;
+
+  // parseArgs accepts project options on either side of the command. Ignore help
+  // flags here because main() handles them before parsing, then classify using
+  // the same positional-command rules as execution.
+  try {
+    const args = argv.filter((argument) => argument !== '--help' && argument !== '-h');
+    return parseArgs(args).positional[0] === 'agents';
+  } catch {
+    return false;
+  }
+}
+
+function isUpgradeFlowInvocation(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) return false;
+  if (
+    argv[0] === internalUpgradeRefreshCommand &&
+    process.env.SKILLSHOP_INTERNAL_UPGRADE_TOKEN === internalUpgradeRefreshToken
+  ) return true;
+  try {
+    return parseArgs(argv).positional[0] === 'upgrade';
+  } catch {
+    return false;
+  }
+}
+
 export async function runLegacyCli(argv) {
+  const isolatedAgentsCommand = isIsolatedAgentsInvocation(argv);
+  const upgradeFlow = isUpgradeFlowInvocation(argv);
+  const skipLegacyReconciliation = isolatedAgentsCommand || upgradeFlow;
   try {
-    reconcileCurrentRepository();
+    if (!skipLegacyReconciliation) reconcileCurrentRepository();
     try {
       await main(argv);
     } finally {
-      reconcileCurrentRepository();
+      if (!skipLegacyReconciliation) reconcileCurrentRepository();
     }
   } catch (error) {
     if (!(error instanceof CliError) && !(error instanceof AgentsInstructionsError)) throw error;