Skip to content

Bundle & Composite Authoring

Learn to create, configure, and publish bundles and composite artifacts. Bundles package multiple artifacts for distribution to teams and the marketplace. Composites group Tier 0 primitives (skills, commands, agents) into reusable combinations.

Walkthrough available

See the Product Manager Walkthrough for a complete bundle authoring and team publishing journey.

Overview

Bundle vs. Composite: When to use each

SkillMeat organizes artifacts in four tiers, from atomic primitives to full distributions:

  • Tier 0 (Primitives): Skills, Commands, Agents, Hooks, Workflows — the building blocks
  • Tier 1 (Composites): Groups of Tier 0 artifacts with a single deployment unit
  • Tier 2 (Deployment Sets): Curated multi-artifact collections
  • Tier 3 (Bundles & Distributions): Distribution packages for marketplace publishing

Bundle vs. Composite at a glance:

Artifact Purpose Contains Scope Best For
Bundle Distribution package Any artifacts (skills, commands, agents, workflows, etc.) Multi-purpose Shipping curated collections; marketplace publishing; team templates
Composite Grouped primitives Tier 0 artifacts only (skills, commands, agents, hooks) Focused Grouping related primitives into a cohesive unit for deployment

In Practice: - Use a Bundle when you want to package a complete solution (e.g., "Python Backend Skills Bundle" containing a skill, command, and hook) - Use a Composite when you want to group related primitives (e.g., "Document Processing" composite with analysis + generation skills) - A bundle can contain a composite as one of its members

Think of bundles as distribution formats and composites as logical groupings.

Prerequisites

Before authoring bundles or composites, you need:

  1. SkillMeat installed — See Quickstart Guide
  2. Collection initialized — Run skillmeat init. See Collection Initialization & Configuration
  3. Artifacts to bundle — The skills, commands, agents, or other artifacts you want to include. See Adding Artifacts if you need to add them first
  4. Optional: Version strategy — Understanding of semantic versioning. See Marketplace Publishing for versioning best practices

Verify your collection and artifacts are ready:

# List all artifacts in your collection
skillmeat list

# Filter by type if you have many
skillmeat list --type skill
skillmeat list --type command

