> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Agent Skill File

> Machine-readable API specification for AI agents and LLMs

The Interchange API publishes a per-role **skill file** — a single Markdown document that teaches an AI agent how to use the API, on demand, at runtime.

## Overview

A skill file is a self-contained Markdown document that describes an entire API surface in a format LLMs can read and reason about. Agents discover capabilities, endpoints, auth, presentation rules, and gotchas without bespoke client code. v2 ships two: one for the **buyer** API and one for the **storefront** API.

## Skill File URL

<CardGroup cols={2}>
  <Card title="Buyer Skill File" icon="file-lines" href="https://api.interchange.io/api/v2/buyer/skill.md">
    Machine-readable API spec for buyer operations
  </Card>

  <Card title="Storefront Skill File" icon="file-lines" href="https://api.interchange.io/api/v2/storefront/skill.md">
    Machine-readable API spec for storefront operations
  </Card>
</CardGroup>

## Format

Each skill file opens with YAML front matter, followed by Markdown sections. The buyer skill file currently looks like:

```markdown theme={null}
---
name: scope3-agentic-buyer
version: "2.0.0"
description: Scope3 Agentic Buyer API - AI-powered programmatic advertising
api_base_url: https://api.interchange.io/api/v2/buyer
auth:
  type: bearer
  header: Authorization
  format: "Bearer {token}"
  obtain_url: https://interchange.io/user-api-keys
---

# Scope3 Agentic Buyer API

This API enables AI-powered programmatic advertising with inventory discovery,
campaign management, and creative orchestration.

## ⚠️ CRITICAL: Presentation Rules
…
```

After the front matter, the file walks through:

* **Presentation rules** — what an agent must show the user from each response.
* **Workflow guides** — the required call sequence for multi-step intents (e.g. campaign creation requires brief → audience → catalog → configure → execute).
* **Endpoint catalog** — operations exposed via `api_call`, with required fields, examples, and gotchas.
* **Display requirements per endpoint** — exactly which fields to surface and how to structure them.

## How an agent uses it

Agents connected over MCP get three tools and use them in a loop:

| Tool                   | Purpose                                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------------------- |
| `health`               | Probe API connectivity                                                                              |
| `ask_about_capability` | Search the skill file for the right operation, fields, and presentation rules for the user's intent |
| `api_call`             | Execute the chosen REST operation                                                                   |

The canonical pattern is:

1. User describes an intent in natural language.
2. Agent calls `ask_about_capability` with that intent. The skill file returns the relevant operation, required fields, and any "must show this in your reply" rules.
3. Agent gathers any missing inputs from the user (one question per turn) and calls `api_call` to execute.
4. Agent presents the result to the user, following the display requirements that came back with the operation. End the turn.

The skill file emphasizes **one mutating or discovery call per turn** — agents should not chain multiple writes in a single response.

**Custom agent prompt example:**

```
Read https://api.interchange.io/api/v2/buyer/skill.md and use it to help me
create an advertiser called "Acme Corp" for the brand acme.com. Once it's
created, list my advertisers so I can confirm.
```

## Versioning

The `version` field in the front matter is a semantic version that tracks **the skill file**, not the underlying API.

* **Patch** (`2.0.x`) — clarifications, new examples, fixed gotchas. No agent change required.
* **Minor** (`2.x.0`) — new operations, new optional fields, additive workflows. Existing agents keep working; new capabilities become available the next time `ask_about_capability` is called.
* **Major** (`x.0.0`) — breaking changes (renamed operations, removed fields, changed required workflows). Pin to the previous version's skill URL if your agent can't be updated immediately; otherwise re-test critical flows.

The skill file URL always serves the latest stable version for that role. There is no separate "v1 skill file" URL — v1 didn't ship one.

## Capability summaries

The skill files cover the same capabilities documented in the [Buyer API reference](/v2/buyer-api-reference) and [Storefront API reference](/v2/storefront-api-reference). For depth on any one area:

<CardGroup cols={2}>
  <Card title="Buyer onboarding" href="/v2/setup/buyer-onboarding" icon="user-plus">
    End-to-end campaign-launch flow.
  </Card>

  <Card title="Storefront onboarding" href="/v2/setup/storefront-onboarding" icon="store">
    Register a storefront and expose inventory.
  </Card>

  <Card title="Discovery guide" href="/v2/guides/discovery" icon="magnifying-glass">
    Product discovery, refinement, and proposals.
  </Card>

  <Card title="Built for Agents" href="/v2/setup/built-for-agents" icon="robot">
    MCP connector setup for Claude, ChatGPT, Cursor, and custom agents.
  </Card>
</CardGroup>

## Related

* [Built for Agents](/v2/setup/built-for-agents) — connector setup per AI tool.
* [Authentication](/v2/authentication) — OAuth and API key details.
* [Quick Start](/v2/quickstart) — connect an agent in minutes.