Manifests are the core of how yafai-skills enables Large Language Models (LLMs) to interact with external tools and services.

They act as comprehensive blueprints, defining what a tool can do, how to use it, and what kind of responses to expect.

What is a Skills Manifest?

Think of a Manifest as a user manual for a specific tool or API, written in a machine-readable format (YAML).
It provides your LLM with all the necessary instructions to:
- Understand a tool’s capabilities: What actions can it perform?
- Learn how to use it: What inputs does each action require?
- Interpret results: How should it understand successful responses and errors?
- By providing these manifests, yafai-skills allows LLMs to go beyond just generating text, enabling them to execute real-world actions like sending emails, querying databases, or managing tasks.

Anatomy of a Skills Manifest

Action Manifests are defined in YAML files and follow a clear, hierarchical structure.

Basic Structure

name: [Service Name] # A human-readable name for your tool/service
description: [Brief description of the service and its purpose] # What does this tool do?
auth_header: "[Authorization|Bearer|API-Key|Custom]" # How to authenticate with the service (e.g., Bearer token, API-Key)
actions: # A list of specific operations this tool can perform
  [ActionName]: # A unique, descriptive name for a single action (e.g., 'send_email', 'get_weather')
    method: [HTTP_METHOD] # The HTTP method (GET, POST, PUT, DELETE, etc.)
    headers: # Optional: Custom headers required for this action
      Content-Type: application/json
      [Optional-Header-Name]: [Optional-Header-Value]
    base_url: "[https://api.example.com/resource/path]" # The specific endpoint for this action
    params: # The input parameters required for this action
      - name: [param_name] # Name of the parameter (e.g., 'query', 'user_id')
        type: [string|integer|boolean|array|object] # Data type (see "Parameter Types" below)
        in: [path|query|body|header] # Where the parameter is sent (URL path, query string, request body, header)
        description: [Parameter description] # What this parameter is for
        required: [true|false] # Is this parameter mandatory?
        # Optional: 'enum' or 'items' or 'properties' for complex types (explained below)
    desc: | # A concise description of what this specific action does (crucial for LLM understanding)
      [Describe what this action does in one or two lines.]
    response_template: # How to format the LLM's understanding of success/failure
      success: |
        Success response:
        {{range .results}}
        - ID: {{.id}}
        - Example Field: {{.example_field}}
        {{end}}
      failure: |
        Failed to perform action:
        - Error: {{.error.message}}

Defining Parameters

Parameters are the inputs an action needs. yafai-skills supports various data types to accurately represent your API’s requirements.

Simple Parameter Types

These are straightforward individual values like below,

string: Text (e.g., “hello world”)

integer: Whole numbers (e.g., 123)

boolean: True/False values (e.g., true, false)

Simple Parameters

params:
  - name: user_id
    type: integer
    in: path
    description: Unique identifier of the user.
    required: true
  - name: active_only
    type: boolean
    in: query
    description: Filter for active users.
    required: false

Complex Parameter Types

These allow for structured data inputs like Arrays, Objects, Nested Arrays/Objects etc.

Object (Structured Data Group)

An object parameter groups several related pieces of information, much like a form with multiple fields.Use properties to define the individual fields (and their types, descriptions, and whether they are required) within the object.Objects are typically sent in the body of a POST or PUT request.

params:
  - name: user_details # Our object parameter
    type: object
    in: body
    description: Detailed information about the user.
    required: true
    properties: # Defines fields within 'user_details' as a list
      - name: first_name
        type: string
        description: User's first name.
        required: true
      - name: last_name
        type: string
        description: User's last name.
        required: true
      - name: email
        type: string
        format: email # Optional: semantic hint for email format
        description: User's email address.
        required: false

Array (List of Items)

An array parameter represents a list of items of the same type.Use items to describe the data type of each element within the array.The items can be simple types (like string, integer) or even complex types (object).

