source readme = "README.md"
source quickstart = "docs/quickstart.mdx"
source dependenciesGuide = "docs/skill-graph.mdx"
source schemaGuide = "docs/schema-skill-md.mdx"
source lifecycleGuide = "docs/how-it-works.mdx"
source docsAsSources = "docs/docs-as-sources.mdx"
source dashboardGuide = "docs/dashboard.mdx"

Use this skill when the user is working with @alavida/agentpack and needs the right lifecycle framing, not just a command snippet.

Agentpack is a lifecycle toolchain for agent artifacts:

• a package is the distribution unit
• an exported skill is the runtime module unit
• runtime adapters materialize compiled skills for a target environment
• source docs are the truth
• SKILL.md is the compiled agent-facing artifact
• package.json is the distributable package artifact

Do not answer with isolated commands until you identify which lifecycle stage the user is in:

• authoring a packaged skill
• testing a packaged skill locally
• installing a published skill in a consumer repo
• building a compiled skill artifact
• materializing that artifact into runtime directories
• checking staleness after source docs change

If the user is confused, explain the stage boundary first.

For source-backed packaged skills, run authoring commands from the repo that owns the files referenced in the agentpack source bindings.

If a skill points at domains/.../knowledge/*.md, run publish validate, author dev, and author stale from that knowledge-base repo root, not from the agentpack repo.

Use when the user is creating or editing one packaged skill module or a package that exports several skill modules.

Default flow:

• agentpack author inspect <target>
• agentpack publish validate <target>
• agentpack author dev <target> if local runtime testing is needed
• agentpack author dev --no-dashboard <target> if the user wants to skip the local workbench

Key idea:

• root SKILL.md is the primary export; agentpack.root declares the directory for named exports
• import ... from skill "@scope/package" is the source of truth for skill-to-skill edges
• package.json.dependencies is the managed cross-package mirror
• publish validate and author dev sync dependencies automatically
• author build and compiler-mode publish validate update .agentpack/compiled.json
• author dev materializes the compiled skill artifact for runtime use

Persistence rule:

• commit .agentpack/compiled.json when you want compiled semantic state reviewed or shared
• do not commit .agentpack/install.json
• do not commit .agentpack/dev-session.json
• do not commit .agentpack/materialization-state.json
• commit skills/sync-state.json when maintaining the shipped Intent skills for this package

Runtime notes:

• after author dev writes to .claude/skills/ or .agents/skills/, start a fresh agent session if the current one was already running
• author 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
• author 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 author dev cleanup and escalate to agentpack author dev cleanup --force only when the recorded pid is a false positive
• use agentpack author unlink <root> --recursive when you need to remove one active dev root plus its transitive local runtime links
• do not manually reconstruct source provenance from prose 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

Read skill-lifecycle.md when the user needs the full methodology.

Use when the skill is already published and the user wants it available in another repo.

Default flow:

• npm install <package-name>
• agentpack skills list
• agentpack skills enable <package-name>

Do not prescribe author dev here unless the user is authoring locally.

Use when the user wants a canonical compiled artifact or needs runtime outputs refreshed from that artifact.

Default flow:

• agentpack author build <target>
• agentpack author materialize
• agentpack author dev <target> for local watch mode and the workbench

Key idea:

• .agentpack/compiled.json is the semantic source of truth
• .agentpack/materialization-state.json records emitted adapter outputs
• runtime directories are outputs, not semantic truth

Use when the source docs changed and the user needs to know whether the packaged skill must be rebuilt or revalidated.

Default flow:

• agentpack author stale
• agentpack author stale <target>
• agentpack publish validate <target>

Key idea:

• author stale compares current source hashes to the last known compiled state
• the canonical authored path is .agentpack/compiled.json

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 package manifest and discovery config
• 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

Read knowledge-as-package.md when the user needs this framing.

Be explicit about:

• which repo the command must run from
• whether the target is a local path or a published package name
• whether the user is in authoring, consumer-install, or compiler/materialization mode
• what the next irreversible step is

Do not collapse authored skill lifecycle and consumer install lifecycle into one answer.

Ground lifecycle explanations in the README{context="high-level product framing, command surface, and current development workflow"}.

Use the quickstart guide{context="source of truth for the minimal compiler-mode package layout and dev workflow"}.

Use the skill dependencies guide{context="source of truth for compiler-mode skill imports and package dependency mirroring"}.

Use the SKILL.md schema guide{context="source of truth for compiler-mode frontmatter, agentpack declarations, and contextual body references"}.

Use the lifecycle guide{context="source of truth for the compiled artifact model and lifecycle boundaries"}.

Use the docs-as-sources guide{context="source of truth for source-backed skills and stale detection framing"}.

Use the dashboard guide{context="source of truth for the local workbench and graph visualization behavior"}.