You should see the artifacts you plan to bundle.

  1. Open the Web UI (typically http://localhost:3000)
  2. Navigate to Collection
  3. You should see your artifacts listed by type

Create a Bundle

Using the CLI

Create a new bundle with a name and optional description:

# Basic bundle creation
skillmeat bundle create my-bundle

# With description
skillmeat bundle create my-bundle --description "A collection of Python processing skills"

This creates a bundle directory structure in your collection:

~/.skillmeat/collections/default/
└── bundles/
    └── my-bundle/
        ├── bundle.toml          # Bundle manifest
        ├── bundle.lock          # Version lock file
        └── members.yaml         # Bundle membership (auto-created)

Using the Web UI

  1. Open the Web UI
  2. Navigate to Collection → Bundles tab
  3. Click Create New Bundle
  4. Enter the bundle name and description
  5. Click Create

The bundle is now created and ready for members.

Bundle Manifest Structure

The bundle.toml file defines your bundle. Here's a minimal example:

[tool.skillmeat]
type = "bundle"
name = "my-bundle"
version = "1.0.0"
description = "A collection of Python processing skills"
author = "Your Name <your.email@example.com>"
license = "MIT"

[[artifacts]]
name = "text-analyzer"
type = "skill"
source = "username/repo/skills/text-analyzer"
version = "latest"

[[artifacts]]
name = "data-processor"
type = "command"
source = "username/repo/commands/data-processor"
version = "1.2.0"

[[artifacts]]
name = "document-hook"
type = "hook"
source = "local:./my-hook"
version = "latest"

Key fields: - name — Bundle identifier (lowercase, hyphens) - version — Semantic version (major.minor.patch) - description — One-line summary - author — Creator name and email - license — SPDX license identifier (e.g., MIT, Apache-2.0) - artifacts — Array of members to include

Add Members to a Bundle

Using the CLI

Add individual artifacts to a bundle:

# Add a skill from your collection
skillmeat bundle add my-bundle text-analyzer

# Add multiple artifacts
skillmeat bundle add my-bundle text-analyzer data-processor document-hook

# Add a specific version
skillmeat bundle add my-bundle text-analyzer@1.2.0

Using the Web UI

  1. Open the bundle detail page
  2. Click Add Members
  3. Search for artifacts in your collection
  4. Select artifacts to add (you can multi-select)
  5. Click Add Selected

The artifacts are now part of the bundle.

View Bundle Members

skillmeat bundle list-members my-bundle

Output: 

Bundle: my-bundle (1.0.0)
Members (3):

├─ text-analyzer (skill, v1.0.0)
├─ data-processor (command, v1.2.0)
└─ document-hook (hook, v1.0.0)

Open the bundle detail page. The Members tab shows all included artifacts with their types and versions.

Version & Publish Your Bundle

Understanding Versions

Bundles use semantic versioning (major.minor.patch): - 1.0.0 — Major (breaking changes) - 1.1.0 — Minor (new features, backward-compatible) - 1.0.1 — Patch (bug fixes)

Update the version in your bundle manifest before publishing:

[tool.skillmeat]
version = "1.1.0"  # Bumped for new feature

Publish to the Marketplace

Once your bundle is ready, publish it for others to discover and use:

# Publish your bundle
skillmeat bundle publish my-bundle

# Publish with a specific version
skillmeat bundle publish my-bundle --version 1.1.0

On first publish, you'll be prompted for publisher credentials (name, email).

  1. Open the bundle detail page
  2. Click Publish to Marketplace
  3. Review the bundle summary, members, and metadata
  4. Confirm publisher information
  5. Click Publish

Before Publishing

Ensure: - All artifacts are included and tested - Version is incremented according to semver - Bundle name is descriptive (users will search by this) - Description is clear and highlights what the bundle includes - License is specified (e.g., MIT, Apache-2.0, GPL-3.0)

After Publishing

Your bundle is now on the marketplace. Users can: - Search for it by name - View detailed information (description, members, author) - Install it into their collections - Rate and provide feedback

To update your published bundle, increment the version and publish again.

For detailed marketplace publishing guidance (including governance workflows and approval requirements), see Marketplace Full Guide.

Create a Composite Artifact

Composites are Tier 1 artifacts that group Tier 0 primitives (skills, commands, agents, hooks) into a cohesive unit.

Key Differences from Bundles

  • Composites are deployable units with a single COMPOSITE.md manifest
  • Bundles are distribution packages that contain multiple artifacts
  • Composites work best for tightly related primitives (e.g., skills that always work together)
  • Bundles work best for curated collections or marketplace distribution

Using the CLI

Create a composite:

# Create a new composite
skillmeat composite create my-composite --description "Related text processing skills"

# Add members
skillmeat composite add my-composite text-analyzer text-formatter

This creates:

~/.skillmeat/collections/default/
└── composites/
    └── my-composite/
        ├── COMPOSITE.md         # Composite manifest
        ├── composite.toml       # Configuration
        └── members.yaml         # Membership

Using the Web UI

  1. Open the Web UI
  2. Navigate to Collection → Composites tab
  3. Click Create New Composite
  4. Enter the name and description
  5. Click Create
  6. On the detail page, click Add Members to include skills, commands, agents, or hooks

Composite Manifest Example

---
skillmeat-type: composite
name: text-processing
version: 1.0.0
description: Integrated text analysis and formatting tools
author: Your Name
license: MIT
members:
  - text-analyzer
  - text-formatter
  - formatting-hook
---

# Text Processing Composite

A unified set of tools for analyzing and formatting text documents.

## Included Artifacts

- **text-analyzer** (Skill) — Analyzes document structure and content
- **text-formatter** (Command) — Applies consistent formatting
- **formatting-hook** (Hook) — Auto-formats on deployment

## Usage

Deploy this composite to your project to get all three artifacts:

```bash
skillmeat deploy text-processing

All components will be available in your .claude/ directory. 

### Deploy a Composite

Composites deploy as a single unit:

=== "CLI"
    ```bash
    # Deploy the entire composite
    skillmeat deploy my-composite

    # This deploys all members to your project
    ```

=== "Web UI"
    1. Open the Collection
    2. Find the composite in the Composites tab
    3. Click the **Deploy** button
    4. Confirm to deploy all members to your project

---

## Verify Your Bundle or Composite

### Using the CLI

List all bundles or composites in your collection:

```bash
# List all bundles
skillmeat list --type bundle

# List all composites
skillmeat list --type composite

# Show detailed info
skillmeat bundle info my-bundle
skillmeat composite info my-composite

Using the Web UI

  1. Open the Collection page
  2. Navigate to Bundles or Composites tab
  3. Search or browse your created artifacts
  4. Click any bundle or composite to view:
  5. Description and metadata
  6. All members with versions
  7. Deployment status
  8. Publishing history (for published bundles)

Next Steps

Tips & Troubleshooting

Bundle Best Practices

  • Keep related artifacts together — Group skills and commands that work together
  • Version consistently — Use semantic versioning and document what changed in each version
  • Test before publishing — Deploy your bundle to a test project and verify all members work
  • Write clear descriptions — Users search by bundle name and description
  • Include licensing info — Ensure all artifacts have compatible licenses

Composite Best Practices

  • Use for tight coupling — Composites work best when artifacts have strong dependencies
  • Include hooks and helpers — Add hooks for setup, teardown, or integration
  • Document interdependencies — Explain in the manifest how the artifacts work together
  • Version with members — Update the composite version when member versions change significantly

Common Issues

Bundle won't publish: - Check that all member artifacts are valid and accessible - Verify your publisher credentials are set - Ensure bundle version follows semantic versioning (e.g., 1.0.0)

Can't add artifact to bundle: - Verify the artifact exists in your collection: skillmeat list - Check artifact name matches exactly (case-sensitive) - Artifact must be in a format supported by bundles

Deployed composite missing members: - Verify all members are present in the composite manifest - Check member artifact paths are correct - Re-run discovery to scan for newly added artifacts