Skip to content

Bundle Build, Publish, and Deploy

Build portable .skillmeat-pack archives containing your Skills, Commands, Agents, Rules, Specs, Context Files, Templates, and Project Configs. Publish bundles to the marketplace, deploy them to project directories, and share collections across teams and instances.

Overview

This guide covers the complete workflow for managing bundles with SkillMeat:

  • Build: Use build-pack to create a .skillmeat-pack archive from a directory of artifacts.
  • Publish: Use bundle publish to make a bundle available in the marketplace catalog (local edition) or via the API (both editions).
  • Deploy: Use bundle deploy to install bundle members into your project structure.

Supported Bundle Member Types

Bundles can contain:

  • Skills — reusable agent workflows and capabilities
  • Commands — CLI commands and shortcuts
  • Agents — specialized subagent definitions
  • Rules — style guides, ADRs, constraints (.md files under .claude/rules/)
  • Specs — design specs and planning documents (.md files under .claude/specs/)
  • Context Files — key-context and support docs (.md files under .claude/context/)
  • Templates — artifact templates for scaffolding
  • Project Config — .skillmeat/manifest.toml and configuration

Building a Bundle from a Directory

Step 1: Organize Your Artifacts

Create a directory with all the artifacts you want to bundle:

my-starter-bundle/
├── skills/
│   ├── my-skill/
│   │   ├── SKILL.md
│   │   ├── workflows/
│   │   └── ...
├── commands/
│   ├── cli-command.yaml
├── agents/
│   ├── my-agent.yaml
├── rules/
│   ├── architecture.md
│   └── testing.md
└── specs/
    └── design-spec.md

Step 2: Build the Pack

Use bundle build-pack to create a portable .skillmeat-pack archive:

skillmeat bundle build-pack ./my-starter-bundle \
  --bundle-name "my-starter-bundle" \
  --bundle-version "1.0.0"

Output: 

Created .skillmeat-pack: my-starter-bundle-1.0.0.skillmeat-pack
Members: 8 (2 skills, 1 command, 1 agent, 2 rules, 1 spec, 1 template)
Bundle ID: <pack-hash>

Options:

  • --bundle-name NAME — Name of the bundle (defaults to directory name)
  • --bundle-version VERSION — Semantic version (defaults to 0.0.0)
  • --output PATH — Output directory for the .skillmeat-pack file (defaults to current directory)
  • --targets ARTIFACT_ID[,...] — (Optional) Filter to specific member artifacts; default includes all

Note on pack hashing: Bundle hashes are deterministic based on the decompressed archive contents. If you rebuild a bundle, the hash will change only if the contents differ. Old packs built with earlier versions must be rebuilt to use the updated hash algorithm.

Publishing a Bundle

Via Local Edition (Full Support)

Create a local bundle and publish it in one command:

skillmeat bundle create my-new-bundle
skillmeat bundle add-member my-new-bundle my-skill
skillmeat bundle add-member my-new-bundle my-command
skillmeat bundle publish my-new-bundle

Verify publication:

skillmeat bundle show my-new-bundle
# Status: published
# Available in marketplace: true

Via Pack (Local Edition)

Build a pack and publish it directly:

skillmeat bundle build-pack ./my-starter-bundle \
  --bundle-name "my-starter-bundle" \
  --bundle-version "1.0.0"

# Verify pack integrity
skillmeat bundle import my-starter-bundle-1.0.0.skillmeat-pack --dry-run

# Import and publish
skillmeat bundle import my-starter-bundle-1.0.0.skillmeat-pack
skillmeat bundle publish my-starter-bundle

Deploying a Bundle

Deploy All Members to a Project

Install all members of a bundle into your project:

skillmeat bundle deploy my-starter-bundle --project ./my-project

# Or dry-run to preview
skillmeat bundle deploy my-starter-bundle --project ./my-project --dry-run

Output: 

Deploying 8 members of 'my-starter-bundle':
  [+] skills/my-skill → .claude/skills/my-skill/
  [+] commands/cli-command.yaml → .claude/commands/cli-command.yaml
  [+] agents/my-agent.yaml → .claude/agents/my-agent.yaml
  [+] rules/architecture.md → .claude/rules/architecture.md
  [+] specs/design-spec.md → .claude/specs/design-spec.md
  [+] templates/template.md → .claude/templates/template.md
  [+] config → .skillmeat/manifest.toml

