Skills

A skill is a capability a merchant exposes to AI agents through Sill. The default skill set ships with seven items — browse_catalog, check_availability, place_order, order_status, track_shipment, request_refund, recommend — and every signed surface Sill publishes per site (the agent card, the MCP server’s tools/list, and the ARD catalog) advertises only the skills that have an actual wired backing. Skills the site does not really expose do not appear. Money-movement skills additionally require a signed mandate and are gated to the Phase‑2 transactional path.

The seven defaults

Every new Sill site is provisioned with the same seven default skills. The skill identifier is the snake_case skill_id — it is the stable, cross-protocol name that the agent card, MCP tools/list, and the ARD catalog all reference.

`skill_id`	Display name	Description	`auth_required`
`browse_catalog`	Browse catalog	Search and browse the product catalog	`false`
`check_availability`	Check availability	Check real-time stock and availability	`false`
`place_order`	Place order	Place an order with a signed payment authorization	`true`
`order_status`	Order status	Look up the status of an order	`false`
`track_shipment`	Track shipment	Track the shipment for an order	`false`
`request_refund`	Request refund	Request a refund or return	`true`
`recommend`	Recommend	Get product recommendations	`false`

auth_required: true marks a skill that cannot dispatch without a signed mandate — today place_order and request_refund. Those skills are the ones the Phase‑2 mandate pipeline gates.

The order is load-bearing. The agent card payload is canonicalized before signing, so any change to the default skill list (add, remove, reorder) changes the signed bytes. The dashboard list, the origin’s site-creation handler, and the edge’s bundled fallback all source the same list so the three views can never drift.

What a skill is, in the data model

A skill is a row attached to a site. The wire shape is:

{
  "skill_id": "browse_catalog",
  "site_id": "01EXAMPLE00000000000000000",
  "name": "Browse catalog",
  "description": "Search and browse the product catalog",
  "request_schema": {},
  "auth_required": false,
  "enabled": true,
  "created_at": "2026-05-27T00:00:00Z"
}

skill_id is a snake_case identifier matching ^[a-z][a-z0-9_]*$. The same regex is enforced both at the origin database (CHECK constraint) and re-validated at the edge before any skill identifier is used as part of a cache or rate-limit key — defense in depth.

enabled is the merchant’s intent. Whether the skill actually surfaces to agents depends on enabled AND backing. See Backing-filtered visibility below.

auth_required is a per-skill flag. When true, the skill cannot dispatch without a signed mandate.

request_schema is opaque JSON Schema. In Phase 1 most defaults use a permissive placeholder schema; wired skills (e.g. browse_catalog against a connected commerce backend) carry a real per-skill schema.

See Concepts for the full data-model glossary.

Where a skill surfaces

A single enabled, backed skill appears on three signed/discovery surfaces. All three derive from the same backing signals, so they cannot disagree.

flowchart LR
  S[(Site skills + connector status)] --> B{Backed?}
  B -- yes --> AC["Agent card skills[]"]
  B -- yes --> MCP["MCP server tools/list"]
  B -- yes --> ARD["ARD catalog entries[]"]
  B -- no --> H["Hidden from agents (visible in dashboard)"]

Agent card

Each per-site agent card lists the backed skills in its skills[] array, with name, description, and auth_required. The card is signed under the foyer/edge/card-signing-v1 ed25519 key; the signature covers the canonical card payload, including the skills[] set. See the A2A specification for the agent-card schema and Verify a signature for the verifier recipe.

MCP `tools/list`

The per-site MCP server exposes the same backed skills as MCP tools. The MCP tool name is the snake_case skill_id; the description matches the agent card. A tools/list response looks like:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "browse_catalog",
        "description": "Search and browse the product catalog",
        "inputSchema": { "type": "object", "additionalProperties": true }
      }
    ]
  }
}

Skills without a wired per-skill schema render with a permissive placeholder inputSchema. Skills with a wired backing (today: browse_catalog) emit a real input schema. See the Model Context Protocol specification for the broader tools/list contract.

ARD catalog

The per-site ARD catalog advertises the agent card and MCP endpoints as discoverable entries. The catalog’s trustManifest is signed with a detached ed25519 JWS over the RFC 8785 (JCS) canonical form. The per-entry url / capabilities / description fields are not inside the signed payload — content integrity for those rests on did:web + TLS, per the ARD specification.

