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

# Agent skills

> Versioned, task-shaped instructions an agent can load before it works in Semicola.

A **skill** is a short, versioned instruction file for one job, written for an agent rather than a
person. It names the tools to call, the order to call them in, the questions to ask the person, and
where to stop for confirmation. Load the skill that matches the task before you start; it keeps an
agent from improvising a workflow the platform already defines.

## Task skills

<CardGroup cols={2}>
  <Card title="Build with Semicola" icon="plug" href="/skills/build-with-semicola">
    Anyone. Connect, verify with `get_status`, read `tools/list`, and learn the rules every other
    skill assumes.
  </Card>

  <Card title="Get an account ready to buy" icon="list-check" href="/skills/get-account-ready-to-buy">
    Buyers. Clear readiness blockers: advertiser, currency, seller connections, terms and billing.
  </Card>

  <Card title="Set up a campaign" icon="clipboard-list" href="/skills/set-up-a-campaign">
    Buyers. Brief to draft campaign, proposals, creatives and staged media buys. Stops before
    launch.
  </Card>

  <Card title="Manage a campaign" icon="sliders" href="/skills/manage-a-campaign">
    Buyers. Delivery and pacing, launch with approval, pause, budget and flight changes, cancel.
  </Card>

  <Card title="Buy from a seller" icon="store" href="/skills/buy-from-seller">
    Buyers. Work with one named seller: availability, proposal or products, refinement, staging.
  </Card>

  <Card title="Test a sales agent" icon="flask" href="/skills/test-sales-agent">
    Sellers. Connect an AdCP sales agent as an inventory source and prove it with a practice brief.
  </Card>

  <Card title="Set up an event source" icon="chart-line" href="/skills/set-up-an-event-source">
    Buyers. Find or create an event source, confirm events arrive, attach it to a campaign goal.
  </Card>
</CardGroup>

## Persona skills

Two longer files cover everything one kind of agent does, and point to the task skills above.

<CardGroup cols={2}>
  <Card title="Buyer skill" icon="cart-shopping" href="/v2/buyer/skill">
    For agents that buy for an advertiser or agency.
  </Card>

  <Card title="Storefront skill" icon="shop" href="/v2/storefront/skill">
    For agents that operate a seller's storefront.
  </Card>
</CardGroup>

## Where agents fetch skills

| URL                                                             | What it returns                                                 |
| --------------------------------------------------------------- | --------------------------------------------------------------- |
| `https://docs.semicola.com/skills/<name>.md`                    | One task skill as markdown (the page you are reading, as text). |
| `https://docs.semicola.com/v2/buyer/skill.md`                   | The buyer persona skill.                                        |
| `https://docs.semicola.com/v2/storefront/skill.md`              | The storefront persona skill.                                   |
| `https://docs.semicola.com/.well-known/agent-skills/index.json` | The skill index for agent-skills discovery.                     |
| `https://docs.semicola.com/.well-known/agent-card.json`         | The A2A agent card that lists the same skills.                  |
| `https://api.semicola.com/skills/index.json`                    | The API's skills catalog, with versions.                        |
| `https://api.semicola.com/skills/<name>/SKILL.md`               | One skill from the API.                                         |

## Rules every skill follows

* Start with `get_status`, and confirm the account before any write.
* Treat `tools/list` as the contract; a skill never overrides a schema.
* Stop at `needs_input` and `pending_confirmation`, and ask the person.
* Use an idempotency key for every write, and re-read before retrying.

<Note>
  Skills describe workflows; they grant nothing. An agent can only do what its credential and
  account already allow.
</Note>