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

# AI Agent Skills

> Versioned Apostra workflows and role-wide API guides for AI agents

Apostra publishes bounded, versioned **workflow skills** that teach an AI
agent how to complete a client job safely. The public catalog is the source of
truth for the current workflow roster and immutable version URLs.

<Card title="Workflow skill catalog" icon="list" href="https://api.interchange.io/skills/index.json">
  Read the machine-readable catalog of current and published workflow versions.
</Card>

## Workflow skills

<CardGroup cols={2}>
  <Card title="Build with Apostra" icon="code" href="https://api.interchange.io/skills/build-with-apostra/SKILL.md">
    Connect a repository and build a tested agent, data sender, or reporting
    pipeline. Start with the [V3 quickstart](/v3/quickstart).
  </Card>

  <Card title="Get an Account Ready to Buy" icon="user-check" href="https://api.interchange.io/skills/get-account-ready-to-buy/SKILL.md">
    Resolve buyer identity, billing, and seller-connection readiness.
  </Card>

  <Card title="Set Up a Campaign" icon="bullseye" href="https://api.interchange.io/skills/set-up-a-campaign/SKILL.md">
    Turn a buyer brief into a grounded draft and staged media buy.
  </Card>

  <Card title="Manage a Campaign" icon="chart-line" href="https://api.interchange.io/skills/manage-a-campaign/SKILL.md">
    Review delivery and safely change an existing campaign.
  </Card>

  <Card title="Set Up an Event Source" icon="wave-pulse" href="https://api.interchange.io/skills/set-up-an-event-source/SKILL.md">
    Configure or reuse conversion tracking for social platforms, direct feeds,
    and measurement partners.
  </Card>

  <Card title="Generate Campaign Creatives" icon="wand-magic-sparkles" href="https://api.interchange.io/skills/generate-campaign-creatives/SKILL.md">
    Create, refine, approve, and finalise a Creative Session when the buyer is
    enrolled.
  </Card>

  <Card title="Buy from a Seller" icon="store" href="https://api.interchange.io/skills/buy-from-seller/SKILL.md">
    Discover one seller's verified AdCP endpoint and transact through it.
  </Card>

  <Card title="Publish an OpenAI App" icon="share-nodes" href="https://api.interchange.io/skills/publish-an-openai-app/SKILL.md">
    Prepare a seller's Apostra-powered app for OpenAI review.
  </Card>

  <Card title="Test a Sales Agent" icon="vial" href="https://api.interchange.io/skills/test-sales-agent/SKILL.md">
    Run evidence-oriented, no-spend validation through ordinary V3 buyer tools.
  </Card>

  <Card title="Inspect a Tag Sheet" icon="file-spreadsheet" href="https://api.interchange.io/skills/inspect-tag-sheet/SKILL.md">
    Preview CSV, XLS, or XLSX parsing locally and report only a content-free
    receipt.
  </Card>
</CardGroup>

The stable URL for a skill resolves to its current version. The catalog also
publishes immutable URLs such as
`/skills/set-up-a-campaign/1.2.0/SKILL.md` for clients and evaluation runs that
need to pin exact instructions.

## Apostra workflow packages

Claude Code and Cowork users can add the public Apostra marketplace, then
install only the workflow package that matches their job:

```text theme={null}
/plugin marketplace add https://github.com/apostra-public/apostra.git
/plugin install buyer-campaign-management@apostra
```

Buyer packages cover account setup, campaign management, creative management,
and reporting. Storefront packages cover listing, merchandising, distribution,
and seller-side campaign management. `sales-agent-testing` works with sales
agents built by Apostra or by third parties. `amc-self-serve-buyer` combines the
current buyer workflows for an Agentic Media Company's own self-serve plugin.

Some packages initially provide authenticated MCP access while their bounded
workflow skill is still being authored. The marketplace README lists the exact
canonical skill version included in every package. Installing a package never
grants account access: Apostra OAuth, roles, capabilities, and entitlements
still control every tool call.

