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