params:
  - name: product_ids # Our array parameter
    type: array
    in: query # Arrays of simple types often in query
    description: A list of product IDs to retrieve.
    required: true
    items: # Each item in items can param with its own param defintion 'product_ids' is an integer
      - type: integer

Nested objects and arrays

You can combine object and array types to define more complex data structures.Array of Objects: A list where each item in the list is itself a structured object.

params:
  - name: new_employees # An array of objects
    type: array
    in: body
    description: A list of new employees to onboard.
    required: true
    items: # Direct list of properties for EACH object in the array
      - name: employee_id
        type: string
        description: Unique ID of the employee.
        required: true
      - name: name
        type: string
        description: Full name of the employee.
        required: true
      - name: department
        type: string
        description: Department the employee belongs to.
        required: false

Object with Nested Object

An object containing another object as one of its fields.

params:
  - name: order_request # Our main object
    type: object
    in: body
    description: Details for a new order.
    required: true
    properties: # Fields for 'order_request'
      - name: order_id
        type: string
        description: Unique identifier for the order.
        required: true
      - name: quantity
        type: integer
        description: Number of items in the order.
        required: true
      - name: shipping_address # A nested object
        type: object
        description: The delivery address for the order.
        required: true
        properties: # Fields for 'shipping_address', defined as a list
          - name: street
            type: string
            description: Street address.
            required: true
          - name: city
            type: string
            description: City name.
            required: true
          - name: zip_code
            type: string
            description: Postal code.
            required: true

Root Body (Entire Request Body)

The root_body field is a boolean flag (true or false) used exclusively for parameters with in: body. When set to true, it signifies that this particular parameter should represent the entire content of the HTTP request body, rather than being a named field within a larger JSON object.

This is useful for APIs that expect the root of their request body to be a raw array or a single complex object without an encapsulating key. Only one parameter per action can have root_body: true.

params:
  - name: user_list # This parameter will be the entire body
    type: array
    in: body
    description: A list of user objects to create.
    required: true
    root_body: true # This makes 'user_list' the direct JSON array body
    items: # Define the structure of each user object in the array
      - name: username
        type: string
        description: The user's unique username.
        required: true
      - name: email
        type: string
        description: The user's email address.
        required: true

Enum (Predefined Options)

The enum keyword allows you to specify a fixed list of allowed values for string parameters, or for the items within an array of strings. This helps ensure valid inputs and guides the LLM.enum for a string parameter: The priority parameter can only be one of “low”, “medium”, or “high”.

params:
  - name: priority
    type: string
    in: query
    description: The priority level for the task.
    required: true
    enum:
      - low
      - medium
      - high

Enum for items in an array of strings:

The tags array can contain multiple strings, but each string must be one of the specified categories.

params:
  - name: tags
    type: array
    in: body
    description: A list of relevant tags.
    required: false
    items: # Each item in the 'tags' array
      type: string
      enum: # Each tag string must be one of these
        - marketing
        - sales
        - development
        - support

YAFAI-Skills Documentation

Skill Manifests

What is a Skills Manifest?

Anatomy of a Skills Manifest

Defining Parameters

Simple Parameter Types

Complex Parameter Types

Object (Structured Data Group)

Array (List of Items)

Nested objects and arrays

Object with Nested Object

Root Body (Entire Request Body)

Enum (Predefined Options)

Enum for items in an array of strings:

​What is a Skills Manifest?

​Anatomy of a Skills Manifest

​Defining Parameters

​Simple Parameter Types

​Complex Parameter Types

​Object (Structured Data Group)

​Array (List of Items)

​Nested objects and arrays

​Object with Nested Object

​Root Body (Entire Request Body)

​Enum (Predefined Options)

​Enum for items in an array of strings:

What is a Skills Manifest?

Anatomy of a Skills Manifest

Defining Parameters

Simple Parameter Types

Complex Parameter Types

Object (Structured Data Group)

Array (List of Items)

Nested objects and arrays

Object with Nested Object

Root Body (Entire Request Body)

Enum (Predefined Options)

Enum for items in an array of strings: