Create Terrazul Assistant Package

This skill guides you through creating a complete Terrazul package - a reusable, distributable AI assistant configuration that works across Claude Code, Codex, and Gemini.

When to Use This Skill

Activate this skill when the user wants to:

Create a reusable AI assistant package
Build a shareable configuration for Claude, Codex, or Gemini
Set up a package with skills, agents, and MCP servers
Create dynamic templates using askUser and askAgent
Understand Terrazul package structure and best practices

Related Skills

This skill works best in combination with:

| Skill | Use For | |-------|---------| | create-skill | Creating individual skills within the package | | add-mcp | Finding and configuring MCP servers for the package | | create-agent | Creating Claude agents for the package | | create-command | Creating slash commands for Claude |

When building a full-featured assistant package, use these skills to create the individual components after setting up the package structure.

Terrazul Package Overview

A Terrazul package is a distributable unit containing:

Configuration manifest (agents.toml) - package metadata and exports
Context templates (.md.hbs or .md) - documentation for AI tools
Operational files - skills, agents, commands, MCP configs
Dynamic content - interactive prompts and AI-generated content

Package Creation Workflow

1. Gather Requirements

Ask the user:

What is the purpose of this assistant package?
Which AI tools should it support? (Claude, Codex, Gemini)
What skills/capabilities should it provide?
Does it need MCP server integrations?
Should content be dynamic (using askUser/askAgent)?

2. Create Directory Structure

Create the package directory with this structure:

my-package/
├── agents.toml              # REQUIRED: Package manifest
├── README.md                # RECOMMENDED: Documentation
├── templates/               # Template files
│   ├── CLAUDE.md.hbs        # Claude context (or .md if no dynamic content)
│   ├── AGENTS.md.hbs        # Codex context
│   ├── GEMINI.md.hbs        # Gemini context
│   ├── claude/              # Claude-specific files
│   │   ├── mcp_servers.json.hbs
│   │   ├── skills/
│   │   │   └── [skill-name]/
│   │   │       └── SKILL.md
│   │   ├── agents/
│   │   │   └── [agent-name].md
│   │   └── commands/
│   │       └── [command-name].md
│   ├── codex/               # Codex-specific files
│   │   └── config.toml.hbs
│   └── gemini/              # Gemini-specific files
│       ├── settings.json.hbs
│       └── commands/
│           └── [command-name].toml
└── prompts/                 # Optional: External prompt files for askAgent
    └── analyze.txt

Required vs Optional Components:

| Component | Status | Purpose | |-----------|--------|---------| | agents.toml | Required | Package manifest | | README.md | Recommended | Package documentation | | templates/ | Recommended | All template files | | Context templates | Optional | CLAUDE.md, AGENTS.md, GEMINI.md | | templates/claude/skills/ | Optional | Claude skills | | templates/claude/agents/ | Optional | Claude agents | | templates/claude/commands/ | Optional | Claude commands | | prompts/ | Optional | External askAgent prompts |

3. Create agents.toml Manifest

The manifest defines package metadata and exports:

[package]
name = "@owner/package-name"           # Required for publish
version = "1.0.0"                      # Required for publish
description = "Brief package description"
repository = "https://github.com/..."
license = "MIT"
keywords = ["ai-assistant", "claude", "codex"]
authors = ["Name <email@example.com>"]

[compatibility]
claude = ">=0.2.0"
codex = "*"
gemini = "*"

[exports.claude]
template = "templates/CLAUDE.md.hbs"
skillsDir = "templates/claude/skills"
agentsDir = "templates/claude/agents"
commandsDir = "templates/claude/commands"
mcpServers = "templates/claude/mcp_servers.json.hbs"

[exports.codex]
template = "templates/AGENTS.md.hbs"
skillsDir = "templates/claude/skills"

[exports.gemini]
template = "templates/GEMINI.md.hbs"
skillsDir = "templates/claude/skills"
commandsDir = "templates/gemini/commands"
mcpServers = "templates/gemini/settings.json.hbs"

Manifest Rules:

name format: @scope/package-name (lowercase, hyphens allowed)
version must be valid semver
All paths in [exports] must be relative to package root
Tool keys: claude, codex, gemini, cursor, copilot

