Instruction Types

The instruction system in ChatBotKit provides a sophisticated mechanism for defining how agents interpret and respond to user input. Instructions can take several forms, each optimized for different use cases and complexity levels. Understanding these instruction types is essential for building effective skillsets and abilities.

Understanding Instruction Types

ChatBotKit supports three primary instruction types, each serving a specific purpose in the instruction processing pipeline:

1. Template Instructions - Pre-defined, reusable instruction templates
2. Simple Instructions - Single-action instructions with parameter substitution
3. Complex Instructions - Multi-action instructions combining text and actions

The platform automatically detects which type of instruction is being used based on its structure and content, allowing for seamless integration of different instruction patterns within the same skillset.

Template Instructions

Template instructions are pre-defined patterns that can be referenced by name and configured with parameters. These provide the highest level of reusability and consistency across your skillsets.

A template instruction is identified by either:

• A single line starting with @ (e.g., @google/calendar/search)
• A YAML document containing a template key

Skillset Role: Templates serve as building blocks for creating sophisticated abilities without writing low-level action code. They encapsulate best practices and tested patterns for common operations.

Ability Category: Templates enable rapid ability creation by providing pre-configured actions for services like Google Calendar, Notion, Slack, and more.

Simple Instructions

Simple instructions consist of a single action block with no additional text content. These are ideal for straightforward operations that map directly to a single action type.

A simple instruction contains exactly one action block and no surrounding text:

The system automatically extracts parameters from the instruction using field notation ($[param] or ((param))), and can use AI to infer missing required parameters from user input.

Skillset Role: Simple instructions provide clear, focused actions that are easy to understand and maintain. They're perfect for abilities that perform a single, well-defined task.

Ability Category: Simple instructions enable actions like fetching data, searching datasets, sending emails, or generating content with a single, straightforward operation.

Complex Instructions

Complex instructions combine multiple action blocks with descriptive text, allowing for rich, context-aware behaviors. These instructions can include explanatory text alongside action definitions.

A complex instruction is detected when:

• Multiple action blocks are present, or
• Text content exists alongside action blocks

Example:

Skillset Role: Complex instructions enable sophisticated multi-step workflows that combine different actions in a coherent sequence, with contextual guidance for the AI agent.

Ability Category: Complex instructions support advanced capabilities like multi-step data processing, conditional workflows, and orchestrated operations across multiple services.

Type Detection Process

The instruction type is automatically detected using the following logic:

1. Check for Template - Does it start with @ or contain a template key?
2. Check for Complex - Does it have multiple actions or text with actions?
3. Check for Simple - Does it have exactly one action and no text?

This automatic detection allows you to focus on writing effective instructions without worrying about explicit type declarations.

Choosing the Right Instruction Type

Use Template Instructions when:

• Working with common, well-established patterns
• You want maximum reusability across multiple abilities
• Integration with third-party services follows standard patterns

Use Simple Instructions when:

• You need a single, focused action
• The operation maps directly to one action type
• You want clear, maintainable ability definitions

Use Complex Instructions when:

• Multiple actions need to work together
• Context and explanation enhance the agent's understanding
• You're orchestrating multi-step workflows

Integration with Skillsets and Abilities

Instructions form the core of ability definitions within skillsets. Each ability's instruction field determines how the agent executes that capability when triggered by user intent.

The instruction type affects:

• Token usage - Templates and simple instructions are more token-efficient
• Processing complexity - Complex instructions require more AI interpretation
• Maintenance - Templates and simple instructions are easier to update
• Flexibility - Complex instructions offer more contextual adaptability

Simple Instructions: Parameter Substitution

Simple instructions represent the most straightforward instruction pattern in ChatBotKit, consisting of a single action block with parameter placeholders that are automatically populated from user input. This type provides a clean, efficient way to create abilities that perform focused, single-action operations.

How Simple Instructions Work

A simple instruction is automatically detected when it contains:

• Exactly one action block (like fetch, search, email, etc.)
• No additional text content outside the action block

When a simple instruction is processed, the system:

