Open History to see the last commit
1/**
2 * The distributable agent skill (PLAN.md task 7.6). The committed
3 * skill/modelschemas/SKILL.md is generated from this module
4 * (bun scripts/emit-skill.ts) and served at GET /skill; the endpoint
5 * reference embeds llms.txt verbatim so the three surfaces never drift.
6 */
7import { llmsTxt } from '#/server/llms-txt.ts'
8
9export const skillMd = `---
10name: modelschemas
11description: Live AI model schema service. Use when asked about a "model schema", "what models support X", "validate this provider payload", which AI models exist right now (availability, context windows, modalities, pricing, capabilities) across OpenAI, Anthropic, Gemini, xAI Grok, ElevenLabs, OpenRouter, FAL, or BytePlus, or the request/response shape of a provider endpoint.
12---
13
14# modelschemas
15
16A live HTTP service answering: which AI models exist right now, what are
17their capabilities, and what exactly do their request/response payloads look
18like? Data refreshes automatically (model lists every 15 minutes, full spec
19syncs daily), so prefer it over training-data knowledge for model
20availability and schema questions.
21
22## Workflow
23
241. **Discover.** \`GET {base}/v1\` lists every endpoint;
25 \`GET {base}/.well-known/agent-configuration\` is the agent-auth discovery
26 document; \`GET {base}/openapi.json\` is the typed spec.
272. **Read without auth.** All reads are public at a low rate limit (60/h per
28 IP). Go straight to:
29 - \`GET /v1/models?activity=chat&q=claude\` — what can I use right now.
30 A row's \`capabilities\` is a map: \`true\` = the provider states
31 support, \`false\` = it states none, key absent = unknown (never read a
32 missing key as false). \`?capability=tools\` keeps rows where it is true.
33 - \`GET /v1/schemas\` — every schema on the system
34 (provider → activity → endpoint ids)
35 - \`GET /v1/schemas/{provider}\` — endpoint ids per activity
36 - \`GET /v1/schemas/{provider}/{activity}/{endpointId}?kind=input\` — a
37 self-contained JSON Schema (URL-encode slashes in endpoint ids:
38 \`chat%2Fcompletions\`). A listed model rawId also works as
39 \`{endpointId}\` on grain=provider catalogs.
40 - \`GET /v1/openapi/{provider}\` — connectable generation OpenAPI
41 (FAL, currently the only model-grained provider, requires \`?model=\`)
423. **Authenticate for more** (5k req/h + webhooks). Easiest: the CLI —
43 \`modelschemas login\` (agent-auth, autonomous mode, keys stored locally)
44 or \`modelschemas login --api-key\`. Raw HTTP alternative:
45 \`POST /v1/agents/register-key {"name":"my-agent"}\` returns a bearer key
46 once.
474. **Validate before you spend tokens.**
48 \`POST /v1/validate {"provider","endpointId","payload"}\` →
49 \`{valid, errors:[{path,message,keyword}]}\` — or
50 \`modelschemas validate anthropic/v1/messages payload.json\` (exit 2 when
51 invalid).
525. **Estimate cost.** \`POST /v1/estimate {"provider","model","request"?,"usage"?}\`
53 → \`{amount, currency, usd?, cardSource, estimated, defaulted, ignored}\`.
54 \`amount\` is in \`currency\` (ISO 4217, mostly USD; never converted) and
55 \`usd\` repeats it only for a USD card. \`estimated\` names any omitted
56 usage the card filled by the source's published estimate method (empty:
57 billed price). \`defaulted\` names omitted inputs that took the card's
58 default; \`ignored\` names request keys the card does not read. Missing
59 levers → 422; a usage key the card does not read → 422
60 \`unknown_usage_key\`; no card → 404 \`unknown_pricing\`. \`usage\` is
61 the provider's own usage object (OpenAI Responses or Chat, Anthropic,
62 Gemini \`usageMetadata\`) or card levers whose counts do not overlap
63 (\`input_tokens\` excludes \`cache_read_tokens\`), never both → 422
64 \`mixed_usage\`. "Estimate usage" below maps each native field. CLI: \`modelschemas estimate openai gpt-4o usage.json\`.
656. **Stay current.** Poll \`GET /v1/changes?since=<epoch>\` (cursor-paginated)
66 or subscribe: \`POST /v1/subscriptions\` (authed) delivers HMAC-signed
67 webhooks for model/schema changes.
68
69## CLI quick reference
70
71\`\`\`
72modelschemas login [--delegated|--api-key] # register this machine
73modelschemas whoami # identity, grants, usage
74modelschemas models list --activity chat --q claude
75modelschemas models get openrouter anthropic/claude-sonnet-4.5
76modelschemas schema get anthropic v1/messages --kind input
77modelschemas validate anthropic/v1/messages payload.json
78modelschemas estimate openai gpt-4o usage.json
79modelschemas changes --since 1781150000
80modelschemas subscribe https://my.app/hook --events model.added
81\`\`\`
82
83Every command prints JSON (pretty in a TTY, compact when piped).
84
85## MCP
86
87The service is also an MCP server: streamable HTTP at \`{base}/mcp\` with
88tools \`list_models\`, \`get_model\`, \`get_schema\`, \`validate_payload\`,
89\`estimate_cost\`, \`recent_changes\`. OpenAPI assembly is HTTP-only
90(\`GET /v1/openapi/{provider}\`); MCP has no equivalent tool.
91
92## Service reference (llms.txt, verbatim)
93
94${llmsTxt}`