01: Your First Pack

Create your first PromptPack-compliant prompt package in 15 minutes.

What You’ll Build

A .pack.json file that conforms to the PromptPack open standard—a vendor-neutral format that works with any AI framework, not just PromptKit.

Learning Objectives

In this tutorial, you’ll learn to:

• Install the PackC compiler
• Create a prompt source file
• Compile to PromptPack format
• Validate against the specification
• Inspect pack contents

Time Required

15 minutes

Prerequisites

• Basic command-line knowledge
• A text editor

Step 1: Install PackC

Choose your preferred installation method:

Option 1: Homebrew (Recommended)

brew install promptkit

Option 2: Go Install

go install github.com/AltairaLabs/PromptKit/tools/packc@latest

Verify installation:

packc version

Expected output:

packc v0.1.0

If packc isn’t found after using Go install, add Go’s bin directory to your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"
source ~/.zshrc  # or ~/.bashrc

Step 2: Create Project Structure

Create a directory for your first pack project:

# Create project directory
mkdir my-first-pack
cd my-first-pack

# Create subdirectories
mkdir -p prompts config packs

Your directory structure should look like:

my-first-pack/
├── prompts/     # Prompt YAML files
├── config/      # Arena configuration
└── packs/       # Compiled packs (output)

Step 3: Create a Prompt

Create your first prompt file:

cat > prompts/greeting.yaml <<'EOF'
apiVersion: promptkit.altairalabs.ai/v1alpha1
kind: PromptConfig
spec:
  task_type: greeting
  name: Greeting Assistant
  description: A friendly assistant that greets users

  system_prompt: |
    You are a friendly assistant. Greet the user warmly and ask how you can help.

  user_template: |
    User name:
    Time of day:

  template_engine: go

  parameters:
    temperature: 0.7
    max_tokens: 150
EOF

This creates a simple greeting prompt with template variables.

Step 4: Create Arena Configuration

Create an arena.yaml configuration that references your prompt:

cat > config/arena.yaml <<'EOF'
prompts:
  - ../prompts/greeting.yaml

tools_directory: ./tools
EOF

Step 5: Compile Your Pack

Now compile the prompt into a pack:

packc compile \
  --config config/arena.yaml \
  --output packs/greeting.pack.json \
  --id greeting

Expected output:

Loaded 1 prompt configs from memory repository
Compiling 1 prompts into pack 'greeting'...
✓ Pack compiled successfully: packs/greeting.pack.json
  Contains 1 prompts: [greeting]

What happened:

1. PackC read the arena.yaml configuration
2. Loaded the greeting.yaml prompt file
3. Compiled it into an optimized pack.json file
4. Saved it to packs/greeting.pack.json

Step 6: Inspect Your Pack

Look at what was created:

# Check file size
ls -lh packs/greeting.pack.json

# Inspect pack contents
packc inspect packs/greeting.pack.json

Expected output:

Pack Information
================
ID: greeting
Name: greeting
Version: 1.0.0
Compiler Version: packc-v0.1.0

Template Engine
===============
Engine: go

Prompts
=======
- ID: greeting
  Name: Greeting Assistant
  Description: A friendly assistant that greets users

  System Prompt:
  You are a friendly assistant. Greet the user warmly and ask how you can help.

  User Template:
  User name:
  Time of day:

  Parameters:
  - temperature: 0.7
  - max_tokens: 150

Step 7: Validate Your Pack

Ensure the pack is valid:

packc validate packs/greeting.pack.json

Expected output:

Validating pack: packs/greeting.pack.json
✓ Pack is valid

Step 8: View the Pack JSON

Look at the compiled JSON (optional):

cat packs/greeting.pack.json

You’ll see a structured JSON file containing your prompt in a format ready for the PromptKit SDK.

What You Learned

Congratulations! You’ve successfully:

• ✅ Installed packc
• ✅ Created a prompt configuration
• ✅ Compiled your first pack
• ✅ Validated the pack
• ✅ Inspected pack contents

Understanding the Pack

Your pack contains:

• Prompt metadata - Name, description, task type
• System prompt - Instructions for the AI
• User template - How to format user input with variables
• Parameters - Model settings (temperature, max_tokens)
• Compiler metadata - Version and compilation info

Try It Yourself

Experiment with your pack:

1. Modify the Prompt

Edit prompts/greeting.yaml to change the greeting style:

system_prompt: |
  You are a professional business assistant. Greet the user formally.

Then recompile:

packc compile --config config/arena.yaml --output packs/greeting.pack.json --id greeting

2. Add Parameters

Add more model parameters:

parameters:
  temperature: 0.9
  max_tokens: 200
  top_p: 0.95

3. Inspect Changes

Check the updated pack:

packc inspect packs/greeting.pack.json

Common Issues

Issue: packc: command not found

Solution: Add Go bin to PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Issue: arena.yaml not found

Solution: Ensure you’re in the project directory:

cd my-first-pack
ls config/arena.yaml  # Should exist

Issue: Invalid YAML syntax

Solution: Check indentation (use spaces, not tabs):

# Validate YAML
cat prompts/greeting.yaml

Next Steps

Now that you’ve compiled your first pack, you’re ready to:

• Tutorial 2: Multi-Prompt Packs - Build packs with multiple prompts
• How-To: Compile Packs - Learn more compilation patterns
• Reference: compile command - Complete compile documentation

Complete Code

Here’s the complete prompt file for reference:

# prompts/greeting.yaml
apiVersion: promptkit.altairalabs.ai/v1alpha1
kind: PromptConfig
spec:
  task_type: greeting
  name: Greeting Assistant
  description: A friendly assistant that greets users

  system_prompt: |
    You are a friendly assistant. Greet the user warmly and ask how you can help.

  user_template: |
    User name:
    Time of day:

  template_engine: go

  parameters:
    temperature: 0.7
    max_tokens: 150

And the arena configuration:

# config/arena.yaml
prompts:
  - ../prompts/greeting.yaml

tools_directory: ./tools

Congratulations on completing your first pack!

What You’ve Achieved

You’ve created a PromptPack-compliant package that:

• Is portable — Works with any PromptPack-compatible runtime, not just PromptKit
• Is validated — Conforms to the open specification
• Is production-ready — Can be versioned, deployed, and shared

Learn more about the PromptPack standard at promptpack.org.