khotan-dataalpha
View as Markdown
Reference

Skills

khotan-data ships built-in agent skills — focused SKILL.md guides that teach a coding agent how to do one job well. Install the ones relevant to your task and your agent gets task-specific instructions on demand.

What is a skill?

A skill is a self-contained markdown guide that an AI coding agent reads before doing work. Each khotan skill covers a single area — the integration workflow, setup, plugs, flows, webhooks, caching, mappings, CLI debugging, or frontend — with the exact commands, patterns, and gotchas for that area. Skills are installed into your project's agent directories so tools like Cursor, Claude Code, and Codex can discover them automatically.

There is one orchestrator skill — khotan-build — that owns the end-to-end workflow and points to the focused skills at each step. Start there when integrating a service.

For the broader story of how agents should discover and consume khotan, see the Agent Guide. This page focuses on what each individual skill contains.

Installing skills

Skills install into every detected agent location (for example .cursor/skills/<name>/SKILL.md and .claude/skills/<name>/SKILL.md). Running npx khotan init --yes installs all of them and auto-accepts; you can also add any skill individually:

terminal
$ npx khotan add skill-build
$ npx khotan add skill-setup
$ npx khotan add skill-plug
$ npx khotan add agent-skill
$ npx khotan add skill-flow
$ npx khotan add skill-webhook
$ npx khotan add skill-cache
$ npx khotan add skill-mappings
$ npx khotan add skill-frontend

khotan-build

terminal
$ npx khotan add skill-build

The orchestrator. Teaches an agent the full, end-to-end workflow for integrating an external service — from reading the service docs to a working sync — and the consent gates that keep it safe. Start here; it delegates the "how" of each step to the focused skills below.

Use it when

  • a user points at a service (docs, a link, markdown) and wants data flowing
  • the request is "connect to X", "sync X", "pull/push data from X"

What it covers

  • the numbered workflow: ensure setup → credential/env triage → build the plug → verify endpoints → flows/webhooks → frontend
  • credential triage: which values are env vars vs encrypted plug vars, and the base khotan vars to check (DATABASE_URL, KHOTAN_SECRET, KHOTAN_DEBUG)
  • the consent gates an agent must stop at: scope, mutations, flows/webhooks, and frontend
  • the "quick-fire, disclosed" principle — ship the smallest working version (one page of pagination) and say so

khotan-setup

terminal
$ npx khotan add skill-setup

Foundation reference. Teaches an agent how to stand up khotan-data in a Next.js + Drizzle + Postgres project and how to recover when the base is incomplete.

Use it when

  • initializing khotan in a new or existing project
  • adding the database schema and running migrations
  • configuring the factory in khotan.ts
  • securing the management API or fixing middleware/workflow interception

What it covers

  • what khotan init scaffolds — khotan.config.ts, the factory khotan.ts, and the catch-all API route
  • the factory config pattern: registering adapter, resources, and plugs
  • database setup with khotan add schema and khotan migrate, and the tables it creates
  • environment variables and credential triage (DATABASE_URL, KHOTAN_SECRET, KHOTAN_DEBUG, KHOTAN_WEBHOOK_URL, CRON_SECRET)
  • securing the management API with the authorize hook
  • the workflow/middleware matcher gotcha and common troubleshooting fixes

khotan-plug

terminal
$ npx khotan add skill-plug

Teaches an agent how to author and configure Plugs — the HTTP clients khotan uses to talk to external APIs — with auth, retry, pagination, and typed endpoints.

Use it when

  • connecting to a new external API
  • defining endpoint contracts with Zod schemas
  • configuring authentication or token exchange
  • creating a typed API client and verifying it against the live API

What it covers

  • auth strategies: bearer, basic, apiKey, custom, and tokenExchange
  • runtime vars stored encrypted via KHOTAN_SECRET and managed in the Hub
  • typed endpoints, hooks (beforeRequest, afterResponse, onUnauthorized)
  • registering the plug in the factory with resources and flows
  • the recommended plug workflow: scaffold → add typed endpoints → verify with khotan plug --compare → build flows
  • the scope and mutation gates that apply while building

khotan-probe

terminal
$ npx khotan add agent-skill

Teaches an agent how to inspect and debug plugs from the CLI using khotan plug (legacy alias khotan probe) — verifying real API responses against your typed endpoint definitions.

Use it when

  • verifying API response shapes against typed endpoints
  • debugging mismatches between declared schemas and actual responses
  • exploring available plugs and their endpoints

