Skip to content
Sill Docs

Custom skills

Beyond the seven default skills, you can define custom skills — capabilities specific to your store — and have Sill fulfill an agent’s call to them by relaying it to an endpoint you run. Custom skills appear on your signed agent card and your MCP server’s tools/list just like the defaults, and every call is recorded in your signed audit envelope.

You add and manage custom skills yourself in the dashboard, under Settings → Skills. Owners and admins can create them.

Fulfillment modes

Section titled “Fulfillment modes”

Each custom skill has a fulfillment mode that decides what happens when an agent calls it:

ModeWhat Sill does
AdvertisedLists the skill so agents can discover it; you fulfill the request yourself, out of band. No endpoint needed.
WebhookRelays the agent’s call to your HTTPS endpoint as a signed request, and returns your response to the agent.
MCP serverRelays the agent’s call to your own MCP server as a JSON-RPC tools/call, and returns the result to the agent.

Webhook and MCP-server skills are the ones Sill actively fulfills. Both require an endpoint on your verified domain (see Domain verification).

Endpoint requirements

Section titled “Endpoint requirements”

Your endpoint must be:

  • On your verified domain — the apex or any subdomain of the domain you verified for this site. Sill will not relay to any other host.
  • HTTPS, on the standard port.
  • Reachable — Sill probes it when you save. If the probe fails, the skill shows Unreachable and is not advertised to agents until it responds.

Sill sends every relayed request from its own servers (never from the browser or the agent), signs it with your skill’s shared secret, and only ever connects to a public address on your verified domain.

The shared secret

Section titled “The shared secret”

When you create a webhook or MCP-server skill, Sill mints a shared secret and shows it to you once. Copy it then — it cannot be retrieved later. If you lose it or want to roll it, use Rotate secret on the skill to mint a new one.

Sill signs each relayed request with this secret so your endpoint can confirm the request genuinely came from Sill. The signature travels in an X-Sill-Signature header using the same scheme as a Stripe webhook:

X-Sill-Signature: t=<unix-timestamp>,v1=<hex>

<hex> is HMAC-SHA256 of "<t>.<raw-request-body>" keyed with your secret. Recompute it over the exact bytes you received and compare; use the timestamp to reject stale requests.

Your endpoint’s contract

Section titled “Your endpoint’s contract”

Webhook

Section titled “Webhook”

Sill sends a POST with a JSON body carrying the skill_id, the agent’s arguments, and a per-call nonce. Respond with 200 and a JSON body — that JSON is returned to the agent (after Sill sanitizes it). A non-2xx status, an oversized body, or non-JSON is treated as a failure and the agent gets a bounded error, never your raw response.

MCP server

Section titled “MCP server”

Sill sends a POST with a JSON-RPC tools/call request:

{
  "jsonrpc": "2.0",
  "id": "<per-call id>",
  "method": "tools/call",
  "params": { "name": "<skill_id>", "arguments": { } }
}

Your MCP server must:

  • Echo the id back in the response — Sill rejects a response whose id does not match.
  • Return a JSON-RPC result: { "jsonrpc": "2.0", "id": "<same id>", "result": { "structuredContent": { … } } } (or a content array). Sill returns structuredContent when present, otherwise content.
  • Accept a single, stateless tools/call — Sill does not perform an MCP initialize handshake first.

A JSON-RPC error, a result with isError: true, or a malformed response is returned to the agent as a bounded error — your raw error text is never forwarded.

Creating a custom skill

Section titled “Creating a custom skill”
  1. Go to Settings → Skills and choose Add custom skill.
  2. Enter a name; the skill_id is derived automatically (a lowercase, snake_case identifier) and stays editable.
  3. Choose the fulfillment mode. For Webhook or MCP server, enter your endpoint URL on your verified domain.
  4. Save. Sill validates the endpoint and probes it.
  5. For a webhook or MCP-server skill, copy the shared secret now — it is shown only once.

Once saved and healthy, the skill is advertised on your agent card and MCP tools/list. You can Edit endpoint (Sill re-probes it) or Rotate secret at any time from the skill’s row.

Where a custom skill surfaces

Section titled “Where a custom skill surfaces”

A healthy custom skill behaves like any other backed skill:

An unhealthy endpoint (failed probe) is not advertised; the dashboard shows Unreachable with the reason, so you never advertise a skill you cannot fulfill.

Frequently asked

Section titled “Frequently asked”

What happens if my endpoint is down when an agent calls? The agent receives a bounded, generic error — never your raw response or internal details — and the failed call is still recorded in your audit log. Sill also marks the skill unreachable so it stops being advertised until it responds again.

Can I point a skill at an endpoint on a different domain? No. The endpoint must be on the domain you verified for the site (apex or a subdomain). This is what lets agents trust that a call is fulfilled by you.

Is the shared secret ever recoverable? No. It is shown once at create time (and once again each time you rotate it). If you lose it, rotate to mint a new one and update your endpoint.

Do custom skills need a signed mandate? No. Custom skills are part of the discovery surface. Money-movement is handled by the gated default skills and the transactional pipeline.

See also

Section titled “See also”