Backing-filtered visibility

A skill is backed (and therefore advertised) only when there is a real fulfillment path for it on this site. The decision is computed from the same signals on every surface — there is no second source of truth.

`skill_id`	What “backed” means
`browse_catalog`	The canonical catalog has at least one `is_eligible_search` row, OR a connected adapter lists this skill.
`check_availability`	The canonical catalog has at least one `is_eligible_search` row.
`place_order`	The canonical catalog has at least one `is_eligible_checkout` row.
`order_status`	A connected adapter lists this skill in its supported set.
`track_shipment`	A connected adapter lists this skill in its supported set.
`request_refund`	A connected adapter is on the refund-capable rail list.
`recommend`	No adapter ships a backing today; surfaces only when one does.

If a skill is enabled but unbacked, the dashboard surfaces an honest status — see Per-skill status (dashboard).

Per-skill status (dashboard)

The dashboard’s Skills view derives a closed-enum status for each row from the same backing signals the card and MCP surfaces consult. The five possible states are:

live — merchant enabled, backed, tier permits. The skill appears on the card and MCP server; dispatch fulfills it.
enabled_unbacked — merchant enabled, tier permits, but no backing signal. The skill stays in the dashboard but not on the card or MCP server.
enabled_unsupported — no fulfillment path exists today (e.g. recommend on a site whose connected adapters do not list it).
tier_gated — site tier is below the skill’s floor (e.g. money-movement skills require a transactional tier).
disabled — enabled: false. The merchant turned it off.

Non-live, non-disabled rows carry a closed-enum gating_reason (no_search_eligible_catalog, no_checkout_eligible_catalog, no_refund_rail, no_fulfillment_connector, no_adapter, below_tier_floor) so the dashboard can render an actionable next step.

Dashboard Skills view — the seven defaults rendered with per-row status and the matching next-step hint.

Verifying a site’s advertised skills

The skills a site actually exposes today are visible on its signed agent card. To inspect them with no Sill code:

curl -s "https://edge.sill.so/v1/agent-card/${SITE_KEY}.json" | jq '.skills'

Replace ${SITE_KEY} with the site key issued for the verified domain. The response is signed; you can verify the signature against the public JWKS using only off-the-shelf ed25519 tooling — see Verify a signature.

To enumerate the same set through MCP, post an initialize then a tools/list to the site’s MCP endpoint — see the MCP server page.

Skill execution boundaries

Discovery is the live surface; transactional execution is the Phase‑2 surface.

Read-only skills (browse, check, status, track, recommend) can dispatch through a connected adapter today, where one is wired. Without a backing, they appear nowhere agent-facing.
Money-movement skills (place_order, request_refund) are gated. Even when the merchant enables them and an adapter is wired, dispatch requires a signed mandate evaluated by the policy engine and authorized through the merchant’s processor. See Signed mandates.

Frequently asked

Can a merchant add a custom skill beyond the seven defaults? The seven defaults are the Phase 1 set. The data model carries no hard cap on custom skill rows, but only skills with a wired backing surface to agents, and the agent-card canonicalization assumes a deterministic order, so adding custom skills is an integration-side change, not a self-serve action today. See Sites and onboarding.

Why does my dashboard show a skill as enabled_unbacked? Backing is computed from real signals — catalog eligibility, connected adapters, and (for refunds) refund-capable rails. An enabled_unbacked row means the merchant turned the skill on but the backing signal is missing. The row carries a gating_reason that says exactly what to fix.

Does the MCP server response carry a signature? No. The signed surface in MCP discovery is the agent-card pointer to the MCP endpoint, not the MCP response bodies themselves. The MCP server records every tools/call invocation in the site’s signed audit envelope — see MCP server and Audit envelope.

Are the per-entry capabilities in the ARD catalog signed? No. The ARD trust manifest’s signature covers identity + provenance. Per-entry fields rest on did:web + TLS, per the ARD specification. See ARD catalog.

Does Sill emit skills for protocols other than A2A / MCP / ARD? The current edge protocol allowlist is a2a, ap2, and mcp. ACP, UCP, and x402 are on the roadmap; see Protocols.