1. Extracts Parameters - Identifies all field placeholders in the instruction
2. Parses User Input - Attempts to parse the input as YAML/JSON for structured data
3. Identifies Missing Fields - Compares expected parameters with provided input
4. Uses AI for Extraction - If required fields are missing, uses an LLM to extract them from natural language input
5. Substitutes Parameters - Replaces all placeholders with actual values

Parameter Field Notation

Simple instructions support multiple field bracket types for different purposes:

Square Brackets $[param] - AI-populated fields These fields are intended to be filled by the AI agent based on user input:

Curly Brackets ${SECRET_NAME} - Secret and metadata references These reference secrets or conversation metadata:

Round Brackets ((param)) - User-provided or template parameters These are expected from structured input or template invocations:

Required vs Optional Parameters

Parameters can be marked as required using the ! modifier:

• $[query! ys|description] - Required field, must be provided or extracted
• $[limit ys|description] - Optional field, can be omitted

When required fields are missing, the system automatically invokes an LLM to extract them from the user's natural language input. This provides a seamless experience where users don't need to provide structured data.

Practical Examples

Example 1: Fetching Weather Data

When a user says "What's the weather in Paris?", the system:

1. Detects this as a simple instruction (one action, no text)
2. Identifies location as a required parameter
3. Uses AI to extract "Paris" from the user input
4. Substitutes to create: GET https://wttr.in/Paris?format=4

Example 2: Searching a Dataset

This instruction:

• Requires datasetId from structured input (template parameter)
• Extracts query from natural language user input
• Combines both to perform the search operation

Example 3: Sending an Email

This demonstrates mixing all three parameter types:

• recipientEmail from template parameters
• USER_EMAIL from secrets/metadata
• subject and emailBody extracted from user input

Skillset and Ability Context

Skillset Role: Simple instructions provide the foundation for creating clean, maintainable abilities that perform specific tasks. They're ideal for building comprehensive skillsets where each ability has a clear, focused purpose.

Ability Category: Simple instructions enable a wide range of capabilities:

• Data Retrieval - Fetching information from APIs
• Search Operations - Querying datasets or external search engines
• Communication - Sending emails or messages
• Content Generation - Creating text or images with AI models

Performance Characteristics

Simple instructions are highly efficient:

• Token Usage - Minimal token consumption for parameter extraction
• Processing Speed - Fast transformation with predictable behavior
• Maintainability - Easy to understand and update

When no required fields are missing, no AI calls are made at all, making the transformation instantaneous. When AI extraction is needed, only the missing fields are extracted, minimizing token usage.

Best Practices

1. Use descriptive field names that clearly indicate their purpose
2. Include helpful descriptions after the pipe | to guide AI extraction
3. Mark required fields with ! to ensure they're always provided
4. Choose appropriate bracket types based on the parameter source
5. Keep instructions focused on a single action for maximum clarity
6. Test with natural language input to verify AI extraction works as expected

Warning: Field descriptions contribute to token usage during AI extraction. Balance descriptiveness with brevity to maintain efficient processing.

Complex Instructions: Multi-Action Orchestration

Complex instructions enable sophisticated agent behaviors by combining multiple action blocks with descriptive text, creating rich, context-aware workflows that guide the AI agent through multi-step operations. This instruction type provides the highest level of flexibility and expressiveness for advanced use cases.

How Complex Instructions Work

A complex instruction is automatically detected when:

• Multiple action blocks are present in the instruction, or
• Text content exists alongside one or more action blocks

When a complex instruction is processed, the system:

1. Analyzes Structure - Identifies all action blocks and text content
2. Simplifies Fields - Removes operand details and descriptions from parameters
3. Invokes AI Transformation - Uses an LLM to adapt the instruction based on user input
4. Returns Transformed Instruction - Provides a fully contextualized instruction ready for execution

Unlike simple instructions that use deterministic parameter substitution, complex instructions leverage AI to intelligently interpret and adapt the entire instruction based on the context of the user's request.

Structure of Complex Instructions

Complex instructions combine three key elements:

1. Descriptive Text - Provides context and guidance

2. Action Blocks - Define specific operations

