Skill Definitions

Skills are YAML files that define reusable tool sets for agents. They declare what an agent can do—HTTP actions, credential bindings, parameter schemas, and output filters—in a portable, declarative format.

Overview

A skill is a self-contained YAML file that packages one or more tools together with their credential requirements and instructions. Agents reference skills by name, gaining access to the defined tool set without knowing the implementation details. The YAML defines what the agent can do, not how it decides to use it.

File Location

skills/ directory at the project root

Extension

.yaml or .yml

Philosophy

Declarative — YAML defines WHAT, not HOW

Reusability

One skill can be shared across multiple agents

Skill Schema Reference

Field	Type	Required	Description
`name`	`string`	Yes	Unique identifier for the skill
`description`	`string`	Yes	Human-readable summary of what the skill provides
`version`	`string`	No	Semantic version of the skill definition
`credentials`	`array`	No	Credential references from the vault required by this skill
`tools`	`array`	Yes	List of tool definitions available in this skill
`instructions`	`string`	No	Natural-language guidance for the agent on when and how to use the tools

Tool Definition

Each entry in the tools array defines a single operation the agent can perform. Tools combine parameter schemas, credential bindings, HTTP actions, and output filtering into a single declarative block.

Field	Type	Description
`name`	`string`	Unique tool name within the skill
`description`	`string`	What this tool does — shown to the agent for tool selection
`parameters`	`array`	Inputs the agent must provide when calling the tool
`credentials`	`object`	Vault reference and injection binding
`action`	`object`	The HTTP action to execute (method, URL, headers, body)
`output`	`object`	Response filtering — allowlist of fields to return

Parameters

Each parameter declares its type, description, and whether it is required. Parameters are injected into action templates as {{variableName}} placeholders.

Property	Type	Description
`type`	`string`	One of `string`, `number`, or `boolean`
`description`	`string`	Explains to the agent what this parameter controls
`required`	`boolean`	Whether the agent must supply this value

parameters:
  - name: owner
    type: string
    description: "GitHub repository owner"
    required: true
  - name: repo
    type: string
    description: "Repository name"
    required: true
  - name: per_page
    type: number
    description: "Results per page"
    required: false

Credential References

Credentials link a skill to secrets stored in the Credential Vault. The ref field names the vault entry, and inject_as defines the template variable used in action URLs, headers, or bodies.

Property	Description
`ref`	Name of the credential in the vault (e.g. `github-token`)
`inject_as`	Template variable name used in actions (e.g. `GITHUB_TOKEN`)

credentials:
  - ref: github-token
    inject_as: GITHUB_TOKEN

At runtime, every occurrence of {{GITHUB_TOKEN}} in the action block is replaced with the vault secret.

Action HTTP

The action block defines the HTTP request to execute when the tool is called. URLs, headers, and body values can reference both parameters and credentials using {{variable}} syntax.

Property	Description
`type`	Action type — currently `http`
`method`	HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
`url`	Request URL with `{{variable}}` placeholders
`headers`	Key-value map of HTTP headers
`body`	Request body (for POST/PUT/PATCH)

action:
  type: http
  method: GET
  url: "https://api.github.com/repos/{{owner}}/{{repo}}/issues?per_page={{per_page}}"
  headers:
    Authorization: "Bearer {{GITHUB_TOKEN}}"
    Accept: "application/vnd.github.v3+json"

Output Filtering

The output block defines an allowlist of response fields to return to the agent. This keeps payloads lean and prevents the agent from receiving unnecessary data that could consume context tokens.

output:
  include:
    - id
    - title
    - state
    - assignee.login
    - labels[].name
    - created_at

Only the listed fields (and nested paths) are extracted from the API response. Everything else is dropped before the result reaches the agent.

Full Example github-operations

A complete skill file combining all the concepts above. This skill gives an agent the ability to list issues from any GitHub repository.

# skills/github-operations.yaml

name: github-operations
description: "GitHub repository tools — issues, PRs, and repo management"
version: "1.0.0"

credentials:
  - ref: github-token
    inject_as: GITHUB_TOKEN

tools:
  - name: list-issues
    description: "List open issues for a GitHub repository"

    parameters:
      - name: owner
        type: string
        description: "Repository owner (user or org)"
        required: true
      - name: repo
        type: string
        description: "Repository name"
        required: true
      - name: per_page
        type: number
        description: "Results per page (default 30)"
        required: false

    credentials:
      ref: github-token
      inject_as: GITHUB_TOKEN

    action:
      type: http
      method: GET
      url: "https://api.github.com/repos/{{owner}}/{{repo}}/issues?per_page={{per_page}}"
      headers:
        Authorization: "Bearer {{GITHUB_TOKEN}}"
        Accept: "application/vnd.github.v3+json"

    output:
      include:
        - id
        - title
        - state
        - assignee.login
        - labels[].name
        - created_at

instructions: |
  Use list-issues to check the current state of a repository.
  Always specify the owner and repo. Use per_page to limit results
  when you only need a quick overview.

Design Philosophy

Declarative, not imperative

YAML defines what the tool does (endpoints, parameters, credentials). The agent decides when and how to use it based on the task at hand.

Portable and reusable

A single skill file can be referenced by multiple agents. Change the credential binding once, and every agent using the skill picks up the update.

Minimal surface area

Output filtering ensures agents only receive the fields they need. This keeps token budgets tight and reduces hallucination from noisy payloads.

Credential isolation

Secrets live in the vault, never in YAML. Skills reference credentials by name and inject them at runtime through template variables.