When a canonical skill advances, an automated source workflow composes a new
content-derived package version and opens a review PR in the public marketplace.
The update becomes public only after that mirror PR passes validation and is
merged.

The Inspect a Tag Sheet skill includes a self-contained local Node.js inspector.
The workbook stays on the user's machine: the inspector prints only parser and
mapping-profile versions, a row count, canonical role and rule IDs, and closed
diagnostic codes. It never prints or transmits filenames, worksheet names,
headers, placement names, tags, URLs, formulas, or cell values. A host that
cannot execute a local command can still present the exact command for the user
to run, but must not claim it inspected the file.

## How agents receive skills

The account-resolved V3 MCP endpoint advertises the
`io.modelcontextprotocol/skills` extension and implements `skills/list` and
`skills/get`. It also exposes eligible skills through MCP resources. Responses
include a SHA-256 digest so a host can identify the exact bytes it retrieved.

The ordinary V3 noun surface also supports
`search({kind: "skill", query: "test my agent"})` and
`get({kind: "skill", id: "test-sales-agent"})`. Search returns only workflows
applicable to the authenticated Buyer or Seller Account, its verified client
channel, its server-authoritative V3 capabilities, any runtime feature
entitlements explicitly required by the skill, and any required customer-scoped
feature flags. It uses deterministic metadata
matching—not a model call—and returns at most five candidates with the exact
terms and match reason that selected each one. Get returns the exact current
version, bundle digest, instructions, declared assets, required tools,
documentation, and the evaluation contract when that version declares one.
Declared JSON workflow assets such as scenarios and fixtures are also returned
as parsed, digest-bound `workflowAssets`, so an agent can follow the workflow
without permission to fetch an arbitrary server-supplied URL. These reads let
Murph and external agents find a workflow from the user's goal without a
separate proprietary `find_skill` tool.

Before an agent follows a workflow that can mutate account state, it must use
`get({kind: "skill", id})` for the active account and continue only when that
account-filtered retrieval succeeds. Its returned version and bundle digest
identify the exact eligible workflow. A public or installed bundle, `skills/list`,
or an operation in `tools/list` is not account eligibility evidence; a workflow
that is missing, inapplicable, unsupported, or unavailable stops before a
mutation.

## Correlate a skill run

Clients may send optional workflow identifiers on V2 REST requests:
`x-scope3-run-id`, `x-scope3-workflow-id`, `x-scope3-skill-id`,
`x-scope3-scenario-id`, and `x-scope3-step-id`. MCP clients can use
`_meta["scope3/run-id"]`, `_meta["scope3/workflow-id"]`,
`_meta["scope3/skill-id"]`, `_meta["scope3/scenario-id"]`, and
`_meta["scope3/step-id"]`. The optional `x-scope3-intent-hint` header or
`_meta["scope3/intent-hint"]` accepts a stable client-owned label of 1–64
characters: it must begin with a lowercase letter and then contain only
lowercase letters, digits, or underscores, such as `agent_testing`. It is a
correlation hint, not an authoritative Apostra intent taxonomy.

