Skip to content
Source
Sign inSign up
TanStack/schemas
Open History to see the last commit

skill.ts

88 lines4.4 KB

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}\`. \`amount\` is in
54 \`currency\` (ISO 4217, mostly USD; never converted) and \`usd\` repeats it
55 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). Missing levers → 422; no card → 404
58 \`unknown_pricing\`. CLI: \`modelschemas estimate openai gpt-4o usage.json\`.
596. **Stay current.** Poll \`GET /v1/changes?since=<epoch>\` (cursor-paginated)
60 or subscribe: \`POST /v1/subscriptions\` (authed) delivers HMAC-signed
61 webhooks for model/schema changes.
62​
63## CLI quick reference
64​
65\`\`\`
66modelschemas login [--delegated|--api-key] # register this machine
67modelschemas whoami # identity, grants, usage
68modelschemas models list --activity chat --q claude
69modelschemas models get openrouter anthropic/claude-sonnet-4.5
70modelschemas schema get anthropic v1/messages --kind input
71modelschemas validate anthropic/v1/messages payload.json
72modelschemas estimate openai gpt-4o usage.json
73modelschemas changes --since 1781150000
74modelschemas subscribe https://my.app/hook --events model.added
75\`\`\`
76​
77Every command prints JSON (pretty in a TTY, compact when piped).
78​
79## MCP
80​
81The service is also an MCP server: streamable HTTP at \`{base}/mcp\` with
82tools \`list_models\`, \`get_model\`, \`get_schema\`, \`validate_payload\`,
83\`estimate_cost\`, \`recent_changes\`. OpenAPI assembly is HTTP-only
84(\`GET /v1/openapi/{provider}\`); MCP has no equivalent tool.
85​
86## Service reference (llms.txt, verbatim)
87​
88${llmsTxt}`