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

# Agent Skills

> Give a coding agent a repeatable Tirdad workflow by packaging the MCP server, API, and docs as a skill

An Agent Skill is a folder with a `SKILL.md` file that a coding agent loads when a task matches its description. Claude Code, Cursor, and other agents that follow the [Agent Skills](https://agentskills.io) format read the same file. A Tirdad skill does not add a new API; it tells the agent which existing surface to use for which job, and the conventions your team wants followed.

## What to connect before writing a skill

Before writing a skill, connect the surfaces it will call:

| Surface | What the agent gets | Set up |
| - | - | - |
| MCP server | One tool per API operation, scoped with `--scope read`, `write`, or `delete` | [MCP server](https://docs.tirdad.ai/docs/connect/mcp-server.md) |
| REST API | Every operation over HTTPS with an API key, for agents that run shell commands | [API reference](https://docs.tirdad.ai/developers/api-reference.md) |
| Docs as text | The whole documentation set as one file the agent can fetch | `https://docs.tirdad.ai/llms-full.txt` |
| OpenAPI spec | Every endpoint, field, and enum | [OpenAPI spec](https://docs.tirdad.ai/developers/api-tooling/openapi-spec.md) |

## A minimal Tirdad agent skill

Create `.claude/skills/tirdad/SKILL.md` in your repository (or the equivalent skills directory for your agent):

```markdown theme={null}
---
name: tirdad
description: Use when the task touches billing, usage metering, plans, customers, subscriptions, wallets, or invoices in Tirdad. Covers reading data, sending usage events, and changing catalog objects.
---

# Tirdad

## Which surface to use

- Read or list anything: use the Tirdad MCP tools (get_*, list_*) if connected, otherwise call the REST API with curl.
- Send usage events: `POST https://api.tirdad.ai/v1/events` with an explicit `event_id` so retries dedupe.
- Change catalog or customer data: propose the change, show the exact request, and wait for approval before running any create, update, or delete.

## Rules

- Never put an API key in a command or file. It comes from the TIRDAD_API_KEY environment variable, sent as the `x-api-key` header.
- Use the sandbox environment key unless the user names production.
- Event names are case-sensitive and immutable after creation. List features before inventing one.
- Treat any non-2xx response as a failure and report the response body; do not retry 4xx errors.

## Reference

- Docs: https://docs.tirdad.ai/llms-full.txt
- OpenAPI spec: https://docs.tirdad.ai/api-reference/openapi.json
```

## Making the skill safe by construction

The skill text is advice. Enforce the important parts with configuration the agent cannot talk itself out of:

* **Scope the MCP server.** Start it with `--scope read` for exploration and add `write` only for agents that are expected to change data. See [MCP server](https://docs.tirdad.ai/docs/connect/mcp-server.md#authenticating-the-mcp-server).
* **Use a sandbox key.** A key is bound to one environment, so a sandbox key cannot touch production.
* **Use a scoped API key.** Create a key with a read-only role for read-heavy agents. See [Manage API keys](https://docs.tirdad.ai/docs/rbac/manage-api.md).
* **Require confirmation in the client.** Most MCP clients can ask a human before running a write tool. Turn that on.

## Extending the skill

Skills grow by adding files next to `SKILL.md`. Useful additions for Tirdad:

* `references/events.md`: the event names and property keys your product emits, so the agent never guesses a meter.
* `references/plans.md`: your plan lookup keys and what each entitles.
* `scripts/backfill.sh`: a vetted script the agent runs instead of composing bulk ingestion by hand.

> [card] [MCP server](https://docs.tirdad.ai/docs/connect/mcp-server.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.