@alavida/agentpack

--- name: multi-skill-packages description: Use when deciding how to structure multi-skill packages, configure agentpack.root for named export discovery, and manage dependency edges between exported skills in agentpack. type: core library: agentpack library_version: "0.1.10" sources: - "alavida-ai/agentpack:docs/skill-graph.mdx" - "alavida-ai/agentpack:docs/schema-package-json.mdx" - "alavida-ai/agentpack:docs/publishing.mdx" --- # Agentpack - Multi-Skill Packages ## Setup A multi-skill package exports more than one skill from a single npm package. The root `SKILL.md` is the primary export. Additional named exports each have their own `SKILL.md` in a separate directory under the path declared in `agentpack.root`. Named exports are discovered from the filesystem automatically -- there is no explicit export table. ### Minimal multi-skill package layout ``` @acme/brand/ package.json SKILL.md # primary export skills/ value-copywriting/ SKILL.md # named export editorial-principles/ SKILL.md # named export tone-of-voice/ SKILL.md # named export ``` ### package.json with named exports ```json { "name": "@acme/brand", "version": "1.0.0", "description": "Brand copywriting and editorial skill package.", "files": ["SKILL.md", "skills/"], "agentpack": { "root": "skills" }, "repository": { "type": "git", "url": "git+https://github.com/acme-corp/knowledge-base.git" }, "publishConfig": { "registry": "https://npm.pkg.github.com" } } ``` The `agentpack.root` tells the toolchain where to discover named exports. Each subdirectory containing a `SKILL.md` becomes a named export. The `name` field in each `SKILL.md` frontmatter determines the export name. ### SKILL.md structure for an exported skill ```markdown --- name: value-copywriting description: Messaging and copywriting guidance grounded in brand selling points. --- ```agentpack source sellingPoints = "domains/brand/knowledge/selling-points.md" import editorial from skill "@acme/brand:editorial-principles" ``` Use ^[source:sellingPoints]{context="core product claims and differentiation"}. Apply ^[skill:editorial]{context="baseline style rules shared across the brand package"}. ``` The `source` statement declares provenance. The `import` statement declares a semantic edge to another exported skill. When that import points at another package, agentpack also mirrors the package dependency into `package.json.dependencies`. ## Core Patterns ### When to use one package vs many Group skills in one package when they: - share the same source knowledge files - are always versioned and released together - belong to the same bounded domain (e.g., "brand", "onboarding", "compliance") Split into separate packages when: - skills have independent version cadences - different teams own different skills - a skill has heavy transitive dependencies that consumers should not pull unless they need it The heuristic: if you would put the code in the same npm library, put the skills in the same package. If you would publish separate libraries, publish separate skill packages. ### The `agentpack.root` export discovery The `agentpack.root` field in `package.json` tells the toolchain which directory to scan for named exports. Every subdirectory under that path that contains a `SKILL.md` becomes a named export automatically. ```json "agentpack": { "root": "skills" } ``` Rules: - Every named export must have a valid `SKILL.md` in its directory. - The `name` field in each `SKILL.md` frontmatter determines the export name. - The root `SKILL.md` at the package root is the primary export (if present). - `agentpack publish validate` checks that each discovered export resolves to a valid `SKILL.md`. ### Canonical skill IDs When a package exports multiple skills, the canonical ID includes both the package name and the skill name: ``` @scope/package:skill-name ``` Examples: ``` @acme/brand:value-copywriting @acme/brand:editorial-principles @acme/brand:tone-of-voice ``` When a package exports exactly one skill with the same name as the package, the short form `@scope/package` is equivalent to `@scope/package:skill-name`. Use the full `@scope/package:skill-name` form in `import` declarations when referencing a specific skill from a multi-export package. ### `import` is the dependency declaration The current compiler-first model uses `import` statements in the `agentpack` block as the source of truth for skill-to-skill edges. An `import` both: - creates the semantic edge in the compiled graph - drives managed `package.json.dependencies` sync for cross-package package references Same-package imports do not add a `dependencies` entry because npm already ships those skills in the same package. Cross-package imports do. ```markdown ```agentpack import research from skill "@acme/research" import editorial from skill "@acme/brand:editorial-principles" ``` Use [research](skill:research){context="required verification workflow before factual claims"}. ``` Guidance: - Use same-package imports for explicit edges between co-exported skills. - Use cross-package imports for external skill dependencies. - Do not duplicate dependency declarations in frontmatter. ### How `package.json.dependencies` stays in sync agentpack manages `package.json.dependencies` from exported skill imports, the way `go mod tidy` manages `go.mod`: 1. Read cross-package `import` statements from each exported `SKILL.md`. 2. Compare against `dependencies` in `package.json`. 3. Add any required package entries that are missing. 4. Remove any `dependencies` entries that are no longer referenced by those imports. 5. Write the updated `package.json`. This sync runs automatically inside `agentpack author dev`. `agentpack publish validate` checks alignment but does not write. You never edit `dependencies` by hand for skill edges. Same-package imports do not generate dependency entries. Only cross-package imports produce `dependencies` entries. ### Inspecting and validating multi-skill packages ```bash # Inspect a specific exported skill by path agentpack author inspect domains/brand/skills/value-copywriting # Inspect by canonical ID agentpack author inspect @acme/brand:value-copywriting # Validate the entire package (checks all exports) agentpack publish validate domains/brand # Dev mode for a specific exported skill agentpack author dev domains/brand/skills/value-copywriting ``` `publish validate` checks all exports discovered from the filesystem: - Each discovered `SKILL.md` parses correctly. - All cross-package skill imports are reflected in `dependencies`. - `files` includes the exported skill paths. - Package identity fields (`name`, `version`, `repository`, `publishConfig`) are present. `author inspect` shows the skill graph for one exported skill, including its source bindings and skill-import edges. ### Internal edges between co-exported skills Skills within the same package can depend on each other through same-package imports: ```markdown ```agentpack import editorial from skill "@acme/brand:editorial-principles" ``` Follow the [editorial principles](skill:editorial){context="baseline style rules that all copy must satisfy"}. ``` This creates a same-package edge. Because both skills ship in `@acme/brand`, no `dependencies` entry is generated. The skill graph still records the edge for staleness propagation and visualization. ### Cross-package edges from a multi-skill package When an exported skill depends on a skill in a different package, declare it with an import: ```markdown ```agentpack import provost from skill "@acme/methodology:gary-provost" ``` ``` After running `agentpack publish validate`, the package.json will contain: ```json { "dependencies": { "@acme/methodology": "^1.0.0" } } ``` Multiple exported skills can import different skills from the same external package. The dependency appears once in `package.json`. ## Common Mistakes ### CRITICAL Putting all skills in one mega-package Wrong: one package with skills from unrelated domains. ```json { "name": "@acme/everything", "agentpack": { "root": "skills" } } ``` Correct: split by domain boundary. ```json // @acme/brand package { "name": "@acme/brand", "agentpack": { "root": "skills" } } // @acme/engineering package { "name": "@acme/engineering", "agentpack": { "root": "skills" } } ``` A mega-package forces every consumer to install every skill even when they only need one domain. Version bumps in unrelated skills force unnecessary upgrades across all consumers. ### CRITICAL Missing `agentpack.root` for named exports Wrong: ```json { "name": "@acme/brand", "version": "1.0.0", "files": ["skills/"] } ``` Correct: ```json { "name": "@acme/brand", "version": "1.0.0", "files": ["SKILL.md", "skills/"], "agentpack": { "root": "skills" } } ``` Without `agentpack.root`, the toolchain only discovers the root `SKILL.md` as the primary export. Named exports under subdirectories are invisible unless `agentpack.root` points to the directory that contains them. Source: docs/schema-package-json.mdx ### HIGH Manually editing `package.json` dependencies for skill edges Wrong: ```json { "dependencies": { "@acme/methodology": "^1.0.0", "@acme/research": "^2.0.0" } } ``` Correct: author cross-package imports in each `SKILL.md`. ```markdown ```agentpack import provost from skill "@acme/methodology:gary-provost" import research from skill "@acme/research:fact-checking" ``` ``` `package.json.dependencies` is managed output. agentpack derives it from exported skills' cross-package imports during `author dev`. `publish validate` checks alignment but does not write. Manual edits will be overwritten on the next `author dev` run. Source: docs/schema-package-json.mdx ### HIGH Mismatched directory name and SKILL.md name The directory name under `agentpack.root` is cosmetic -- the export name comes from the `name` field in `SKILL.md` frontmatter. But keeping them aligned avoids confusion: Wrong: ``` skills/ copywriting/ SKILL.md # name: value-copywriting ``` Correct: ``` skills/ value-copywriting/ SKILL.md # name: value-copywriting ``` ### MEDIUM Treating imports as optional for cross-package dependencies Wrong: describing an external dependency in prose but never declaring the import. ```markdown ```agentpack import research from skill "@acme/research" ``` ``` If the external skill is part of the package contract, declare the import explicitly so agentpack can sync the package dependency and the compiled graph edge. Correct: declare the import and reference it in the body when needed. ```markdown ```agentpack import research from skill "@acme/research" ``` ``` ### MEDIUM Excluding skill directories from `files` Wrong: ```json { "files": ["README.md"], "agentpack": { "root": "skills" } } ``` Correct: ```json { "files": ["SKILL.md", "skills/"], "agentpack": { "root": "skills" } } ``` The `files` array controls what npm publishes. If it does not include the exported skill directories, the published package will be empty. `publish validate` checks that `files` includes the exported paths. Source: docs/schema-package-json.mdx ## References - `docs/schema-package-json.mdx` - `docs/schema-skill-md.mdx` - `docs/skill-graph.mdx` - `docs/publishing.mdx`