4. Create Context Templates

Context templates provide instructions to the AI tool. Use .hbs extension for dynamic content, .md for static.

Static template (CLAUDE.md):

# Package Name

This package provides [description].

## Available Skills

| Skill | Description |
|-------|-------------|
| `skill-name` | Brief description |

## Quick Start

[Usage instructions]

Dynamic template (CLAUDE.md.hbs):

{{~ var projectInfo = askAgent("""
Analyze this repository and return:
{
  "name": "repository name",
  "description": "brief description",
  "languages": "primary languages used"
}
""", { json: true }) ~}}

# {{ vars.projectInfo.name }}

{{ vars.projectInfo.description }}

## Tech Stack
Languages: {{ vars.projectInfo.languages }}

5. Add Dynamic Content with askUser/askAgent

askUser - Interactive Prompts

Gather information from users during package rendering:

{{~ var projectPitch = askUser('Describe your project in 1-2 sentences.') ~}}
{{~ var targetAudience = askUser('Who is the primary user of this assistant?') ~}}
{{~ var constraints = askUser('List any constraints or guardrails.', {
  default: 'None',
  placeholder: 'Enter constraints or press Enter for none'
}) ~}}

# Project Overview

{{ vars.projectPitch }}

**Primary User**: {{ vars.targetAudience }}

**Constraints**: {{ vars.constraints }}

askUser Options:

default - Default value if user presses Enter
placeholder - Hint text shown when empty

askAgent - AI-Powered Analysis

Generate content using AI analysis of the codebase:

{{~ var analysis = askAgent("""
Analyze this repository structure and provide:
{
  "mainDirectories": "key directories and their purposes",
  "buildTools": "build tools used",
  "testFramework": "testing framework if present"
}
""", { json: true }) ~}}

## Repository Structure

{{ vars.analysis.mainDirectories }}

## Development

Build: {{ vars.analysis.buildTools }}
Tests: {{ vars.analysis.testFramework }}

askAgent Options:

json: true - Expect JSON response
tool: 'claude' - Specify AI tool
systemPrompt: 'custom prompt' - Override system prompt
timeoutMs: 60000 - Custom timeout

IMPORTANT Best Practice: Use ONE comprehensive askAgent call with flat JSON instead of multiple sequential calls:

{{~ var projectData = askAgent("""
Analyze this repository and return a flat JSON object:
{
  "name": "repository name",
  "description": "brief description",
  "languages": "TypeScript, Python",
  "frameworks": "Next.js, FastAPI",
  "directories": "src: source code, tests: test files"
}
""", { json: true }) ~}}

This is more efficient and produces more coherent results than multiple separate calls.

6. Create Skills (Optional)

TIP: Use the create-skill skill for detailed guidance on creating skills. It provides templates, validation checklists, and best practices for different skill types.

Add skills in templates/claude/skills/[skill-name]/SKILL.md:

---
name: skill-name
description: Third-person description of what this skill does and when to use it
---

# Skill Title

[Overview of what this skill provides]

## When to Use

Activate this skill when:
- [Trigger condition 1]
- [Trigger condition 2]

## Instructions

[Specific instructions for Claude to follow]

## Examples

[Concrete usage examples]

7. Create Agents (Optional)

Add Claude agents in templates/claude/agents/[agent-name].md:

---
name: agent-name
description: What this agent does
model: sonnet
color: blue
tools:
  - Read
  - Grep
  - Glob
  - Edit
examples:
  - "Review this PR for security issues"
  - "Analyze the architecture"
---

You are a specialized agent for [purpose].

## Your Role

[Agent's responsibilities]

## Guidelines

[Specific instructions for the agent]

8. Configure MCP Servers (Optional)

TIP: Use the add-mcp skill to search mcp.so for servers, get configuration details, and properly set up MCP integrations. It handles searching, fetching server details, and generating correct configurations.

Add MCP configuration in templates/claude/mcp_servers.json.hbs:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"]
    }
  }
}

CRITICAL REQUIREMENT: Include setup-mcp Command

Every package with MCP servers MUST include the setup-mcp command. This is not optional.

When the package includes MCP server configuration:

