Przejdź do treści
Biblioteka skilli
Programowanie · Integracja z narzędziem

agentic-surface

/agentic-surface

Buduje, bada i audytuje maszynowo czytelną powierzchnię sklepu: profil UCP, endpointy MCP koszyka, checkoutu i katalogu, kwalifikację katalogu agentowego i tożsamość agenta.

Repozytorium
HomeIQ ↗
Licencja
MIT
Ostatnia zmiana repozytorium
15.09.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść25 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 15.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Buduje, bada i audytuje maszynowo czytelną powierzchnię sklepu: profil UCP, endpointy MCP koszyka, checkoutu i katalogu, kwalifikację katalogu agentowego i tożsamość agenta.

Oryginalny opis (EN)

Use when building, probing, or auditing the machine-readable surface of a storefront — UCP profile, MCP cart/checkout/catalog endpoints, agentic-catalog eligibility, product route shape, or agent identity. Carries dated protocol cutovers.

Jak działa

  1. 1. The cutover calendar
  2. 2. Endpoints, and which one needs a credential
  3. 3. Who serves the UCP profile — not us
  4. 4. Catalog eligibility
  5. 5. The product route is a hard requirement
  6. 6. Agent identity and rate limits
  7. 7. What a headless storefront owes agents
  8. 8. Audit behaviour
Sekcje z nagłówków SKILL.md, w oryginale · 160 linii, 1 375 słów
Podgląd SKILL.md
---
name: agentic-surface
description: Use when building, probing, or auditing the machine-readable surface of a storefront — UCP profile, MCP cart/checkout/catalog endpoints, agentic-catalog eligibility, product route shape, or agent identity. Carries dated protocol cutovers.
version: 1.0.0
verified_at: 2026-08-01
expires: 2026-11-01
allowed_tools: ""
---
# Agentic surface

**Dated knowledge.** Verified 2026-08-01 against the platform's own changelog, its
agent documentation, its Catalog requirements pages, and two developer-forum
threads carrying staff answers. Re-verify by **2026-11-01**.

This surface moves faster than any other in the kit — **two tool removals already
happened on schedule** in the four months before this pack was written. A protocol
cutover held only in a chat transcript is precisely the failure that dated packs
exist to prevent, so every date below carries its consequence, not just its fact.

An auditor reading this pack past its `expires` date must say so in its findings
rather than silently trusting stale endpoints.

## 1. The cutover calendar

| Date | Event | Consequence |
|---|---|---|
| **2026-04-22** | Storefront Catalog MCP migrated to UCP | legacy tool names accepted through 2026-06-15 |
| **2026-06-15** | legacy catalog tool names **removed** | `search_*` / `lookup_*` no longer resolve; use `search_catalog` / `lookup_catalog` |
| **2026-06-24** | cart tools deprecated in favour of UCP Cart MCP | **the cutover happened here** — the new path is live from this date |
| **2026-08-31** | legacy `get_cart` / `update_cart` on `/api/mcp` **removed** | a consumer still on the old path stops working entirely |

**Read that table carefully, because the obvious misreading is expensive.**
2026-08-31 is a **removal** date, not a migration date. The migration opened on
2026-06-24 and the new endpoint is live now. There is nothing to wait for, and a
plan that schedules work "before the cutover" has already missed it.

Two removals landing on their announced dates is the evidence that matters here:
on this platform, deprecation notices are not advisory.

## 2. Endpoints, and which one needs a credential

| Server | Path | Tools | Auth |
|---|---|---|---|
| Cart MCP | `/api/ucp/mcp` on the shop domain | `create_cart`, `get_cart`, `update_cart`, `cancel_cart` | **none** |
| Checkout MCP | `/api/ucp/mcp` on the shop domain | `create_checkout`, `get_checkout`, `update_checkout`, `complete_checkout`, `cancel_checkout` | **OAuth bearer token** |
| Catalog MCP | `/api/ucp/mcp` on the shop domain | `search_catalog`, `lookup_catalog`, `get_product` | none |
| Legacy Storefront MCP | `/api/mcp` on the shop domain | policy/FAQ search survives; the two cart tools die 2026-08-31 | none |

**The auth asymmetry is a trap.** Cart and Catalog need no credential, so it is
natural to conclude the whole UCP path is credential-free. **Checkout MCP requires a
real bearer token.** A design built on "no credentials anywhere in this path" works
all the way through browsing and cart assembly and then fails at the one step that
moves money.

Contract details: JSON-RPC 2.0; every request carries `meta["ucp-agent"].profile`, a
URL to the calling agent's profile JSON. The three destructive operations —
`cancel_cart`, `complete_checkout`, `cancel_checkout` — additionally require
`meta["idempotency-key"]` as a UUID. Capability `dev.ucp.shopping.cart`, dated
version `2026-04-08`.

**`update_cart` has PUT semantics.** Each call replaces the full cart state; it is
not a patch. A caller that sends only the changed line silently discards the rest of
the cart.

## 3. Who serves the UCP profile — not us

The platform **generates** the business profile when agentic storefronts are enabled
and serves it at `{shop-subdomain}/.well-known/ucp` and on the managed checkout
domain. Platform staff answered this directly in the developer forums
(2026-01-29, updated 2026-07-27): there is *"not currently a supported way to edit or
replace that profile"*, and a consumer **should not host, proxy, or redirect it** —
including on a custom domain.

**So the correct posture on this platform is verify-and-report, never publish.** A
storefront may build an entirely independent implementation on its own
infrastructure, but it is *additional to* the managed endpoint, not a replacement.

Two consequences for anyone writing a profile-related contract:

- A **404 on the custom domain is expected**, not a defect. An audit that scores it
  red is wrong.
- Self-publishing belongs only to **non-platform storefronts**, and every place it
  appears must name the platform it applies to.

## 4. Catalog eligibility

Store level: the paid-plan floor or above; **not password-protected**; sells to
customers in the United States; **Terms of service, Privacy policy, and Return and
refund policy all completed**; the merchant has accepted the agentic-storefront
supplemental terms. Account standing additionally requires genuine sales history,
prompt fulfilment, low chargebacks, and identity verification.

Product level: a title and **at least one image**; price **greater than zero** —
free products are excluded outright; published to a storefront sales channel; an
identifiable product URL; not unlisted; not hidden from search engines.

Three notes that are easy to get wrong:

1. **The policy pages are an eligibility gate, not just a legal obligation.** A store
   missing them is invisible to every agentic channel regardless of its catalog.
2. **Development stores can never qualify** — they are permanently password-protected,
   so they fail the password gate rather than a named exclusion. Watch for records
   claiming a separate "trial store" rule; no such rule is published.
3. **Eligibility is earned by trading, not provisioned.** No freshly created store
   qualifies at birth. A factory can stamp everything else; it cannot stamp standing.
   Any plan promising "repo to agent-ready store in one session" is overclaiming — say
   so rather than designing around it.

## 5. The product route is a hard requirement

A headless storefront **must** use the expected route format to be included in the
agentic catalog. The standard is **`/products/<handle>`** with the platform's product
handle verbatim. A storefront using a different structure must provide a
**server-side 3XX redirect** from the expected path — client-side redirection does
not satisfy it.

**Do not localize or prefix the canonical product path.** A prettier URL is fine as
long as the canonical one still resolves.

**The catalog is fed from the platform's own product records, not by crawling
storefront HTML.** So structured data and sitemaps do **not** gate agentic-catalog
inclusion — they serve general search crawlers, which is a separate pipeline over the
same canonical product record. Conflating the two leads to auditing the wrong artifact.

## 6. Agent identity and rate limits

Higher rate limits for automated traffic are documented as reachable through
**RFC 9421 HTTP Message Signatures** (Web Bot Auth), which lets a well-behaved agent
identify itself cryptographically rather than being treated as anonymous traffic.

**Carried knowledge, not re-fetched this pass.** The RFC itself is stable, but the
platform-side mechanism for registering a signing key and the limits actually granted
were not verified on 2026-08-01. Treat the direction as sound and **re-verify the
specifics before building against them**; do not quote a limit number from this pack.

## 7. What a headless storefront owes agents

| Artifact | Status |
|---|---|
| the `/products/<handle>` route | **required** |
| product published to a storefront channel | **required** |
| `/.well-known/ucp` on the storefront domain | **do not build** — platform-managed |
| an MCP endpoint on the storefront domain | **do not build** — platform-managed |
| product feed | not required for the agentic catalog; still required for shopping-ad surfaces |
| `sitemap.xml`, `robots.txt` | the framework generates both |
| canonical URL | recommended |
| product structured data | recommended; effectively required for merchant listings on general search |
| `/llms.txt`, `/agents.md` | **must be hand-built on headless** — the platform's defaults are theme templates and a headless storefront renders none of them, so all such paths 404 |

**Non-production preview deployments are served a disallow-all robots file by
design.** Never diagnose agent visibility against a preview URL — an absence there
proves nothing.

## 8. Audit behaviour

An audit of this surface is never "compliant" as one flag. Classify per item, the
same discipline the disclosure-matrix and compliance packs use.

- **Treat pack expiry as blocking.** Past `expires`, report the staleness as a finding
  in its own right before reporting anything else.
- **A 404 for the profile on a custom domain is a PASS.** So is an empty agentic
  catalog for a store that has never traded. Classify correct-empty against
  broken-empty before scoring anything red.
- **Name the date and the source** for every protocol claim, so a reader can tell a
  current fact from a carried one.
- **Never assert a limit, endpoint, or tool name from memory.** Two tool families were
  renamed and removed within four months of this pack being written.

Wersje

W bazie nie ma innych skilli o nazwie agentic-surface.

Migawka bazy z 13.11.2026 · wersja paczki 055ac04a8667 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100ucp-cart
    Wdraża możliwość UCP Cart (dev.ucp.shopping.cart): lekki CRUD do zbierania pozycji przed zakupem i konwersję koszyka w sesję Checkout przez REST, MCP lub Embedded.
  • 90ucp-catalog
    Implementuje możliwość UCP Catalog: wyszukiwanie tekstowe i Lookup po identyfikatorach, model Product i Variant, media, oceny i jednostki ilości, do udostępniania katalogu agentom.
  • 100ucp
    Obsługuje UCP CLI do wyszukiwania, porównywania, kupowania i śledzenia produktów u internetowych sprzedawców oraz konfiguracji i diagnostyki lokalnego profilu UCP, koszyka, checkoutu i zamówień.
  • 100hydrogen-request-handlers
    Prowadzi podpięcie handlerów żądań Hydrogen w frameworkach serwerowych: trasy Shopify, przekierowania, proxy Storefront API, koszyk, konto klienta i przekierowania do checkoutu.
  • 100ucp-checker
    Wyszukuje sklepy obsługujące zakupy agentów AI i sprawdza, czy domena spełnia protokół UCP.
  • 100ucp-agent-ready
    Publikuje i naprawia profil UCP, dzięki któremu agenty AI odkryją sklep i zrealizują w nim zakup, z weryfikacją.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.