feat(discovery): buildSkillMd renderer for /skill.md agent surface

CLAUDE.md

@@ -11,7 +11,7 @@ Every helper is extracted from a real consumer, not speculated.
 | `@agent-score/commerce/identity/{hono,express,fastify,nextjs,web}` | Trust gate middleware (KYC, age, sanctions, jurisdiction) |
 | `@agent-score/commerce/identity/policy` | Framework-agnostic per-product / per-tier compliance policy helpers — `PolicyBlock`, `policyToGateOptions`, `runGateWithEnforcement`, `shippingCountryAllowed`, `shippingStateAllowed` |
 | `@agent-score/commerce/payment` | Networks/USDC/rails registries, paymentauth.org directive builders, x402 server factory + scheme dual-register, MPP server factory, dispatch-by-network, signer extraction, WWW-Authenticate header, Settlement-Overrides header |
-| `@agent-score/commerce/discovery` | Discovery probe middleware, Bazaar wrapper, `/.well-known/mpp.json` builder, `llms.txt` builder, OpenAPI snippets, `noindexNonDiscoveryPaths` Hono middleware |
+| `@agent-score/commerce/discovery` | Discovery probe middleware, Bazaar wrapper, `/.well-known/mpp.json` builder, `llms.txt` builder, `skill.md` builder (Claude-Skill-compatible agent-discovery manifest), OpenAPI snippets, `noindexNonDiscoveryPaths` Hono middleware |
 | `@agent-score/commerce/challenge` | 402-body builders: accepted_methods, identity metadata, how_to_pay, agent_instructions, build402Body, `buildValidationError` (4xx body builder) |
 | `@agent-score/commerce/stripe-multichain` | Multichain PaymentIntent helper, deposit-address lookup, testnet simulator, mppx Stripe wrapper |
 | `@agent-score/commerce/api` | Re-exports `AgentScore` + `AgentScoreError` from `@agent-score/sdk` |
@@ -25,7 +25,7 @@ Single TypeScript package, tsup-built CJS + ESM with subpath exports. Per-framew
 | `src/identity/` | Per-framework gate adapters (hono, express, fastify, nextjs, web) |
 | `src/core.ts` | Shared assess/session/cache/captureWallet (framework-agnostic) |
 | `src/payment/` | Payment-protocol helpers (`networks.ts`, `usdc.ts`, `rails.ts`, `directive.ts`, `dispatch.ts`, `signer.ts`, `wwwauthenticate.ts`, `settlement_override.ts`, `x402.ts`, `x402_server.ts`, `mppx_server.ts`) |
-| `src/discovery/` | Probe + Bazaar + `/.well-known/mpp.json` + `llms.txt` + OpenAPI |
+| `src/discovery/` | Probe + Bazaar + `/.well-known/mpp.json` + `llms.txt` + `skill.md` + OpenAPI |
 | `src/challenge/` | 402-body builders |
 | `src/stripe-multichain/` | Stripe multichain PaymentIntent helpers |
 | `src/api/` | `AgentScore` re-export from sdk |

README.md

@@ -25,7 +25,7 @@ npm install hono mppx @x402/core @x402/evm @x402/svm stripe   # whatever your st
 |---|---|
 | `/identity/{hono,express,fastify,nextjs,web}` | Trust gate middleware: KYC, sanctions, age, jurisdiction. `agentscoreGate(...)`, `getAgentScoreData(c)`, `captureWallet(...)`, `verifyWalletSignerMatch(...)`. Plus shared denial helpers: `denialReasonStatus`, `denialReasonToBody`, `buildSignerMismatchBody`, `buildContactSupportNextSteps`, `verificationAgentInstructions`, `isFixableDenial`, `FIXABLE_DENIAL_REASONS`. |
 | `/payment` | `networks`, `USDC`, `rails` registries; `paymentDirective`, `buildPaymentDirective`, `wwwAuthenticateHeader`, `paymentRequiredHeader`, `aliasAmountFields` (v1↔v2 amount field shim — emits both `amount` and `maxAmountRequired` so v1-only x402 parsers like Coinbase awal can read v2 bodies), `settlementOverrideHeader`, `dispatchSettlementByNetwork`, `extractPaymentSigner` (returns `{address, network}`); `createX402Server`, `createMppxServer`; drop-in x402 helpers: `validateX402NetworkConfig` (boot-time guard), `verifyX402Request` (parse + validate inbound X-Payment), `processX402Settle` (verify-then-settle with one call). |
