agentpack

You already know the feeling:

• the skill worked in one repo, but now it is copied into three places
• a runtime has a skill on disk, but nobody knows which compiled artifact produced it
• the source knowledge changed, but the shipped skill never got updated
• the runtime still has a skill on disk, but nobody can tell whether it is current, stale, local, bundled, or installed transitively
• the agent "knows" something, but you no longer trust where that knowledge came from

That is the problem agentpack is for.

The core failure mode is lifecycle collapse. Most teams flatten four different artifact types into one fuzzy thing called "a skill":

• source knowledge
• compiled skill artifact
• runtime materialization
• installed environment state

Once those boundaries blur, everything gets worse:

• authors do not know what to update
• consumers do not know what to install
• runtimes drift from the last known compiled state
• agents end up running stale knowledge with no visible trust chain

agentpack gives those artifacts their own lifecycle again:

• source docs and knowledge files stay authoritative
• SKILL.md becomes the agent-facing artifact
• package.json becomes the distribution contract
• npm handles package resolution and versioning
• agentpack handles compilation, validation, staleness, local linking, install flow, and runtime materialization

This is for teams who want agent behavior to be packaged, inspectable, and updateable like software instead of copy-pasted prompt debris.

Docs: https://docs.alavida.ai

Development

For stateful behavior changes, run the formal model checks first:

npm run test:models

This bootstraps tla2tools.jar into .cache/tla/ and runs the current models in tla/.

Install

npm install -g @alavida/agentpack

Or without a global install:

npx @alavida/agentpack --help

Why It Exists

Most agent workflows still look like this:

• write source knowledge in one place
• hand-copy some of it into a skill
• hand-copy that skill into another repo or runtime
• lose track of what depends on what
• discover drift only when the agent produces the wrong output

agentpack gives you a real lifecycle instead:

1. Write and maintain source knowledge where your team already works.
2. Derive a skill artifact from that knowledge.
3. Validate it before release.
4. Link it locally for testing.
5. Publish it as a package.
6. Install and materialize it wherever it needs to run.

What It Does

agentpack covers four practical workflows:

1. Author a packaged skill from source docs or knowledge files.
2. Validate that skill before release.
3. Compile it into .agentpack/compiled.json.
4. Materialize it into .claude/skills/ and .agents/skills/ for testing or consumption.

Quick Start

Author and test a packaged skill

Run these commands from the repo that owns the source files bound in the skill's agentpack block:

agentpack author inspect domains/operations/skills/agonda-prioritisation
agentpack publish validate domains/operations/skills/agonda-prioritisation
agentpack author dev domains/operations/skills/agonda-prioritisation

Use author dev when you want the skill linked into .claude/skills/ and .agents/skills/ for local runtime testing. It now also starts a localhost development workbench by default for one selected skill, showing immediate provenance sources, direct required skills, lifecycle state, and workbench actions such as validation and stale checks.

Pass --no-dashboard if you want the original CLI-only linking workflow without the local dashboard.

If your agent session was already running, start a fresh session after linking so the runtime can pick up the newly materialized skill.

Install a published skill in another repo

npm install @scope/skill-package
agentpack materialize

Build and materialize a compiled skill

agentpack author build path/to/skill
agentpack author materialize

author build produces .agentpack/compiled.json. author materialize records adapter output ownership in .agentpack/materialization-state.json.

The Model

The most important distinction in agentpack is lifecycle stage.

Packaged skills

A packaged skill is a reusable capability artifact.

• source ... = "repo/path" bindings track provenance
• import ... from skill "@scope/package" defines skill dependencies
• package.json.dependencies are the package-level mirror for cross-package skill imports
• it is self-contained at runtime, not a pointer back to source files

Typical local flow:

• author inspect
• publish validate
• author dev

Consumer installs

Consumer repos do not author the skill. They install the published package and materialize it into agent-visible directories.

Typical consumer flow:

• npm install @scope/skill-package
• agentpack materialize
• agentpack skills list

What Agentpack Refuses To Blur

These are deliberate boundaries:

• Knowledge is the source of truth.
• Skills are derived artifacts.
• Runtime adapters materialize compiled skills.
• Installed state is repo-local runtime state.

If you blur those together, you get the exact problems this tool exists to stop:

• skills that silently depend on files they do not ship
• runtimes that cannot explain why a skill is present
• repos that cannot explain why a skill is present
• updates that change behavior without an explicit review step

Knowledge As A Package

agentpack works best when you treat knowledge like software:

• the source files explain the methodology or domain truth
• the skill is the compiled agent-facing artifact
• package metadata defines how the capability is distributed
• validation and stale checks stop the artifact drifting from its sources

That lets you manage agent behavior with the same discipline you already apply to code.

Source-Backed Skills

For source-backed skills, run authoring commands from the repo that owns the source files.

If a skill points at domains/.../knowledge/*.md, run:

• agentpack skills validate
• agentpack skills dev
• agentpack skills stale

from that knowledge-base repo root, not from the agentpack repo.

Commands

Implemented today:

• agentpack author inspect
• agentpack author dev
• agentpack author unlink
• agentpack author stale
• agentpack author build
• agentpack author materialize
• agentpack publish validate
• agentpack materialize
• agentpack skills list
• agentpack skills enable
• agentpack skills disable
• agentpack skills status

Docs

Hosted docs: https://docs.alavida.ai

Run the live downstream smoke harness against the isolated agonda and superpowers sandboxes with:

npm run test:sandboxes

Docs source: docs/

For local docs preview as a contributor:

npm i -g mint
cd docs
mint dev

Development

Run the full test suite:

npm test

Run the live sandbox harness:

npm run test:sandboxes

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:

npx changeset

Manual git tags are no longer the normal release path.

Optional Agent Integration

This package also ships an agent-facing skill under:

node_modules/@alavida/agentpack/skills/agentpack-cli/SKILL.md

Consumers can use TanStack Intent in their repos to map that shipped skill into their agent workflow so the agent knows how to use agentpack correctly.

This is recommended if you want downstream coding agents to follow the right agentpack lifecycle automatically.

It is still optional. You do not need Intent to install or run the CLI itself.

Metadata Policy

In authoring repos:

• commit .agentpack/compiled.json when you want compiled semantic state reviewed or shared
• compiled state is the only semantic source of truth
• 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
• do not commit .agentpack/materialization-state.json

License

MIT