@alavida/agentpack 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alavida/agentpack",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Package-backed skills lifecycle CLI for agent skills and plugins",
   "type": "module",
   "bin": {

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.3
+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
@@ -77,7 +79,7 @@ Persistence rule:
 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
@@ -92,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.
@@ -124,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:
 
@@ -138,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.3"
+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/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.3"
+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/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.3"
+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