Retrieve the skill in the same correlated workflow before sending its scenario
step requests; operations observed before retrieval are not attributed to that
skill. Existing V2 REST and V3 MCP calls behave the same when this metadata is
omitted. Invalid workflow, skill, scenario, step, or intent values return REST
`400 INVALID_CORRELATION_METADATA`. Invalid run metadata returns
`400 INVALID_RUN_METADATA`. MCP returns JSON-RPC `-32602` with the specific
code in `error.data.code`. See
[Audit logs](/v2/guides/audit-logs#correlate-a-skill-workflow) for a complete
request example.

These values help correlate a client's run; they are not authorization and do
not prove that the named skill was retrieved, followed, or completed. A search
receipt records the applicable candidate versions. Attributing
subsequent operations to one skill requires the server receipt returned by
`get({kind: "skill"})` for that exact version and digest. Workflow completion
evidence comes only from server-observed operations, structured results,
follow-up reads, cleanup, and the skill's scenario assertions. If the server
does not observe intent or completion evidence, those values remain absent.

The Murph V2 insights response now provides `nonEscalationRate` and
`notEscalated` for its support signal. Existing clients continue to receive
`taskSuccessRate` and `resolvedWithoutEscalation` as deprecated aliases with
identical values. Those aliases measure only the absence of escalation; they
do not prove that a task completed successfully.

Apostra does not copy skill search text, matched terms, retrieved
instructions, prompts, credentials, signed URLs, briefs, creative bodies, or
tool payloads into skill-learning analytics. For this analysis, Apostra
stores only bounded identifiers, immutable digests, operation names and counts,
outcome categories, and evidence references.

Eligibility is contextual:

* Buyer Accounts receive account readiness, campaign setup, and campaign
  management skills through generic MCP discovery and submission bundles.
* Seller Accounts receive the OpenAI publication skill through generic MCP
  discovery. It is not included in the buyer submission bundle.
* Buy-from-seller and Sales Agent testing are published over HTTP and are
  discoverable through the account-aware V3 Skill noun where applicable; they
  are not pushed through generic account-wide MCP skill distribution.
* A public skill URL describes a workflow. It does not grant account access,
  tool entitlements, or permission to transact.

This filtering is especially important for white-label clients: an agent sees
only the workflows applicable to the authenticated account and distribution
channel, while the public catalog remains available for documentation and
version pinning.

Applicability never comes from a package-name guess. A complete version
manifest declares separate Buyer and Seller audience rules and can require a
named V3 capability or canonical runtime entitlement. Older manifests remain
explicitly marked as legacy and use a reviewed compatibility entry until a new
immutable version adopts the complete contract. The platform checks the
applicable rules before advertising or returning the skill. If entitlement
state cannot be verified, an entitlement-gated skill is withheld.

## Skill format and versioning

Each workflow starts with YAML front matter containing its stable name and
description, followed by the workflow, guardrails, required evidence, and
failure behavior. Some skills also publish a version manifest and deterministic
scenario or fixture assets; the version manifest declares those assets and the
versioned routes serve them.

Workflow versions use semantic versioning:

* **Patch** versions clarify or safely correct an existing workflow.
* **Minor** versions add compatible behavior, evidence, or scenarios.
* **Major** versions change a contract in a way that can require client work.

Use the stable URL when you want improvements automatically. Pin an immutable
version and digest for acceptance tests, canaries, or regulated workflows.

## Role-wide API guides

Apostra also keeps two broader v2 role guides. These are API manuals rather
than entries in the bounded workflow catalog:

<CardGroup cols={2}>
  <Card title="Buyer API guide" icon="file-lines" href="https://api.apostra.com/api/v2/buyer/skill.md">
    Role-wide v2 buyer operations and presentation rules.
  </Card>

  <Card title="Storefront API guide" icon="file-lines" href="https://api.apostra.com/api/v2/storefront/skill.md">
    Role-wide v2 storefront operations and presentation rules.
  </Card>
</CardGroup>

Agents using those role-wide guides work through `health`,
`ask_about_capability`, and `api_call`. New V3 integrations should prefer the
typed V3 tools and bounded workflow skills above.

## Related

* [Built for Agents](/v2/setup/built-for-agents) — connector setup for AI tools.
* [Buyer onboarding](/v2/setup/buyer-onboarding) — buyer account readiness.
* [Seller workflows](/v2/setup/v3/seller-workflows) — seller and Sales Agent workflows.
* [White-label ChatGPT app](/v2/reference/white-label-chatgpt-app) — account-resolved OpenAI packaging.
* [Authentication](/v2/authentication) — OAuth and API key details.