Deploy complete: 8 installed

Deploy with Project Scaffolding

Create a project scaffold and deploy a bundle in one step:

skillmeat scaffold --standard my-project

cd my-project
skillmeat bundle deploy my-starter-bundle --project .

This creates the standard .claude/ directory structure and installs all bundle members.

Enterprise Edition Guidance

Enterprise edition supports bundle operations with the following known limitations:

Supported Operations

  • Publish via pack: skillmeat bundle build-pack + skillmeat bundle import on the enterprise API
  • Deploy: skillmeat bundle deploy deploys to local project directories

Partially Supported (Guidance Mode)

The following operations are available in local edition only and print actionable guidance on enterprise:

bundle export (not yet supported)

skillmeat bundle export my-bundle
# Error: `bundle export` reads from the local SQLite cache and is not yet
# supported against an enterprise instance.
#
# Workaround: Use `skillmeat enterprise import <dir>` to sync artifacts
# to the enterprise DB first, then retry.

bundle import (direct pack import; enterprise-publish route works)

skillmeat bundle import my-bundle.skillmeat-pack
# Error: Enterprise pack import is not yet supported directly via this command.
#
# Workaround: Use `skillmeat bundle publish --from-dir <dist-dir>`
# (the canonical enterprise publish path via /bundles/import/with-targets),
# or `skillmeat enterprise import <dir>` to sync artifacts first.

bundle add-member (on enterprise DB)

skillmeat bundle add-member my-bundle my-artifact
# Error: Artifact 'my-artifact' not found in the enterprise DB.
#
# Workaround: Use `skillmeat enterprise import <dir>` to sync artifacts
# to the enterprise DB first, then retry.

Workaround for Enterprise

For enterprise deployments, ensure artifacts exist in the enterprise database before performing bundle operations:

# 1. Export your local artifacts (if migrating from local edition)
skillmeat collection export --output /tmp/my-collection

# 2. Import into the enterprise instance
skillmeat enterprise import /tmp/my-collection

# 3. Now bundle operations work against the enterprise DB
skillmeat bundle publish my-bundle
skillmeat bundle deploy my-bundle --project ./my-project

For enterprise federation and pack distribution, use the enterprise-specific import endpoints. See Enterprise Deployment (coming in future releases) for full details.

Troubleshooting

Hash Mismatch on Import

Symptom: Import fails with "hash validation failed" or similar.

Cause: The bundle was built with an old version of SkillMeat that hashed the gzip-compressed bytes instead of the decompressed archive.

Solution: Rebuild the bundle:

skillmeat bundle build-pack ./my-starter-bundle --bundle-version "1.0.1"
skillmeat bundle import my-starter-bundle-1.0.1.skillmeat-pack

Hollow Bundle (Empty Members)

Symptom: Deploy or show reports "0 members" or members have no content.

Cause: The pack was built from an empty or incomplete source directory.

Solution: Verify your source directory contains valid artifacts, then rebuild:

ls -la ./my-starter-bundle/
skillmeat bundle build-pack ./my-starter-bundle --bundle-version "1.0.2"

501 Error on Enterprise

Symptom: bundle export or bundle import returns HTTP 501.

Cause: The operation is not supported in enterprise edition.

Solution: Refer to Enterprise Edition Guidance above for the recommended workaround.

Empty Deploy

Symptom: bundle deploy completes but no files are written to the project.

Cause: The bundle has no members, or all members were skipped due to conflicts.

Solution: Check bundle contents:

skillmeat bundle show my-bundle
skillmeat bundle deploy my-bundle --project ./my-project --dry-run

If conflicts exist, use --conflict-strategy overwrite to replace existing files (use with caution).

Advanced: Filtering Bundle Members

Build a pack with only specific artifacts:

skillmeat bundle build-pack ./my-starter-bundle \
  --targets "skill:my-skill,command:cli-command"

This creates a smaller pack with only the named members.

Next Steps