Writing the Manifest

The manifest defines what your Trik can do and how it communicates with agents.

Complete Examples

Conversational Mode

Here’s the manifest for an article search trik that uses LLM-powered conversations:


{
  "schemaVersion": 2,
  "id": "article-search",
  "name": "Article Search",
  "description": "Search and retrieve articles with session support.",
  "version": "2.0.0",
 
  "agent": {
    "mode": "conversational",
    "handoffDescription": "An article search assistant that helps users find and explore articles by topic. Supports multi-turn conversations for searching, browsing results, and reading article details.",
    "systemPromptFile": "./system-prompt.md",
    "domain": ["articles", "search", "content discovery"],
    "model": {
      "provider": "anthropic",
      "capabilities": ["tool_use"],
      "temperature": 0.3
    }
  },
 
  "tools": {
    "search": {
      "description": "Search for articles by topic",
      "logTemplate": "Searched for '{{topic}}' — found {{count}} results",
      "logSchema": {
        "topic": { "type": "string", "enum": ["AI", "technology", "science", "health"] },
        "count": { "type": "integer", "minimum": 0, "maximum": 100 }
      }
    },
    "getDetails": {
      "description": "Get full article details by ID",
      "logTemplate": "Retrieved article {{articleId}}",
      "logSchema": {
        "articleId": { "type": "string", "pattern": "^art-[0-9]+$" }
      }
    }
  },
 
  "capabilities": {
    "session": {
      "enabled": true,
      "maxDurationMs": 1800000
    }
  },
 
  "limits": {
    "maxTurnTimeMs": 15000
  },
 
  "entry": {
    "module": "./dist/index.js",
    "export": "agent"
  },
 
  "config": {
    "required": [
      { "key": "ANTHROPIC_API_KEY", "description": "Anthropic API key for the agent's LLM" }
    ]
  }
}

Tool Mode

Here’s the manifest for a hash utility trik that exposes native tools to the main agent:


{
  "schemaVersion": 2,
  "id": "hash-utils",
  "name": "Hash Utilities",
  "description": "Compute hashes for text inputs.",
  "version": "1.0.0",
 
  "agent": {
    "mode": "tool",
    "domain": ["cryptography", "utilities", "hashing"]
  },
 
  "tools": {
    "computeHash": {
      "description": "Compute a cryptographic hash of the given text",
      "inputSchema": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "description": "The text to hash",
            "minLength": 1
          },
          "algorithm": {
            "type": "string",
            "description": "Hash algorithm to use",
            "enum": ["sha256", "sha512", "md5"]
          }
        },
        "required": ["text", "algorithm"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "hash": { "type": "string" },
          "algorithm": { "type": "string", "enum": ["sha256", "sha512", "md5"] },
          "inputLength": { "type": "integer", "minimum": 0 }
        },
        "required": ["hash", "algorithm", "inputLength"]
      },
      "outputTemplate": "Computed {{algorithm}} hash (input: {{inputLength}} chars): {{hash}}"
    }
  },
 
  "limits": {
    "maxTurnTimeMs": 5000
  },
 
  "entry": {
    "module": "./dist/index.js",
    "export": "agent"
  }
}

Step-by-Step Guide

1. Identity


{
  "schemaVersion": 2,
  "id": "my-trik",
  "name": "Human Readable Name",
  "description": "One sentence description.",
  "version": "1.0.0"
}

schemaVersion must be 2 for v2 manifests.

ID format: Lowercase alphanumeric + hyphens (e.g., my-trik). When published, the registry derives the scoped name (@publisher/my-trik) from your verified GitHub repo ownership.

2. Agent Block

The agent block defines how your trik operates:

Conversational mode — an LLM agent that receives the conversation via handoff:


{
  "agent": {
    "mode": "conversational",
    "handoffDescription": "A helpful assistant that does X, Y, and Z. Handles multi-turn conversations about...",
    "systemPromptFile": "./system-prompt.md",
    "domain": ["topic-a", "topic-b"],
    "model": {
      "provider": "anthropic",
      "capabilities": ["tool_use"],
      "temperature": 0.3
    }
  }
}

Tool mode — exports native tools that the main agent calls directly (no handoff, no session):


{
  "agent": {
    "mode": "tool",
    "domain": ["utilities", "computation"]
  }
}

Field	Required	Description
`mode`	Yes	`"conversational"` or `"tool"`
`handoffDescription`	Conversational only	Description used to generate the handoff tool for the main agent. Write it as if explaining to another AI what this agent can help with.
`systemPrompt`	No	Inline system prompt (alternative to `systemPromptFile`)
`systemPromptFile`	No	Path to system prompt file, relative to manifest
`domain`	Yes	String array of domain tags describing the agent’s expertise
`model`	No	LLM preferences: `provider`, `capabilities`, `temperature`

Tip: Write handoffDescription as a clear, detailed summary of what the agent can do. The main agent uses this to decide when to hand off. Aim for 1-3 sentences.

3. Tools Block

The tools block declares the tools your trik uses. The structure differs by mode.

