Skills (SKILL.md)

Agents discover and use your capability via a skill. In Cursor and the OpenClaw (open source) ecosystem, skills are often defined in a SKILL.md file that describes when to use the skill, what it does, and how to call it.

What to include

  • When to use — Describe the situations or user intents that should trigger this skill
  • What it does — Short description of the capability
  • How to call — Endpoint URL, method, headers, and request/response format
  • Parameters — Required and optional fields for requests

Keep the file concise and machine-friendly. Agents parse this to decide when to invoke your service and how to call it.

# Search API Skill

Use this skill when the user wants to search or query documentation.

## What it does
Searches the knowledge base and returns structured results.

## Endpoint
POST https://api.example.com/v1/search

## Headers
Authorization: Bearer <token>

## Body
{ "query": "string", "limit": number }

API Design

Agents interact with your app over HTTP. Design endpoints that are stable, well-specified, and easy for an agent to call from natural language or tool calls.

Best practices

  • REST or POST — Use clear REST semantics or simple POST endpoints. Avoid complex RPC or multi-step handshakes.
  • Versioning — Use versioned paths like /v1/... so you can evolve without breaking agents.
  • JSON everywhere — Prefer JSON for requests and responses. Document schemas so agents know what to expect.
  • Consistent errors — Return structured error responses with proper HTTP status codes.
  • Idempotency — Support idempotency keys for operations that create or modify resources.

Hosting & Deployment

Your service must be reachable by agents 24/7. Choose a host that gives you a public URL, HTTPS, and enough reliability for production use.

Platform options

  • Serverless — Vercel, Netlify, Railway, Fly.io. Great for getting started and automatic scaling.
  • Containers — AWS ECS, GCP Cloud Run. Full control over runtime and environment.
  • Edge computing — Cloudflare Workers, Vercel Edge. Low-latency, globally distributed.

Always use HTTPS and document your base URL in the skill definition so agents can call it reliably.

Authentication

Agents need to authenticate to your API on behalf of a user or app. Use a scheme that's easy for the agent to store and send with every request.

Authentication methods

  • API Keys — Issue long-lived or scoped keys. Agent sends Authorization: Bearer <key>. Simple and reliable.
  • OAuth 2.0 — For user-delegated access. Agent completes the flow and stores access/refresh tokens.
  • Signed requests / HMAC — For higher assurance, require signatures. The agent must have a secret and compute a signature per request; you verify it on the server.

Document the exact header format in your SKILL.md so agent runtimes can attach credentials correctly.

API Key Management

When users connect your service to an agent, you typically issue an API key that the agent stores and uses for all subsequent calls.

Issuing keys

  • Provide a "Generate API key" flow in your dashboard or settings
  • Generate cryptographically secure keys with appropriate scope (read-only, project-specific)
  • Show the key once and encourage secure storage in the agent's configuration

Storage (agent side)

The agent runtime stores the key securely and injects it into requests. You only document the header format in your SKILL.md, not the actual key.

Security best practices

  • Always use HTTPS to protect keys in transit
  • Issue scoped keys with minimal required permissions
  • Provide key rotation and revocation in your dashboard
← Back to home