@alavida/agentpack 0.1.3 → 0.1.4

package/README.md

@@ -253,6 +253,28 @@ Validate the shipped agent skill:
 npm run intent:validate
 ```
 
+## Releases
+
+This repo now uses Changesets for versioning and publishing.
+
+Normal maintainer flow:
+
+1. Add a changeset in any PR that changes user-facing behavior.
+2. Merge the feature PR to `main`.
+3. Let GitHub open or update the `Version Packages` release PR.
+4. Review and merge that release PR.
+5. The merge publishes to npm automatically.
+
+Useful local commands:
+
+```bash
+npx changeset
+npm run version-packages
+npm run release
+```
+
+Manual git tags are no longer the normal release path.
+
 ## Optional Agent Integration
 
 This package also ships an agent-facing skill under:
@@ -273,10 +295,12 @@ In authoring repos:
 
 - commit `.agentpack/build-state.json`
 - commit `.agentpack/catalog.json`
+- commit `skills/sync-state.json` when maintaining shipped Intent skills
 
 In consumer/runtime repos:
 
 - do not commit `.agentpack/install.json`
+- do not commit `.agentpack/dev-session.json`
 
 ## License
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@alavida/agentpack",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Package-backed skills lifecycle CLI for agent skills and plugins",
   "type": "module",
   "bin": {
     "agentpack": "bin/agentpack.js",
-    "intent": "./bin/intent.js"
+    "intent": "bin/intent.js"
   },
   "files": [
     "bin",
@@ -19,6 +19,9 @@
     "validate:live": "node scripts/live-validation.mjs",
     "smoke:monorepo": "node scripts/smoke-monorepo.mjs",
     "docs:dev": "cd docs && mint dev",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "changeset publish",
     "intent:validate": "npx @tanstack/intent validate",
     "build:dashboard": "node scripts/build-dashboard.mjs"
   },
@@ -51,6 +54,7 @@
     "react-dom": "^19.1.1"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.30.0",
     "@tanstack/intent": "^0.0.14",
     "esbuild": "^0.25.10"
   },

package/skills/agentpack-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agentpack-cli
 description: Use the agentpack CLI correctly when treating knowledge as a package. Apply the authored skill lifecycle, plugin lifecycle, source-backed validation, install flow, and bundled plugin artifact flow without mixing those stages together.
-library_version: 0.1.2
+library_version: 0.1.3
 sources:
   - README.md
   - docs/introduction.mdx
@@ -71,11 +71,16 @@ Persistence rule:
 - commit `.agentpack/build-state.json` so stale detection works across GitHub, CI, and teammate machines
 - commit `.agentpack/catalog.json` in authoring repos
 - do not commit `.agentpack/install.json`
+- do not commit `.agentpack/dev-session.json`
+- commit `skills/sync-state.json` when maintaining the shipped Intent skills for this package
 
 Runtime notes:
 
 - after `skills dev` writes to `.claude/skills/` or `.agents/skills/`, start a fresh agent session if the current one was already running
 - `skills dev` starts a localhost workbench by default for one selected skill, with provenance edges, direct required skills, and actions like validate or stale checks
+- `skills dev` records the active session in `.agentpack/dev-session.json` so the next run can clean up stale runtime links after abnormal termination
+- if a stale local dev session blocks startup, use `agentpack skills dev cleanup` and escalate to `agentpack skills dev cleanup --force` only when the recorded pid is a false positive
+- use `agentpack skills unlink <root> --recursive` when you need to remove one active dev root plus its transitive local runtime links
 - do not reload `metadata.sources` manually once the dev-linked skill exists; trust the compiled `SKILL.md` artifact unless you are explicitly updating the skill
 - invoke the resulting skill through the runtime's skill mechanism, not by opening the file and reading it as plain text
 

package/skills/authoring-skillgraphs-from-knowledge/SKILL.md

@@ -3,7 +3,7 @@ name: authoring-skillgraphs-from-knowledge
 description: Use when authoring packaged skills from source knowledge with valid SKILL.md metadata, package.json release fields, provenance sources, and requires edges in agentpack.
 type: core
 library: agentpack
-library_version: "0.1.2"
+library_version: "0.1.3"
 sources:
   - "alavida-ai/agentpack:docs/commands.mdx"
   - "alavida-ai/agentpack:docs/architecture.mdx"

package/skills/developing-and-testing-skills/SKILL.md

@@ -3,7 +3,7 @@ name: developing-and-testing-skills
 description: Use when iterating locally on a packaged skill with agentpack skills dev, the localhost workbench, repo-local materialization, and runtime testing feedback loops.
 type: core
 library: agentpack
-library_version: "0.1.2"
+library_version: "0.1.3"
 sources:
   - "alavida-ai/agentpack:docs/commands.mdx"
   - "alavida-ai/agentpack:docs/introduction.mdx"
@@ -30,7 +30,7 @@ agentpack skills dev domains/value/skills/copywriting
 agentpack skills dev domains/value/skills/copywriting
 ```
 
-This links the selected skill into `.claude/skills/` and `.agents/skills/` and starts a localhost workbench by default.
+This links the selected skill into `.claude/skills/` and `.agents/skills/`, records the active dev session in `.agentpack/dev-session.json`, and starts a localhost workbench by default.
 
 ### Use CLI-only mode when you explicitly do not want the dashboard
 
@@ -44,6 +44,24 @@ agentpack skills dev --no-dashboard domains/value/skills/copywriting
 agentpack skills unlink value-copywriting
 ```
 
+If the previous dev process was killed badly and left stale runtime links behind:
+
+```bash
+agentpack skills dev cleanup
+```
+
+If a wrapper-managed process left a false-positive live pid in `.agentpack/dev-session.json`:
+
+```bash
+agentpack skills dev cleanup --force
+```
+
+If you need to remove the active root plus its recorded transitive links in one shot:
+
+```bash
+agentpack skills unlink value-copywriting --recursive
+```
+
 ## Common Mistakes
 
 ### HIGH Expecting the current agent session to pick up new links

package/skills/getting-started-skillgraphs/SKILL.md

@@ -3,7 +3,7 @@ name: getting-started-skillgraphs
 description: Use when starting from an empty repo or empty skillgraph and needing the first correct authoring loop, lifecycle framing, repo-root routing, and inspect/validate/dev command flow in agentpack.
 type: lifecycle
 library: agentpack
-library_version: "0.1.2"
+library_version: "0.1.3"
 sources:
   - "alavida-ai/agentpack:docs/introduction.mdx"
   - "alavida-ai/agentpack:docs/commands.mdx"

package/skills/identifying-skill-opportunities/SKILL.md

@@ -3,7 +3,7 @@ name: identifying-skill-opportunities
 description: Use when deciding what raw knowledge should become a packaged skill, a reusable capability boundary, a requires edge, or a plugin-local wrapper in an agentpack skillgraph.
 type: core
 library: agentpack
-library_version: "0.1.2"
+library_version: "0.1.3"
 sources:
   - "alavida-ai/agentpack:docs/architecture.mdx"
   - "alavida-ai/agentpack:docs/overview.mdx"

package/skills/maintaining-skillgraph-freshness/SKILL.md

@@ -3,7 +3,7 @@ name: maintaining-skillgraph-freshness
 description: Use when validating authored skills, checking stale state, and keeping build-state and catalog metadata aligned with changing knowledge in an agentpack skillgraph.
 type: lifecycle
 library: agentpack
-library_version: "0.1.2"
+library_version: "0.1.3"
 sources:
   - "alavida-ai/agentpack:docs/commands.mdx"
   - "alavida-ai/agentpack:docs/current-state.mdx"

package/skills/repairing-broken-skill-or-plugin-state/SKILL.md

@@ -3,7 +3,7 @@ name: repairing-broken-skill-or-plugin-state
 description: Use when auditing or repairing stale skills, unresolved requires, missing runtime dependencies, affected dependents, or malformed plugin definition files in agentpack.
 type: lifecycle
 library: agentpack
-library_version: "0.1.2"
+library_version: "0.1.3"
 sources:
   - "alavida-ai/agentpack:docs/current-state.mdx"
   - "alavida-ai/agentpack:docs/commands.mdx"
@@ -100,11 +100,15 @@ Correct:
 
 ```bash
 agentpack skills unlink value-copywriting
+agentpack skills unlink value-copywriting --recursive
+agentpack skills dev cleanup
 agentpack skills install @alavida-ai/value-copywriting
 ```
 
 Runtime state should be repaired through agentpack lifecycle commands, not direct edits under `.claude/skills` or `.agents/skills`.
 
+Use `skills dev cleanup --force` only when a wrapper-managed process or pid reuse leaves a false-positive active session in `.agentpack/dev-session.json`.
+
 Source: docs/architecture.mdx
 
 ## References

package/skills/shipping-production-plugins-and-packages/SKILL.md

@@ -3,7 +3,7 @@ name: shipping-production-plugins-and-packages
 description: Use when turning maintained skills into deployable bundled plugins or publishable standalone packages with explicit dependency closure, hooks, MCP tools, and production checks in agentpack.
 type: core
 library: agentpack
-library_version: "0.1.2"
+library_version: "0.1.3"
 sources:
   - "alavida-ai/agentpack:docs/commands.mdx"
   - "alavida-ai/agentpack:docs/architecture.mdx"

package/skills/sync-state.json

@@ -0,0 +1,83 @@
+{
+  "version": 1,
+  "skills": {
+    "agentpack-cli": {
+      "library_version": "0.1.3",
+      "synced_at": "2026-03-12T00:00:00.000Z",
+      "sources_sha": {
+        "README.md": "2680d4fa603b070e6bd92c162b3d172131b71c39c9dc39351ed452d95567b0bd",
+        "docs/introduction.mdx": "c1a8989382dc81a3a33dae1e8f243d159b92835a1999a8793741a25b317b455d",
+        "docs/overview.mdx": "48151b11dfef153223ba2aed7100eeeafc100c475694c98e053f9c4ffb025357",
+        "docs/architecture.mdx": "400617fb8ba4a5f09a78b998e3b1a01262caed05e0344206ca1f8fd71519ea22",
+        "docs/build-lifecycle.mdx": "0e697180c639a72514272e6421f900ac3d5248ecc09220409efc716bf0d4fa71",
+        "docs/commands.mdx": "5f2ec2839caa8a6758f36daaa150f6af8d3700e26b135333fad6a0719dacb05b",
+        "docs/current-state.mdx": "b4ad89e40706aff29bbe3149daeeb3feac6d07bb3ddfd4f164e630cd5b7997a8",
+        "docs/distribution.mdx": "060e47b28c3da13ff61e6b1b04e018beb8dc5d6ebd30b5a3d1574fceb289e3f4",
+        "docs/end-to-end-test-plan.md": "c1e37589660a438cb1a9742f68e769ed68f6f8849f1510d8445e99c2bff1ec21"
+      }
+    },
+    "authoring-skillgraphs-from-knowledge": {
+      "library_version": "0.1.3",
+      "synced_at": "2026-03-12T00:00:00.000Z",
+      "sources_sha": {
+        "alavida-ai/agentpack:docs/commands.mdx": "5f2ec2839caa8a6758f36daaa150f6af8d3700e26b135333fad6a0719dacb05b",
+        "alavida-ai/agentpack:docs/architecture.mdx": "400617fb8ba4a5f09a78b998e3b1a01262caed05e0344206ca1f8fd71519ea22",
+        "alavida-ai/agentpack:skills/agentpack-cli/SKILL.md": "54d9a43172ff6b7e7218bb9a9454b56d38233e9d1a6df9362e7167ceb9dc2249"
+      }
+    },
+    "developing-and-testing-skills": {
+      "library_version": "0.1.3",
+      "synced_at": "2026-03-12T00:00:00.000Z",
+      "sources_sha": {
+        "alavida-ai/agentpack:docs/commands.mdx": "5f2ec2839caa8a6758f36daaa150f6af8d3700e26b135333fad6a0719dacb05b",
+        "alavida-ai/agentpack:docs/introduction.mdx": "c1a8989382dc81a3a33dae1e8f243d159b92835a1999a8793741a25b317b455d",
+        "alavida-ai/agentpack:README.md": "2680d4fa603b070e6bd92c162b3d172131b71c39c9dc39351ed452d95567b0bd"
+      }
+    },
+    "getting-started-skillgraphs": {
+      "library_version": "0.1.3",
+      "synced_at": "2026-03-12T00:00:00.000Z",
+      "sources_sha": {
+        "alavida-ai/agentpack:docs/introduction.mdx": "c1a8989382dc81a3a33dae1e8f243d159b92835a1999a8793741a25b317b455d",
+        "alavida-ai/agentpack:docs/commands.mdx": "5f2ec2839caa8a6758f36daaa150f6af8d3700e26b135333fad6a0719dacb05b",
+        "alavida-ai/agentpack:README.md": "2680d4fa603b070e6bd92c162b3d172131b71c39c9dc39351ed452d95567b0bd"
+      }
+    },
+    "identifying-skill-opportunities": {
+      "library_version": "0.1.3",
+      "synced_at": "2026-03-12T00:00:00.000Z",
+      "sources_sha": {
+        "alavida-ai/agentpack:docs/architecture.mdx": "400617fb8ba4a5f09a78b998e3b1a01262caed05e0344206ca1f8fd71519ea22",
+        "alavida-ai/agentpack:docs/overview.mdx": "48151b11dfef153223ba2aed7100eeeafc100c475694c98e053f9c4ffb025357",
+        "alavida-ai/agentpack:skills/agentpack-cli/SKILL.md": "54d9a43172ff6b7e7218bb9a9454b56d38233e9d1a6df9362e7167ceb9dc2249"
+      }
+    },
+    "maintaining-skillgraph-freshness": {
+      "library_version": "0.1.3",
+      "synced_at": "2026-03-12T00:00:00.000Z",
+      "sources_sha": {
+        "alavida-ai/agentpack:docs/commands.mdx": "5f2ec2839caa8a6758f36daaa150f6af8d3700e26b135333fad6a0719dacb05b",
+        "alavida-ai/agentpack:docs/current-state.mdx": "b4ad89e40706aff29bbe3149daeeb3feac6d07bb3ddfd4f164e630cd5b7997a8",
+        "alavida-ai/agentpack:README.md": "2680d4fa603b070e6bd92c162b3d172131b71c39c9dc39351ed452d95567b0bd"
+      }
+    },
+    "repairing-broken-skill-or-plugin-state": {
+      "library_version": "0.1.3",
+      "synced_at": "2026-03-12T00:00:00.000Z",
+      "sources_sha": {
+        "alavida-ai/agentpack:docs/current-state.mdx": "b4ad89e40706aff29bbe3149daeeb3feac6d07bb3ddfd4f164e630cd5b7997a8",
+        "alavida-ai/agentpack:docs/commands.mdx": "5f2ec2839caa8a6758f36daaa150f6af8d3700e26b135333fad6a0719dacb05b",
+        "alavida-ai/agentpack:src/domain/plugins/load-plugin-definition.js": "3aac67288351229e878d0877097b41cd369cc594fc8683fccf2506b94a5f17e7"
+      }
+    },
+    "shipping-production-plugins-and-packages": {
+      "library_version": "0.1.3",
+      "synced_at": "2026-03-12T00:00:00.000Z",
+      "sources_sha": {
+        "alavida-ai/agentpack:docs/commands.mdx": "5f2ec2839caa8a6758f36daaa150f6af8d3700e26b135333fad6a0719dacb05b",
+        "alavida-ai/agentpack:docs/architecture.mdx": "400617fb8ba4a5f09a78b998e3b1a01262caed05e0344206ca1f8fd71519ea22",
+        "alavida-ai/agentpack:README.md": "2680d4fa603b070e6bd92c162b3d172131b71c39c9dc39351ed452d95567b0bd"
+      }
+    }
+  }
+}

package/src/commands/skills.js

@@ -11,6 +11,7 @@ import {
   installSkills,
   listOutdatedSkills,
   resolveInstallTargets,
+  cleanupSkillDevSession,
   startSkillDev,
   unlinkSkill,
   uninstallSkills,
@@ -22,13 +23,16 @@ export function skillsCommand() {
   const cmd = new Command('skills')
     .description('Inspect and manage package-backed skills');
 
-  cmd
+  const devCmd = cmd
     .command('dev')
     .description('Link one local packaged skill for local Claude and agent discovery')
     .option('--no-sync', 'Skip syncing managed package dependencies from requires')
     .option('--no-dashboard', 'Skip starting the local skill development workbench')
-    .argument('<target>', 'Packaged skill directory or SKILL.md path')
+    .argument('[target]', 'Packaged skill directory or SKILL.md path')
     .action(async (target, opts, command) => {
+      if (!target) {
+        command.help({ error: true });
+      }
       const globalOpts = command.optsWithGlobals();
       const session = startSkillDev(target, {
         sync: opts.sync,
@@ -70,23 +74,37 @@ export function skillsCommand() {
         },
       });
 
-      const stop = () => {
-        session.close();
-        process.exit(0);
-      };
-
-      process.once('SIGTERM', stop);
-      process.once('SIGINT', stop);
       await session.ready;
     });
 
+  devCmd
+    .command('cleanup')
+    .description('Remove recorded skills dev links for a stale session')
+    .option('--force', 'Remove recorded links even if the session pid still appears alive')
+    .action((opts, command) => {
+      const globalOpts = command.optsWithGlobals();
+      const result = cleanupSkillDevSession({ force: opts.force });
+
+      if (globalOpts.json) {
+        output.json(result);
+        return;
+      }
+
+      output.write(`Cleaned: ${result.cleaned}`);
+      if (result.name) output.write(`Root Skill: ${result.name}`);
+      for (const removed of result.removed) {
+        output.write(`Removed: ${removed}`);
+      }
+    });
+
   cmd
     .command('unlink')
     .description('Remove one locally linked skill from Claude and agent discovery paths')
+    .option('--recursive', 'Remove the active dev root and its recorded transitive links')
     .argument('<name>', 'Skill frontmatter name')
     .action((name, opts, command) => {
       const globalOpts = command.optsWithGlobals();
-      const result = unlinkSkill(name);
+      const result = unlinkSkill(name, { recursive: opts.recursive });
 
       if (globalOpts.json) {
         output.json(result);

package/src/infrastructure/fs/dev-session-repository.js

@@ -0,0 +1,25 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function getDevSessionPath(repoRoot) {
+  return join(repoRoot, '.agentpack', 'dev-session.json');
+}
+
+export function readDevSession(repoRoot) {
+  const sessionPath = getDevSessionPath(repoRoot);
+  if (!existsSync(sessionPath)) return null;
+  return JSON.parse(readFileSync(sessionPath, 'utf-8'));
+}
+
+export function writeDevSession(repoRoot, session) {
+  mkdirSync(join(repoRoot, '.agentpack'), { recursive: true });
+  writeFileSync(getDevSessionPath(repoRoot), JSON.stringify(session, null, 2) + '\n');
+}
+
+export function removeDevSession(repoRoot) {
+  rmSync(getDevSessionPath(repoRoot), { force: true });
+}
+
+export function devSessionExists(repoRoot) {
+  return existsSync(getDevSessionPath(repoRoot));
+}

package/src/infrastructure/runtime/materialize-skills.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, rmSync, symlinkSync } from 'node:fs';
-import { dirname, join, relative } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { writeInstallState } from '../fs/install-state-repository.js';
 
 function ensureDir(pathValue) {
@@ -40,6 +40,23 @@ export function removeSkillLinksByNames(repoRoot, names, normalizeDisplayPath) {
   return [...new Set(removed)];
 }
 
+export function removeSkillLinksByPaths(repoRoot, paths, normalizeDisplayPath) {
+  const removed = [];
+  const allowedRoots = [
+    resolve(repoRoot, '.claude', 'skills'),
+    resolve(repoRoot, '.agents', 'skills'),
+  ];
+  for (const relativePath of paths || []) {
+    const pathValue = resolve(repoRoot, relativePath);
+    const inAllowedRoot = allowedRoots.some((root) => pathValue === root || pathValue.startsWith(`${root}/`));
+    if (!inAllowedRoot) continue;
+    if (!existsSync(pathValue)) continue;
+    removePathIfExists(pathValue);
+    removed.push(normalizeDisplayPath(repoRoot, pathValue));
+  }
+  return [...new Set(removed)];
+}
+
 function ensureSymlink(targetPath, linkPath) {
   removePathIfExists(linkPath);
   mkdirSync(dirname(linkPath), { recursive: true });

package/src/lib/skills.js

@@ -9,11 +9,13 @@ import {
   readNodeStatus,
 } from '../domain/skills/skill-graph.js';
 import { readInstallState } from '../infrastructure/fs/install-state-repository.js';
+import { readDevSession, writeDevSession, removeDevSession } from '../infrastructure/fs/dev-session-repository.js';
 import {
   ensureSkillLink,
   rebuildInstallState,
   removePathIfExists,
   removeSkillLinks,
+  removeSkillLinksByPaths,
   removeSkillLinksByNames,
 } from '../infrastructure/runtime/materialize-skills.js';
 import {
@@ -171,6 +173,100 @@ function readPackageJson(packageDir) {
   };
 }
 
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error.code === 'EPERM') return true;
+    if (error.code === 'ESRCH') return false;
+    return false;
+  }
+}
+
+function buildDevSessionNextSteps(command) {
+  return [{
+    action: 'run_command',
+    command,
+    reason: 'Use the dev session cleanup flow to remove recorded linked skills for this repo',
+  }];
+}
+
+function toDevSessionRecord(repoRoot, target, result, existing = null) {
+  const now = new Date().toISOString();
+  const rootSkill = result.linkedSkills.find((entry) => entry.name === result.name) || result.linkedSkills[0] || null;
+  return {
+    version: 1,
+    session_id: existing?.session_id || `dev-${now.replaceAll(':', '-').replaceAll('.', '-')}`,
+    status: 'active',
+    pid: process.pid,
+    repo_root: repoRoot,
+    target,
+    root_skill: rootSkill
+      ? {
+        name: rootSkill.name,
+        package_name: rootSkill.packageName,
+        path: rootSkill.path,
+      }
+      : null,
+    linked_skills: result.linkedSkills.map((entry) => ({
+      name: entry.name,
+      package_name: entry.packageName,
+      path: entry.path,
+    })),
+    links: result.links,
+    started_at: existing?.started_at || now,
+    updated_at: now,
+  };
+}
+
+function cleanupRecordedDevSession(repoRoot, session, status = 'stale') {
+  if (!session) {
+    return {
+      cleaned: false,
+      removed: [],
+      session: null,
+    };
+  }
+
+  writeDevSession(repoRoot, {
+    ...session,
+    status,
+    updated_at: new Date().toISOString(),
+  });
+  const removed = removeSkillLinksByPaths(repoRoot, session.links || [], normalizeDisplayPath);
+  removeDevSession(repoRoot);
+  return {
+    cleaned: removed.length > 0 || Boolean(session),
+    removed,
+    session,
+  };
+}
+
+function reconcileDevSession(repoRoot) {
+  const session = readDevSession(repoRoot);
+  if (!session) return null;
+
+  if (session.status === 'active' && isProcessAlive(session.pid)) {
+    throw new AgentpackError('A skills dev session is already active in this repo', {
+      code: 'skills_dev_session_active',
+      exitCode: EXIT_CODES.GENERAL,
+      nextSteps: [
+        ...buildDevSessionNextSteps('agentpack skills dev cleanup'),
+        ...buildDevSessionNextSteps('agentpack skills dev cleanup --force'),
+      ],
+      details: {
+        rootSkill: session.root_skill?.name || null,
+        pid: session.pid,
+        startedAt: session.started_at || null,
+      },
+    });
+  }
+
+  return cleanupRecordedDevSession(repoRoot, session, 'stale');
+}
+
 export function syncSkillDependencies(skillDir) {
   const skillFile = join(skillDir, 'SKILL.md');
   const metadata = parseSkillFrontmatterFile(skillFile);
@@ -271,12 +367,14 @@ export function startSkillDev(target, {
   const outerRepoRoot = findRepoRoot(cwd);
   const { skillDir } = resolveLocalPackagedSkillDir(outerRepoRoot, target);
   const repoRoot = findRepoRoot(skillDir);
+  reconcileDevSession(repoRoot);
   let closed = false;
   let timer = null;
   let currentNames = [];
   let watcher = null;
   let workbench = null;
   let initialResult = null;
+  let sessionRecord = null;
 
   const cleanup = () => {
     if (closed) return { name: currentNames[0] || null, unlinked: false, removed: [] };
@@ -284,10 +382,20 @@ export function startSkillDev(target, {
     clearTimeout(timer);
     if (watcher) watcher.close();
     if (workbench) workbench.close();
-    const removed = removeSkillLinksByNames(repoRoot, currentNames, normalizeDisplayPath);
+    if (sessionRecord) {
+      writeDevSession(repoRoot, {
+        ...sessionRecord,
+        status: 'cleaning',
+        updated_at: new Date().toISOString(),
+      });
+    }
+    const removed = sessionRecord
+      ? removeSkillLinksByPaths(repoRoot, sessionRecord.links || [], normalizeDisplayPath)
+      : removeSkillLinksByNames(repoRoot, currentNames, normalizeDisplayPath);
+    removeDevSession(repoRoot);
     detachProcessCleanup();
     return {
-      name: currentNames[0] || null,
+      name: sessionRecord?.root_skill?.name || currentNames[0] || null,
       unlinked: removed.length > 0,
       removed,
     };
@@ -295,9 +403,14 @@ export function startSkillDev(target, {
 
   const processCleanupHandlers = new Map();
   const attachProcessCleanup = () => {
-    for (const eventName of ['exit', 'beforeExit', 'SIGINT', 'SIGTERM', 'SIGHUP']) {
+    const exitHandler = () => cleanup();
+    processCleanupHandlers.set('exit', exitHandler);
+    process.once('exit', exitHandler);
+
+    for (const eventName of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
       const handler = () => {
         cleanup();
+        process.exit(0);
       };
       processCleanupHandlers.set(eventName, handler);
       process.once(eventName, handler);
@@ -333,6 +446,8 @@ export function startSkillDev(target, {
       removeSkillLinksByNames(repoRoot, staleNames, normalizeDisplayPath);
     }
     currentNames = nextNames;
+    sessionRecord = toDevSessionRecord(repoRoot, target, result, sessionRecord);
+    writeDevSession(repoRoot, sessionRecord);
     return result;
   };
 
@@ -390,8 +505,37 @@ export function startSkillDev(target, {
   };
 }
 
-export function unlinkSkill(name, { cwd = process.cwd() } = {}) {
+export function unlinkSkill(name, { cwd = process.cwd(), recursive = false } = {}) {
   const repoRoot = findRepoRoot(cwd);
+  const session = readDevSession(repoRoot);
+
+  if (recursive) {
+    if (!session || session.root_skill?.name !== name) {
+      throw new AgentpackError('Recursive unlink requires the active dev-session root skill', {
+        code: 'linked_skill_recursive_unlink_requires_root',
+        exitCode: EXIT_CODES.GENERAL,
+        nextSteps: session?.root_skill?.name
+          ? [{
+            action: 'run_command',
+            command: `agentpack skills unlink ${session.root_skill.name} --recursive`,
+            reason: 'Recursive unlink in v1 only works for the recorded dev-session root skill',
+          }]
+          : buildDevSessionNextSteps('agentpack skills dev cleanup --force'),
+        details: {
+          rootSkill: session?.root_skill?.name || null,
+        },
+      });
+    }
+
+    const removed = removeSkillLinksByPaths(repoRoot, session.links || [], normalizeDisplayPath);
+    removeDevSession(repoRoot);
+    return {
+      name,
+      unlinked: removed.length > 0,
+      removed,
+    };
+  }
+
   const existing = [
     join(repoRoot, '.claude', 'skills', name),
     join(repoRoot, '.agents', 'skills', name),
@@ -413,6 +557,43 @@ export function unlinkSkill(name, { cwd = process.cwd() } = {}) {
   };
 }
 
+export function cleanupSkillDevSession({ cwd = process.cwd(), force = false } = {}) {
+  const repoRoot = findRepoRoot(cwd);
+  const session = readDevSession(repoRoot);
+  if (!session) {
+    return {
+      cleaned: false,
+      active: false,
+      removed: [],
+    };
+  }
+
+  if (!force && session.status === 'active' && isProcessAlive(session.pid)) {
+    throw new AgentpackError('A skills dev session is still active in this repo', {
+      code: 'skills_dev_session_active',
+      exitCode: EXIT_CODES.GENERAL,
+      nextSteps: [
+        ...buildDevSessionNextSteps('agentpack skills dev cleanup'),
+        ...buildDevSessionNextSteps('agentpack skills dev cleanup --force'),
+      ],
+      details: {
+        rootSkill: session.root_skill?.name || null,
+        pid: session.pid,
+        startedAt: session.started_at || null,
+      },
+    });
+  }
+
+  const result = cleanupRecordedDevSession(repoRoot, session, 'stale');
+  return {
+    cleaned: true,
+    active: false,
+    forced: force,
+    name: session.root_skill?.name || null,
+    removed: result.removed,
+  };
+}
+
 function buildValidateNextSteps(packageMetadata, valid) {
   if (!valid || !packageMetadata.packageName) return [];