3. Sequential Flow - Orders operations logically

AI-Powered Transformation

Complex instructions undergo AI-powered transformation using a specialized prompt template. This transformation:

• Contextualizes Actions - Adapts actions based on user input context
• Resolves Parameters - Intelligently fills in parameter values
• Maintains Structure - Preserves action block syntax while adapting content
• Handles Complexity - Manages interactions between multiple actions

The AI receives:

• A list of available action types (fetch, search, email, etc.)
• The simplified instruction with parameter placeholders
• The user's input or request

It returns a fully populated instruction ready for execution.

Practical Examples

Example 1: Multi-Step Data Processing

Example 2: Conditional Workflow

Example 3: Integration Orchestration

Skillset and Ability Context

Skillset Role: Complex instructions enable sophisticated abilities that handle nuanced, multi-step workflows. They're essential for building advanced skillsets that go beyond simple command-response patterns to create truly intelligent agent behaviors.

Ability Category: Complex instructions support advanced capabilities:

• Multi-Step Workflows - Orchestrating sequences of operations
• Conditional Logic - Adapting behavior based on intermediate results
• Data Transformation Pipelines - Processing data through multiple stages
• Integration Choreography - Coordinating multiple service interactions
• Context-Aware Operations - Leveraging conversational context throughout the workflow

Parameter Handling

Complex instructions support all three field bracket types, but handle them differently than simple instructions:

• Field Simplification - Parameter descriptions and operands are simplified before AI processing
• AI-Driven Population - The AI determines appropriate values based on context
• Flexible Interpretation - The AI can adapt parameter usage based on the situation

This flexibility allows complex instructions to handle ambiguous or incomplete user input more gracefully than simple instructions.

Performance Considerations

Complex instructions have different performance characteristics:

• Higher Token Usage - AI transformation requires more tokens
• Increased Latency - Additional AI call adds processing time
• Greater Flexibility - Handles more varied input patterns
• Enhanced Context Awareness - Better adapts to conversational context

Best Practice: Use complex instructions when the added flexibility justifies the performance cost. For straightforward operations, prefer simple instructions.

Best Practices

1. Provide Clear Context - Text descriptions guide AI interpretation
2. Order Actions Logically - Structure flows from general to specific
3. Explain Dependencies - Clarify how actions relate to each other
4. Use Descriptive Variables - Help AI understand parameter purposes
5. Consider Token Efficiency - Balance detail with brevity
6. Test with Varied Input - Verify AI handles different phrasings
7. Document Expectations - Include notes about expected behavior

When to Use Complex Instructions

Choose complex instructions when:

• Multiple actions need to work together sequentially
• Context and explanation enhance agent understanding
• Conditional logic or decision-making is required
• The workflow adapts based on intermediate results
• Rich, natural language guidance adds value

Avoid complex instructions when:

• A single action suffices (use simple instructions)
• A standard pattern exists (use template instructions)
• Token efficiency is critical
• Deterministic behavior is required

Warning: Complex instructions rely on AI transformation, which can introduce variability in behavior. For critical operations requiring consistent, predictable behavior, consider using simple or template instructions.

Template Instructions: Reusable Patterns

Template instructions provide the highest level of abstraction and reusability in the ChatBotKit instruction system. They allow you to reference pre-defined, tested instruction patterns by name and configure them with parameters, enabling rapid ability creation and ensuring consistency across your skillsets.

How Template Instructions Work

A template instruction is automatically detected when:

• It starts with @ followed by a template identifier (e.g., @google/calendar/search)
• It's a YAML document containing a template key

When a template instruction is processed, the system:

1. Parses Template Reference - Extracts the template ID and parameters
2. Unpacks Template - Retrieves the full instruction definition from the catalog
3. Substitutes Parameters - Replaces parameter placeholders with provided values
4. Detects Instruction Type - Determines if the resulting instruction is simple, complex, or automatic
5. Transforms Accordingly - Processes the instruction using the appropriate handler

Templates act as instruction generators, producing complete instructions that are then processed through the normal instruction pipeline.

Template Reference Syntax

Single-Line Format (for templates without parameters):