@alavida/agentpack 0.1.3 → 0.1.5

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.5",
   "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.4
 sources:
   - README.md
   - docs/introduction.mdx
@@ -20,7 +20,8 @@ Use this skill when the user is working with `@alavida/agentpack` and needs the
 
 Agentpack is a lifecycle toolchain for agent artifacts:
 
-- a packaged skill is a reusable capability artifact
+- a package is the distribution unit
+- an exported skill is the runtime module unit
 - a plugin package is a deployable runtime shell
 - source docs are the truth
 - `SKILL.md` is the compiled agent-facing artifact
@@ -49,19 +50,20 @@ If a skill points at `domains/.../knowledge/*.md`, run `skills validate`, `skill
 
 ### 1. Authored packaged skill
 
-Use when the user is creating or editing one reusable skill package.
+Use when the user is creating or editing one packaged skill module or a package that exports several skill modules.
 
 Default flow:
 
-- `agentpack skills inspect <skill-dir>`
-- `agentpack skills validate <skill-dir>`
-- `agentpack skills dev <skill-dir>` if local runtime testing is needed
-- `agentpack skills dev --no-dashboard <skill-dir>` if the user wants to skip the local workbench
+- `agentpack skills inspect <target>`
+- `agentpack skills validate <target>`
+- `agentpack skills dev <target>` if local runtime testing is needed
+- `agentpack skills dev --no-dashboard <target>` if the user wants to skip the local workbench
 
 Key idea:
 
-- `SKILL.md.requires` is the source of truth
-- `package.json.dependencies` is the compiled mirror
+- `package.json.agentpack.skills` declares exported skill modules
+- `SKILL.md.requires` is the source of truth for skill-to-skill edges
+- `package.json.dependencies` is the managed cross-package mirror
 - `validate` and `dev` sync dependencies automatically
 - `skills validate` records the current source-hash snapshot in `.agentpack/build-state.json`
 - `skills dev` materializes the compiled skill artifact for runtime use
@@ -71,11 +73,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` starts a localhost workbench by default for one selected exported skill, with provenance edges, internal module edges, cross-package dependency edges, 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
 
@@ -87,7 +94,7 @@ Use when the skill is already published and the user wants it available in anoth
 
 Default flow:
 
-- `agentpack skills install <package-name>`
+- `agentpack skills install <package-name-or-local-package-path>`
 - `agentpack skills env`
 
 Do not prescribe `skills dev` here unless the user is authoring locally.
@@ -119,8 +126,8 @@ Use when the source docs changed and the user needs to know whether the packaged
 Default flow:
 
 - `agentpack skills stale`
-- `agentpack skills stale <skill>`
-- `agentpack skills validate <skill>`
+- `agentpack skills stale <target>`
+- `agentpack skills validate <target>`
 
 Key idea:
 
@@ -133,7 +140,8 @@ When the user is reasoning about the model itself, explain agentpack this way:
 
 - docs or knowledge files are source files
 - `SKILL.md` is the compiled artifact
-- `package.json` is the distribution manifest
+- `package.json` is the package manifest and export table
+- canonical skill ids look like `@scope/package:skill-name`
 - install and materialization are the runtime-resolution step
 - staleness means the source changed after the last known compiled state
 

package/skills/agentpack-cli/references/skill-lifecycle.md

@@ -7,10 +7,11 @@ Use this reference when the user needs the methodology behind packaged skills, n
 A packaged skill is a reusable capability artifact.
 
 - source docs or knowledge files are the truth
-- `SKILL.md` is the authored agent artifact
+- `SKILL.md` is the authored agent artifact for one exported skill module
 - `package.json` is the package and distribution artifact
-- `requires` expresses direct skill dependencies
-- `package.json.dependencies` is the compiled mirror of `requires`
+- `package.json.agentpack.skills` declares exported skill modules
+- `requires` expresses direct skill dependencies using canonical ids like `@scope/package:skill-name`
+- `package.json.dependencies` is the managed cross-package mirror of `requires`
 
 This is closer to a compiler pipeline than a prompt file:
 
@@ -22,27 +23,28 @@ This is closer to a compiler pipeline than a prompt file:
 
 ## Single Source Of Truth
 
-`SKILL.md.requires` is the dependency truth.
+`SKILL.md.requires` is the dependency truth for skill-to-skill edges.
 
