Creating & Publishing Packs: A Complete Guide

Turn your AI workflows into installable packages.

What is a Pack?

A Pack is a bundle of context files that your AI agent reads to understand how to work in your project. Think of it like:

• npm packages → for code dependencies
• CorePack Packs → for AI behavior dependencies

Packs can contain:

• Coding standards and conventions
• Project architecture docs
• Persona definitions (e.g., "Senior Backend Engineer")
• Workflow instructions
• Memory templates

The Philosophy

1. Context as Code

Your AI context should be:

• Version-controlled alongside your code
• Shareable across teams and projects
• Composable (use multiple packs together)

2. Read-Only Engine, Editable Context

Every pack has two parts:

• Engine (bin/) → The pack's logic, workflows, instructions. Read-only, managed by CLI.
• Templates (templates/) → Generates project-specific files. Editable by agents.

3. Immutability

Once you publish version 1.0.0, it's locked forever. Users who installed 1.0.0 will always get exactly that version. To make changes, bump the version.

Pack Structure

A valid pack must have this structure:

my-pack/
├── pack.config.json     # Required: Pack metadata
├── README.md            # Required: Pack description
├── boot.md              # Optional: Agent entry point
├── bin/                 # Required: Engine logic (read-only)
│   └── workflows/       # Example: workflow files
├── templates/           # Optional: Context templates
│   └── context/         # Files that get copied to user's project
└── pack-lock.json       # Auto-generated: Integrity checksums

pack.config.json

This is the manifest. Here's the full specification:

{
  "name": "@yourname/pack-name",
  "version": "1.0.0",
  "description": "What this pack does.",
  "visibility": "public",
  "context_engine": "bin",
  "context_template": "templates",
  "dependencies": {
    "@corepackai/ucp": "latest"
  },
  "tags": ["category", "keywords", "for-search"]
}

Required Fields

Optional Fields

Creating Your First Pack

Step 1: Create the Directory

mkdir my-pack
cd my-pack

Step 2: Create pack.config.json

{
  "name": "@yourname/my-pack",
  "version": "1.0.0",
  "description": "My first context pack.",
  "tags": ["example", "starter"]
}

Important: Replace yourname with your GitHub username.

Step 3: Create README.md

# My Pack

This pack does...

## Installation

\`\`\`bash
npx corepackai install @yourname/my-pack
\`\`\`

Step 4: Create the Engine

mkdir bin

Add your workflow files inside bin/. These are the instructions your AI agent will follow.

Example bin/coding-standards.md:

# Coding Standards

- Use TypeScript for all new files
- Follow Prettier formatting
- Write JSDoc comments for public functions

Step 5: (Optional) Create Templates

mkdir -p templates/context

Files in templates/ get copied to the user's .ai/context/ directory when they install. These are the editable, project-specific files.

Publishing

Step 1: Login

npx corepackai login

This opens GitHub OAuth. After authentication, your credentials are saved locally.

Step 2: Publish

npx corepackai publish

The CLI will:

1. Validate your pack.config.json
2. Check that README.md exists
3. Verify you own the @yourname scope
4. Create a zip archive
5. Upload to the registry
6. Generate pack-lock.json for integrity

What Happens Next?

• New packs: Status is pending (awaiting approval)
• Approved packs: Updates go live immediately
• Version bumps: Required for every change (immutable registry)

Version Bumping

The registry is immutable. To publish changes:

{
  "name": "@yourname/my-pack",
  "version": "1.0.1"  // Bumped from 1.0.0
}

Then:

npx corepackai publish

Dependencies

Packs can depend on other packs:

{
  "name": "@yourname/my-pack",
  "version": "1.0.0",
  "dependencies": {
    "@corepackai/ucp": "latest"
  }
}

When a user installs your pack, dependencies are installed automatically.

Scope Rules

• You can only publish under your own scope: @yourusername/...
• The scope must match your GitHub username
• Reserved scopes: @corepackai is reserved for official packs

Example: If your GitHub username is alice, you can only publish:

• ✅ @alice/my-pack
• ❌ @bob/my-pack (not your scope)
• ❌ @corepackai/my-pack (reserved)

Private Packs

To keep a pack private (only visible to you):

{
  "name": "@yourname/internal-pack",
  "version": "1.0.0",
  "visibility": "private"
}

Private packs:

• Do not appear in the public marketplace
• Can only be installed by authenticated users you authorize

Testing Before Publishing

Before publishing, test your pack locally:

# From another project
npx corepackai install /path/to/my-pack

This installs from a local directory instead of the registry.

Updating the UCP Tutorial

Now that you know how packs work, update the reference in our UCP tutorial:

👉 Getting Started with UCP

Quick Reference

Need Help?

• Source Code: github.com/breeznik/workflows
• Discord: discord.gg/gUph8dFNDY
• Marketplace: corepackai.com/browse

Now go build something and share it with the world. 🚀