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 dispatch only through the transactional path when payments are enabled.

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.

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 and every signed surface source the same list.

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_]*$.

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. Most defaults ship with 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 with Sill’s ed25519 card-signing 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. Every surface consults the same signals.

`skill_id`	What “backed” means
`browse_catalog`	The site has at least one searchable catalog product, OR a connected adapter (Shopify or WooCommerce) lists this skill.
`check_availability`	The site has at least one searchable catalog product.
`place_order`	The site has at least one checkout-eligible catalog product.
`order_status`	A connected adapter (Shopify or WooCommerce) lists this skill in its supported set.
`track_shipment`	A connected adapter (Shopify or WooCommerce) lists this skill in its supported set.
`request_refund`	A connected adapter is on the refund-capable rail list.
`recommend`	A connected adapter lists this skill in its supported set — today WooCommerce backs `recommend` from the merchant’s own curated related / upsell / cross-sell products (honest empty when none are curated).

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. order_status on a site without a connected commerce adapter).
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, missing_compliance_fields, no_checkout_rule, 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 payments-enabled surface.

Read-only skills (browse, check, status, track, recommend) can dispatch through a connected adapter today, where one is wired. The shipping adapters are Shopify and WooCommerce (woocommerce@1). 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.

Beyond the connected-adapter path, the Skill Fulfillment Contract v1 is the wire contract merchants can build against to fulfill the five read-side default skills (browse_catalog, check_availability, order_status, track_shipment, recommend) from their own HTTPS endpoint — request envelope, HMAC signing, canonical response shape per skill, and the self-test flow. The spec is public; whether a given site’s endpoint-fulfillment lane is enabled is a per-site configuration.

Frequently asked

Can a merchant add a custom skill beyond the seven defaults? Yes — custom skills are self-serve via Settings → Skills → “Add custom skill.” The skill must have a wired backing (a verified HTTPS endpoint you control) before it surfaces to agents. See Custom skills and 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.