-| `/discovery` | `isDiscoveryProbeRequest`, `buildDiscoveryProbeResponse` (with optional `x402Sample` for x402-aware crawlers — `awal x402 details` etc.), `sampleX402AcceptForNetwork` (USDC sample-accept builder for known CAIP-2 networks), `buildWellKnownMpp`, `buildLlmsTxt` + `llmsTxtIdentitySection` + `llmsTxtPaymentSection` (compact + verbose modes), `agentscoreOpenApiSnippets`, `createBazaarDiscovery`, `noindexNonDiscoveryPaths` (Hono middleware that emits `X-Robots-Tag: noindex` on every path except the agent-discovery surfaces — defaults cover `/openapi.json`, `/llms.txt`, `/.well-known/{mpp.json,agent-card.json,ucp}`, `/favicon.{png,ico}`; pure helpers `isDiscoveryPath` + `defaultDiscoveryPaths` for non-Hono frameworks). |
+| `/discovery` | `isDiscoveryProbeRequest`, `buildDiscoveryProbeResponse` (with optional `x402Sample` for x402-aware crawlers — `awal x402 details` etc.), `sampleX402AcceptForNetwork` (USDC sample-accept builder for known CAIP-2 networks), `buildWellKnownMpp`, `buildLlmsTxt` + `llmsTxtIdentitySection` + `llmsTxtPaymentSection` (compact + verbose modes), `buildSkillMd` (Claude-Skill-compatible `/skill.md` agent-discovery manifest — strictly agent-facing data only, no internal posture), `agentscoreOpenApiSnippets`, `createBazaarDiscovery`, `noindexNonDiscoveryPaths` (Hono middleware that emits `X-Robots-Tag: noindex` on every path except the agent-discovery surfaces — defaults cover `/openapi.json`, `/llms.txt`, `/skill.md`, `/.well-known/{mpp.json,agent-card.json,ucp}`, `/favicon.{png,ico}`; pure helpers `isDiscoveryPath` + `defaultDiscoveryPaths` for non-Hono frameworks). |
 | `/challenge` | `build402Body`, `buildAcceptedMethods`, `buildIdentityMetadata`, `buildHowToPay`, `buildAgentInstructions` (auto-emits per-rail `compatible_clients` — smoke-verified CLIs the agent should use; vendor override supported), `buildPricingBlock`, `firstEncounterAgentMemory`, `OrderReceipt`; `respond402` — drop-in 402 emit that preserves mppx's `WWW-Authenticate` and layers x402's `PAYMENT-REQUIRED`. `buildValidationError` — structured 4xx body builder (`{error: {code, message}, required_fields?, example_body?, next_steps?, ...extra}`) so vendors compose body shapes by name instead of inlining at every validation site. |
 | `/stripe-multichain` | `createMultichainPaymentIntent`, `getDepositAddress`, `simulateCryptoDeposit`, `createMppxStripe`; `createPiCache` (TTL'd PI / deposit-address cache, Redis-backed when `redisUrl` set, in-memory otherwise), `simulateDepositIfTestMode` (gates on `sk_test_` and looks up the PI for you), `STRIPE_TEST_TX_HASH_SUCCESS` / `STRIPE_TEST_TX_HASH_FAILED` constants. Peer dep on `stripe`. |
 | `/api` | Everything from `@agent-score/sdk` re-exported in one place: `AgentScore` + `AgentScoreError`, `AGENTSCORE_TEST_ADDRESSES` + `isAgentScoreTestAddress`. **Don't add `@agent-score/sdk` as a separate dep** — the two can drift versions and cause subtle type mismatches. |

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-score/commerce",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Agent commerce SDK — identity middleware (Hono, Express, Fastify, Next.js, Web Fetch) + payment helpers + 402 builders + discovery + Stripe multichain. The full merchant-side toolkit for AgentScore-powered agent commerce.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

src/challenge/agent_instructions.ts

@@ -76,15 +76,36 @@ function defaultWarnings(howToPay: HowToPayBlock): string[] {
  * for humans (rationale, per-rail commands, why some clients don't fully work, last
  * verified date) — this default keeps the merchant-side surface in sync.
  */
-function defaultCompatibleClients(howToPay: HowToPayBlock): CompatibleClients | undefined {
+/** Symbolic rail keys agent-facing surfaces use to talk about a rail without spelling out
+ *  network/scheme details. Same keys as `CompatibleClients` map keys. */
+export type RailKey = 'tempo_mpp' | 'x402_base' | 'x402_solana' | 'stripe';
+
+const RAIL_CLIENTS: Record<RailKey, readonly string[]> = {
+  tempo_mpp: ['agentscore-pay', 'tempo request', 'x402-proxy'],
+  x402_base: ['agentscore-pay', 'x402-proxy', 'purl (omit --network flag)'],
+  x402_solana: ['agentscore-pay'],
+  stripe: ['link-cli'],
+};
+
+/** Returns the smoke-verified client list for a set of rail keys. The single source of
+ *  truth for "which CLIs we've verified end-to-end on each rail" — consumed both by the
+ *  402-body builder (`defaultCompatibleClients`) and by discovery surfaces (skill.md,
+ *  llms.txt, etc.). Update here, every surface inherits. */
+export function compatibleClientsByRails(rails: readonly RailKey[]): CompatibleClients | undefined {
   const out: CompatibleClients = {};
-  if (howToPay.tempo) out.tempo_mpp = ['agentscore-pay', 'tempo request', 'x402-proxy'];
-  if (howToPay.x402_base) out.x402_base = ['agentscore-pay', 'x402-proxy', 'purl (omit --network flag)'];
-  if (howToPay.x402_solana) out.x402_solana = ['agentscore-pay'];
-  if (howToPay.stripe) out.stripe = ['link-cli'];
+  for (const r of rails) out[r] = [...RAIL_CLIENTS[r]];
   return Object.keys(out).length === 0 ? undefined : out;
 }
 
+function defaultCompatibleClients(howToPay: HowToPayBlock): CompatibleClients | undefined {
+  const rails: RailKey[] = [];
+  if (howToPay.tempo) rails.push('tempo_mpp');
+  if (howToPay.x402_base) rails.push('x402_base');
+  if (howToPay.x402_solana) rails.push('x402_solana');
+  if (howToPay.stripe) rails.push('stripe');
+  return compatibleClientsByRails(rails);
+}
+
 /**
  * Build the agent_instructions object for the 402 body. Combines how_to_pay with
  * recommended tools, warnings, wallet-compatibility note, and timeout.

src/discovery/index.ts

@@ -4,3 +4,4 @@ export * from './well_known_mpp';
 export * from './llms_txt';
 export * from './openapi';
 export * from './robots_tag';
+export * from './skill_md';

src/discovery/robots_tag.ts

@@ -12,6 +12,8 @@
 export const defaultDiscoveryPaths: ReadonlySet<string> = new Set([
   '/openapi.json',
   '/llms.txt',
+  '/skill.md',
+  '/SKILL.md',
   '/.well-known/mpp.json',
   '/.well-known/agent-card.json',
   '/.well-known/ucp',