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