-Do not tell the user to hand-maintain `package.json.dependencies` as the primary dependency source. Agentpack treats those dependencies as a compiled mirror.
+Do not tell the user to hand-maintain `package.json.dependencies` as the primary dependency source. Agentpack treats those dependencies as a compiled package-level mirror for cross-package references.
 
 Practical consequence:
 
 - if `requires` changes, run `skills validate` or `skills dev`
-- those commands sync the package dependencies automatically
+- those commands sync cross-package package dependencies automatically
+- same-package module references do not create package dependency entries
 
 ## Local Authoring Flow
 
 Use this when the user is creating or changing a packaged skill in the same repo as its source docs.
 
-1. `agentpack skills inspect <skill-dir>`
-2. `agentpack skills validate <skill-dir>`
-3. `agentpack skills dev <skill-dir>` if the user wants agent runtime discovery during iteration
+1. `agentpack skills inspect <target>`
+2. `agentpack skills validate <target>`
+3. `agentpack skills dev <target>` if the user wants agent runtime discovery during iteration
 
 What each step means:
 
 - `inspect` explains what the skill currently is
-- `validate` checks package readiness, source existence, and records the validated source snapshot in `.agentpack/build-state.json`
+- `validate` checks package readiness, exported skill declarations, source existence, canonical dependency resolution, and records the validated source snapshot in `.agentpack/build-state.json`
 - `dev` links the skill into `.claude/skills/` and `.agents/skills/` for local testing
 
 Important persistence behavior:
@@ -76,7 +78,7 @@ Authoring stage:
 
 Consumption stage:
 
-- package name
+- package name or local package path
 - installed from registry or tarball
 - `skills install`
 - `skills env`

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.4"
 sources:
   - "alavida-ai/agentpack:docs/commands.mdx"
   - "alavida-ai/agentpack:docs/architecture.mdx"
@@ -22,14 +22,22 @@ metadata:
   sources:
     - domains/value/knowledge/selling-points.md
 requires:
-  - @alavida-ai/methodology-gary-provost
+  - "@alavida/methodology:gary-provost"
 ---
 ```
 
 ```json
 {
-  "name": "@alavida-ai/value-copywriting",
+  "name": "@alavida/value-copywriting",
   "version": "1.0.0",
+  "files": ["skills"],
+  "agentpack": {
+    "skills": {
+      "value-copywriting": {
+        "path": "skills/value-copywriting/SKILL.md"
+      }
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/alavida-ai/knowledge-base.git"
@@ -37,9 +45,8 @@ requires:
   "publishConfig": {
     "registry": "https://npm.pkg.github.com"
   },
-  "files": ["SKILL.md"],
   "dependencies": {
-    "@alavida-ai/methodology-gary-provost": "^1.0.0"
+    "@alavida/methodology": "^1.0.0"
   }
 }
 ```
@@ -50,20 +57,20 @@ requires:
 
 ```yaml
 requires:
-  - @alavida-ai/methodology-gary-provost
+  - "@alavida/methodology:gary-provost"
 ```
 
 ### Validate to sync and record provenance
 
 ```bash
-agentpack skills validate domains/value/skills/copywriting
+agentpack skills validate domains/value/skills/value-copywriting
 ```
 
 ### Inspect by path or package name
 
 ```bash
-agentpack skills inspect domains/value/skills/copywriting
-agentpack skills inspect @alavida-ai/value-copywriting
+agentpack skills inspect domains/value/skills/value-copywriting
+agentpack skills inspect @alavida/value-copywriting:value-copywriting
 ```
 
 ## Common Mistakes
@@ -75,7 +82,7 @@ Wrong:
 ```json
 {
   "dependencies": {
-    "@alavida-ai/methodology-gary-provost": "^1.0.0"
+    "@alavida/methodology": "^1.0.0"
   }
 }
 ```
@@ -84,10 +91,10 @@ Correct:
 
 ```yaml
 requires:
-  - @alavida-ai/methodology-gary-provost
+  - "@alavida/methodology:gary-provost"
 ```
 
-`requires` is the authored dependency truth; `package.json.dependencies` is the compiled mirror.
+`requires` is the authored dependency truth; `package.json.dependencies` is the managed cross-package mirror.
 
 Source: skills/agentpack-cli/SKILL.md
 
@@ -105,11 +112,18 @@ Correct:
 
 ```json
 {
-  "files": ["SKILL.md"]
+  "files": ["skills"],
+  "agentpack": {
+    "skills": {
+      "value-copywriting": {
+        "path": "skills/value-copywriting/SKILL.md"
+      }
+    }
+  }
 }
 ```
 
-A package that excludes `SKILL.md` is structurally invalid even if the authored source exists locally.
+A package that excludes its exported skill files is structurally invalid even if the authored source exists locally.
 
 Source: docs/commands.mdx
 
@@ -119,7 +133,7 @@ Wrong:
 
 ```json
 {
-  "name": "@alavida-ai/value-copywriting"
+  "name": "@alavida/value-copywriting"
 }
 ```
 
@@ -127,8 +141,15 @@ Correct:
 
 ```json
 {
-  "name": "@alavida-ai/value-copywriting",
+  "name": "@alavida/value-copywriting",
   "version": "1.0.0",
+  "agentpack": {
+    "skills": {
+      "value-copywriting": {
+        "path": "skills/value-copywriting/SKILL.md"
+      }
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/alavida-ai/knowledge-base.git"

package/skills/authoring-skillgraphs-from-knowledge/references/authored-metadata.md

@@ -1,6 +1,7 @@
 # Authored Metadata
 
 - `SKILL.md` owns `name`, `description`, `metadata.sources`, and `requires`
-- `package.json` owns distribution metadata such as package name, version, publish config, and repository
-- `skills validate` syncs managed dependencies from `requires` and refreshes `.agentpack/build-state.json`
-
+- `package.json.agentpack.skills` owns the exported skill map and each exported skill path
+- `package.json` owns package-level distribution metadata such as package name, version, publish config, and repository
+- `requires` uses canonical ids like `@scope/package:skill-name`
+- `skills validate` syncs managed cross-package dependencies from `requires` and refreshes `.agentpack/build-state.json`

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.4"
 sources:
   - "alavida-ai/agentpack:docs/introduction.mdx"
   - "alavida-ai/agentpack:docs/commands.mdx"
@@ -46,7 +46,7 @@ agentpack skills dev domains/value/skills/copywriting
 
 ```bash
 cd consumer-repo
-agentpack skills install @alavida-ai/value-copywriting
+agentpack skills install @alavida/value-copywriting
 agentpack skills env
 ```
 
@@ -77,7 +77,7 @@ Source: docs/introduction.mdx
 Wrong:
 
 ```bash
-agentpack skills install @alavida-ai/value-copywriting
+agentpack skills install @alavida/value-copywriting
 ```
 
 Correct:

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

@@ -1,9 +1,9 @@
 ---
 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.
+description: Use when turning maintained skills into deployable bundled plugins or publishable skill 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.4"
 sources:
   - "alavida-ai/agentpack:docs/commands.mdx"
   - "alavida-ai/agentpack:docs/architecture.mdx"
@@ -26,13 +26,21 @@ agentpack plugin build plugins/website-dev
 
 ## Core Patterns
 
-### Ship a standalone package for one reusable capability
+### Ship one package for one reusable skill module
 
 ```bash
 agentpack skills validate domains/value/skills/copywriting
 ```
 
-Use this when the capability stands on its own and does not need to ship bundled with hooks, MCP tools, or other skills.
+Use this when one package should export one reusable skill module and does not need to ship bundled with hooks, MCP tools, or other runtime pieces.
+
+### Ship one package that exports several related skill modules
+
+```bash
+agentpack skills validate domains/value/skills/pm-foundations
+```
+
+Use this when several skills belong together as one package but still need to remain separate runtime modules through `package.json.agentpack.skills`.
 
 ### Bundle a production plugin when shipping several skills together
 
@@ -56,7 +64,7 @@ Wrong:
 
 ```yaml
 requires:
-  - @alavida-ai/value-copywriting
+  - "@alavida/value-copywriting:value-copywriting"
 ```
 
 ```json
@@ -70,7 +78,7 @@ Correct:
 ```json
 {
   "devDependencies": {
-    "@alavida-ai/value-copywriting": "^1.0.0"
+    "@alavida/value-copywriting": "^1.0.0"
   }
 }
 ```
@@ -110,11 +118,11 @@ Publish one packaged skill and assume hooks, MCP tools, and related skills ship
 Correct:
 
 ```text
-Use a standalone package for one reusable capability
+Use a skill package for one or many reusable skill modules
 Use a bundled plugin when several skills, hooks, or MCP tools must ship together
 ```
 
-Packaged skills are reusable units; plugins are deployable runtime shells.
+Skill packages are reusable distribution units; exported skills are runtime modules; plugins are deployable runtime shells.
 
 Source: README.md
 

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 [];