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:

create-skill

add-mcp

create-agent

create-command

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:

agents.toml

README.md

templates/

templates/claude/skills/

templates/claude/agents/

templates/claude/commands/

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

.md

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

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

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

When the package includes MCP server configuration:

1. Copy the setup-mcp command to

   templates/claude/commands/setup-mcp.md

2. Copy the Gemini version to

   templates/gemini/commands/setup-mcp.toml

3. Update README.md to include post-installation section:

   ## Setup Required
   
   After installing, configure MCP credentials:
   

   /setup-mcp

4. Update CLAUDE.md to list the MCP servers and note that

   /setup-mcp

   must be run

The

setup-mcp

~/.zshenv

~/.bashrc

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

1. Start Simple: Begin with

   agents.toml

   and one context template
2. Use Dynamic Content Wisely:

   askAgent

   is expensive; use sparingly
3. Flat JSON Only: Always request flat JSON structures from

   askAgent

4. One Comprehensive Call: Prefer single

   askAgent

   with multiple fields over multiple calls
5. Cache-Friendly Prompts: Design stable prompts for better caching
6. Platform-Agnostic Skills: Write skills that work across tools when possible
7. Document Everything: Good README and context files save user time
8. Test Before Publishing: Run

   tz validate

   and

   tz apply --force

9. 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

# 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