Copy the setup-mcp command to templates/claude/commands/setup-mcp.md
Copy the Gemini version to templates/gemini/commands/setup-mcp.toml

Update README.md to include post-installation section:

## Setup Required

After installing, configure MCP credentials:

/setup-mcp

Update CLAUDE.md to list the MCP servers and note that /setup-mcp must be run

The setup-mcp command guides users through setting up environment variables in their shell profile (~/.zshenv, ~/.bashrc) so MCP servers can authenticate with external services.

9. Write README.md

Document the package for users:

# @owner/package-name

Brief description of what this package provides.

## Features

- Feature 1
- Feature 2

## Installation

\`\`\`bash
tz add @owner/package-name
tz apply
\`\`\`

## Usage

[How to use the package]

## Configuration

[Any configuration needed]

## License

MIT

10. Validate Package

Before publishing, validate the package:

# Check structure and manifest
tz validate

# Test rendering locally
tz run --force

# Verify generated files
ls -la agent_modules/@owner/package-name/

Validation Checklist

Before considering the package complete:

[ ] agents.toml has valid name and version
[ ] All template paths in [exports] exist
[ ] Context templates render without errors
[ ] Skills have valid frontmatter (name, description)
[ ] Agents have valid frontmatter (name, description, model)
[ ] MCP configs have valid JSON/TOML syntax
[ ] README.md documents installation and usage
[ ] Package works with tz apply --force
[ ] If MCP servers configured → setup-mcp.md exists in templates/claude/commands/
[ ] If MCP servers configured → setup-mcp.toml exists in templates/gemini/commands/
[ ] If MCP servers configured → README mentions /setup-mcp in post-installation steps
[ ] If MCP servers configured → CLAUDE.md documents required credentials

Common Patterns

Documentation-Focused Package

For packages that primarily provide context and guidelines:

my-docs-package/
├── agents.toml
├── README.md
└── templates/
    ├── CLAUDE.md.hbs      # Dynamic analysis of codebase
    ├── AGENTS.md           # Static codex docs
    └── claude/
        └── skills/
            └── guidelines/
                └── SKILL.md

Skills-Focused Package

For packages that add capabilities:

my-skills-package/
├── agents.toml
├── README.md
└── templates/
    ├── CLAUDE.md
    └── claude/
        └── skills/
            ├── skill-1/
            │   ├── SKILL.md
            │   ├── reference.md
            │   └── examples.md
            └── skill-2/
                └── SKILL.md

Full-Featured Package

For comprehensive packages:

my-full-package/
├── agents.toml
├── README.md
├── prompts/
│   └── analyze.txt
└── templates/
    ├── CLAUDE.md.hbs
    ├── AGENTS.md.hbs
    ├── GEMINI.md.hbs
    ├── claude/
    │   ├── mcp_servers.json.hbs
    │   ├── skills/
    │   ├── agents/
    │   └── commands/
    ├── codex/
    │   └── config.toml.hbs
    └── gemini/
        ├── settings.json.hbs
        └── commands/

Tips for Effective Packages

Start Simple: Begin with agents.toml and one context template
Use Dynamic Content Wisely: askAgent is expensive; use sparingly
Flat JSON Only: Always request flat JSON structures from askAgent
One Comprehensive Call: Prefer single askAgent with multiple fields over multiple calls
Cache-Friendly Prompts: Design stable prompts for better caching
Platform-Agnostic Skills: Write skills that work across tools when possible
Document Everything: Good README and context files save user time
Test Before Publishing: Run tz validate and tz apply --force
Use Related Skills: Leverage create-skill for skill creation, add-mcp for MCP configuration, and create-agent for agent definitions

Working with PDF Context

Assistants are often given PDFs for context (documentation, specifications, guidelines). Large PDFs can hit token limits when read directly.

Best Practice: Use pdftotext to convert PDFs to plain text:

# Convert PDF to text
pdftotext input.pdf output.txt

# Convert with layout preservation
pdftotext -layout input.pdf output.txt

Use the converted text however is appropriate for your use case. This avoids token limits and makes the content more accessible to the AI tool.

Reference Materials

For detailed information:

reference.md - Complete manifest and template reference
examples.md - Real-world package examples
templates/ - Starter templates for different package types