Conversational mode tools — metadata for logging and quality scoring. The actual tool schemas live in your code (Zod schemas, LangChain tools):


{
  "tools": {
    "search": {
      "description": "Search for articles by topic",
      "logTemplate": "Searched for '{{topic}}' — found {{count}} results",
      "logSchema": {
        "topic": { "type": "string", "enum": ["AI", "technology", "science"] },
        "count": { "type": "integer", "minimum": 0 }
      }
    }
  }
}

Tool mode tools — the full runtime contract. inputSchema, outputSchema, and outputTemplate are required:


{
  "tools": {
    "computeHash": {
      "description": "Compute a cryptographic hash",
      "inputSchema": {
        "type": "object",
        "properties": {
          "text": { "type": "string", "minLength": 1 },
          "algorithm": { "type": "string", "enum": ["sha256", "sha512", "md5"] }
        },
        "required": ["text", "algorithm"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "hash": { "type": "string" },
          "algorithm": { "type": "string", "enum": ["sha256", "sha512", "md5"] }
        },
        "required": ["hash", "algorithm"]
      },
      "outputTemplate": "Computed {{algorithm}} hash: {{hash}}"
    }
  }
}

The outputTemplate defines what the main agent sees after a tool call. Only reference fields from outputSchema as {{placeholders}}.

4. Capabilities


{
  "capabilities": {
    "session": {
      "enabled": true,
      "maxDurationMs": 1800000
    },
    "storage": {
      "enabled": true,
      "maxSizeBytes": 104857600,
      "persistent": true
    }
  }
}

Capability	Description
`session.enabled`	Enable multi-turn session state (conversational mode)
`session.maxDurationMs`	Maximum session duration (default: 30 minutes)
`storage.enabled`	Enable persistent key-value storage
`storage.maxSizeBytes`	Maximum storage size (default: 100MB)
`storage.persistent`	Whether storage persists across sessions (default: true)

Capability Enforcement: Capabilities declared here are cross-checked against your source code at publish time. If your code uses storage, filesystem, process/shell, or trikManagement APIs without declaring the corresponding capability, trik publish will block. Run trik lint . to check for mismatches before publishing.

5. Limits


{
  "limits": {
    "maxTurnTimeMs": 15000
  }
}

maxTurnTimeMs sets the maximum time allowed per turn. The gateway enforces this timeout.

6. Entry Point


{
  "entry": {
    "module": "./dist/index.js",
    "export": "agent"
  }
}

Field	Description
`module`	Path to the compiled JavaScript file (relative to the manifest)
`export`	The named export to use (typically `"agent"`)
`runtime`	Optional: `"node"` (default) or `"python"`

7. Configuration Requirements

Declare required configuration values (API keys, tokens):


{
  "config": {
    "required": [
      { "key": "ANTHROPIC_API_KEY", "description": "Anthropic API key for the agent's LLM" }
    ],
    "optional": [
      { "key": "WEBHOOK_URL", "description": "Optional webhook URL", "default": "" }
    ]
  }
}

The gateway validates that required config values are set before executing the trik. Users set config values via trik config set <trik-id> <KEY> <VALUE>.

Schema Design Tips

Use Constrained Types (TDPS)

The Typed Data Passing Standard (TDPS) ensures that all data flowing between triks and agents is safe and predictable. Use constrained types — enums, bounded numbers, patterns — instead of free-form strings.


// Good: constrained values
"status": {
  "type": "string",
  "enum": ["success", "pending", "error"]
}
 
// Bad: free-form string
"status": { "type": "string" }

Provide Descriptions


"topic": {
  "type": "string",
  "description": "The topic to search for. Examples: 'machine learning', 'climate change'",
  "minLength": 2
}

Use Appropriate Types


// Counts
"resultCount": { "type": "integer", "minimum": 0 }
 
// IDs
"articleId": { "type": "string", "pattern": "^art-[0-9]+$" }
 
// Booleans
"isAvailable": { "type": "boolean" }

outputTemplate Best Practices (Tool Mode)

The outputTemplate is what the main agent sees. Keep it concise and informative:


// Good: tells the agent what happened
"outputTemplate": "Found {{count}} articles about {{topic}}"
 
// Bad: too verbose or includes raw data
"outputTemplate": "The search operation completed successfully. Results: {{rawJson}}"

Only reference fields that exist in outputSchema. The gateway fills {{placeholders}} with validated output values.

Validation

Validate your manifest before publishing:


# Lint the manifest and project structure
trik lint .

The linter checks schema version, required fields, TDPS compliance, entry point validity, and mode-specific requirements (e.g., handoffDescription for conversational, outputTemplate for tool mode).

Specific TDPS rules:

tdps-agent-safe-output — outputSchema strings must use enum, format, or pattern
tdps-constrained-log — logSchema strings must have at least one constraint
tdps-log-template — logTemplate placeholders must match logSchema fields
tdps-output-template — outputTemplate placeholders must match outputSchema fields

Next: Learn about Building the Agent.