The Agent Skill Pattern: Packaging APIs for AI Consumption

The problem with API docs

API documentation was designed for a human developer sitting at a desk. They read the getting started guide, scan the endpoint reference, copy the cURL example, and adapt it to their codebase. This workflow works. It has worked for decades.

But it doesn't work for AI agents.

An AI agent doesn't “scan” a documentation site. It doesn't browse tabs. It doesn't click through interactive examples. It processes text — structured, contextual text — and makes tool calls based on what it understands. The richer and more structured the text, the better the tool call.

Most API documentation is optimised for visual browsing, not text comprehension. That's a problem when your fastest-growing user segment is software.

What is an Agent Skill?

An Agent Skill is a structured markdown file (or set of files) that teaches an AI agent how to use a service. It bundles everything the agent needs into a single installable package:

• What the service does — A concise, LLM-optimised description
• When to use it — Trigger conditions and use cases
• How to call it — Exact API endpoints, parameters, and auth
• Examples — Complete request/response pairs the agent can pattern-match against
• Edge cases — What to do when things go wrong

The format was pioneered by frameworks like Hermes Agent (via agentskills.io) and has been adopted across the agentic ecosystem. Hermes even generates its own skills from experience — if it solves a problem once, it creates a skill so it can solve it faster next time.

Skill anatomy

Here's what a Signbee Agent Skill looks like:

---
name: signbee-esigning
description: Send documents for legally binding e-signatures via the Signbee API
version: 1.0.0
triggers:
  - "sign document"
  - "send contract"
  - "send NDA"
  - "e-sign"
  - "get document signed"
---

# Signbee E-Signing Skill

## When to Use
Use this skill when a user asks to send a document
for signing, check document status, or draft a contract
that needs legally binding signatures.

## Authentication
Requires a Signbee API key. Set as SIGNBEE_API_KEY
environment variable. Get one at https://signb.ee/register

## Primary Action: Send Document

POST https://signb.ee/api/v1/send
Content-Type: application/json
Authorization: Bearer {SIGNBEE_API_KEY}

### Required Fields
- markdown: string (the document content in markdown)
- sender_name: string
- sender_email: string (must match account email)
- recipient_name: string
- recipient_email: string

### Optional Fields
- title: string (document title, shown in email)
- pdf_url: string (use existing PDF instead of markdown)

### Example Request
{
  "markdown": "# Mutual NDA\n\nThis agreement...",
  "sender_name": "Alice Smith",
  "sender_email": "alice@startup.com",
  "recipient_name": "Bob Jones",
  "recipient_email": "bob@acme.dev",
  "title": "Mutual NDA"
}

### Example Response
{
  "success": true,
  "document_id": "cmm8x9k2j000108l3...",
  "signing_url": "https://signb.ee/sign/cmm8x9k2j..."
}

## Error Handling
- 401: Invalid API key
- 429: Rate limited (free: 5/month, pro: unlimited)
- 400: Missing required field (check markdown + emails)

This is everything an agent needs. No browsing. No guessing. No “let me check the docs”. The skill tells it what the tool does, when to use it, exactly how to call it, and what errors to expect.

The Triad Specification: llms.txt, SKILL.md, and MCP

Leading developer platforms do not treat agent integration as a single file. Instead, they organize their interfaces into three complementary layers tailored to different stages of the agent lifecycle:

Skills vs. traditional docs

Modular Directory Layout: The Index vs. Deep Reference Pattern

As skills expand to handle complex enterprise requirements, cramming thousands of lines of documentation into a single SKILL.md degrades model performance through context dilution. Instead, modern agent architectures employ a modular index layout:

.agent/skills/signbee-signing/
├── SKILL.md                 # Lean index (< 500 tokens): Triggers, when to use, quick reference
├── references/
│   ├── api-endpoints.md     # Full REST specification (loaded on demand)
│   ├── error-dictionary.md  # HTTP 400, 401, 403, 429 resolution playbooks
│   └── legal-standards.md   # ESIGN Act & eIDAS compliance clauses
└── scripts/
    └── smoke_test.py        # Executable self-test script for agent sanity checks

When an agent activates the skill, it reads only SKILL.md. If it encounters a complex validation error or needs exact legal wording, it selectively loads references/error-dictionary.md, conserving tokens and maximizing reasoning precision.

The distribution layer

Skills need somewhere to live. Several registries have emerged:

• agentskills.io — The open format specification and community registry
• ClawHub — Community skill marketplace
• GitHub — Universal source; agents can clone and install directly
• Self-created — Hermes Agent generates skills from experience automatically

The distribution model is similar to npm packages but simpler — a skill is just a markdown file. No build steps, no dependencies, no runtime. An agent reads it and immediately knows how to use the service.

Why this matters for API builders

If you're building an API-first product, you have a new distribution channel to think about. Traditional developer marketing goes: write docs → get featured on developer blogs → hope developers find you via Google.

Agent Skill distribution goes: write a skill file → publish to registries → agents discover and install your product automatically.

The agent doesn't need to “discover” your product through marketing. It discovers it through capability matching — “I need to sign a document, do I have a skill for that?” If the skill is installed, your API gets called. If it isn't, the agent might search for one and install it.

This is why we built Signbee as an API-first product from day one. Our llms.txt file, our MCP server, and our Agent Skill are three layers of the same strategy: make Signbee discoverable and usable by AI agents, not just human developers.

Building your own skill

If you maintain an API, creating an Agent Skill takes less than an hour:

1. Write a SKILL.md — Name, description, trigger keywords
2. Document the primary action — The one API call that delivers the most value
3. Include a complete example — Request and response, copy-paste ready
4. Add error handling — What the agent should do when calls fail
5. Publish — GitHub repo, agentskills.io, or embed in your docs

Keep it focused. One skill should do one thing well. If your API has ten endpoints, start with a skill for the most common workflow — the one that delivers value in a single call.