What it covers

  • the headline safety rule: probe GET endpoints freely, but require explicit consent before firing any non-GET
  • listing plugs (--list) and inspecting endpoints (--info)
  • firing requests by raw method/path or by named endpoint
  • comparing responses against Zod schemas with --compare and reading the mismatch output
  • the discover → probe → compare → fix loop, and the running dev server with KHOTAN_DEBUG=1 requirement

khotan-flow

terminal
$ npx khotan add skill-flow

Teaches an agent how to build and run Flows — durable inflows (pull data in), outflows (push data out), and relays (move data plug-to-plug) on Vercel Workflow.

Use it when

  • pulling data from a service into your app (inflow)
  • pushing app data out to a service (outflow)
  • moving data directly between two services (relay)
  • scheduling or manually triggering a flow

What it covers

  • choosing between inflow, outflow, and relay
  • the "use step" (top level) / "use workflow" (orchestration only) authoring rule
  • registering flows on a plug and the quick-fire single-page default
  • triggering with khotanData.flow(name).start(), the khotan flows trigger CLI, and the HTTP route
  • run types (full, delta, backfill, reconcile, dry-run) and scheduling on Vercel via a single cron dispatcher

khotan-webhook

terminal
$ npx khotan add skill-webhook

Teaches an agent how to receive and process webhooks with Wires, Catch, and Pass — registering subscriptions, verifying signatures, and handling events durably.

Use it when

  • receiving webhooks from an external service
  • registering callback URLs and verifying signatures
  • processing incoming events durably via Vercel Workflow
  • forwarding events from one service to another

What it covers

  • creating a Wire with onSubscribe, onUnsubscribe, and onVerify hooks, and their contexts
  • registering wires on a plug and the programmatic wire API
  • the webhook callback URL convention and local-dev tunneling
  • Catch for durable event processing and Pass for forwarding events to another service
  • the end-to-end webhook flow, dependency requirements, and debugging (401 vs 500 causes)

khotan-cache

terminal
$ npx khotan add skill-cache

Teaches an agent how to add first-class durable caching to flows and webhooks — named caches with scope and TTL for upstream snapshots, checkpoints, and dedupe markers.

Use it when

  • a flow re-fetches the same expensive upstream data every run
  • you need to compare current vs previous between runs (delta detection)
  • the user asked for caching or snapshots

What it covers

  • defining a cache with name, scope, and ttl, and registering it in the factory
  • using khotanCache(ctx, name) inside a workflow step (.get, .set, .delete)
  • where caching fits in flows, relays, catches, and passes

khotan-mappings

terminal
$ npx khotan add skill-mappings

Teaches an agent how to define resources and manage cross-service record mappings — a canonical connect key plus per-plug refs so the same entity is matched and deduped across services.

Use it when

  • you need record matching or dedupe across systems
  • a flow needs idempotent upserts keyed by a stable external identifier
  • the user asked about mappings, connect fields, or external IDs

What it covers

  • declaring resources and connectField (single or composite) in the factory
  • the mappings CLI: list, lookup, upsert, update, delete
  • using mappings to keep upserts idempotent across full/delta/backfill runs
  • the optional Mapping Browser UI

khotan-frontend

terminal
$ npx khotan add skill-frontend

Teaches an agent how to suggest khotan frontend — drop-in components and ready-made page blocks — and, critically, to never inject UI or add routes without confirmation.

Use it when

  • the user wants a browser UI to manage, debug, or observe khotan
  • deciding between drop-in components and ready-made pages

What it covers

  • the hard rules: never scaffold UI or add a route without explicit confirmation, never invent paths, prefer components over blocks
  • the component catalog (Hub, plug debugger, logs, mapping browser)
  • the block catalog with fixed routes (/config, /debug, /logs, /mappings, /graph)
  • shadcn prerequisites, --without-ui, and securing management pages with your own middleware

Which skill should I install?

  • Integrating a service end to end → khotan-build (start here)
  • Standing up or repairing the foundation → khotan-setup
  • Connecting an API → khotan-plug (then khotan-probe to verify it)
  • Pulling/pushing/syncing data → khotan-flow
  • Handling webhooks → khotan-webhook
  • Caching upstream snapshots → khotan-cache
  • Matching records across services → khotan-mappings
  • Adding management/debug UI → khotan-frontend

If you are an agent, also read the Agent Guide for the recommended reading order and practical workflow.