Reference

Agent Guide

If you are a coding agent working in a project that uses khotan-data, the most important fact to know is this: khotan ships built-in skills for agents.

Those skills are part of the package itself, and they should usually be your first stop before making substantial khotan changes.

The fastest agent setup path

terminal

$ npm install khotan-data
$ npx khotan init --yes

--yes matters because it auto-accepts the skill installation prompt.

What gets installed for agents

a project-root AGENTS.md
one skill directory per installed khotan skill in each detected agent location

Detected agent locations:

Cursor: .cursor/skills/<skill-name>/SKILL.md
Claude Code: .claude/skills/<skill-name>/SKILL.md
Codex: .agents/skills/<skill-name>/SKILL.md
Copilot: .github/skills/<skill-name>/SKILL.md
Kiro: .kiro/skills/<skill-name>/SKILL.md
Roo: .roo/rules/<skill-name>/SKILL.md

If none of those agent directories exist yet, khotan defaults to Cursor plus Claude Code.

Built-in skills

khotan installs one orchestrator skill plus eight focused skills. Start from khotan-build — it owns the end-to-end workflow and the consent gates, and points to the others at each step. See the Skills reference for the full contents of each.

khotan-build (add skill-build) — integrating a service end to end; the workflow and consent gates. Start here.
khotan-setup (add skill-setup) — init, schema, factory registration, securing the API, middleware fixes
khotan-plug (add skill-plug) — plug authoring, auth strategies, typed endpoints
khotan-probe (add agent-skill) — the khotan plug CLI; verifying endpoint shapes, GET-first
khotan-flow (add skill-flow) — inflows, outflows, relays; triggering and scheduling
khotan-webhook (add skill-webhook) — wire registration, verification, Catch and Pass handlers
khotan-cache (add skill-cache) — durable caching of snapshots, checkpoints, dedupe markers
khotan-mappings (add skill-mappings) — resources and cross-service record matching/dedupe
khotan-frontend (add skill-frontend) — suggesting UI components/blocks; never adds UI or routes unprompted

The consent gates

The khotan-build workflow stops and asks the user at four points. An agent following the skills should honor these rather than improvising:

Scope— if the integration's scope is unclear, ask before building.
Mutations — probe GET endpoints freely; never fire POST/PATCH/PUT/DELETE against a live service without explicit consent.
Flows/webhooks — after the plug is verified, ask which flows and webhook handlers are wanted.
Frontend — never add UI or routes on your own; ask what (if any) frontend the user wants.

Best docs format for agents

The docs site mirrors major pages as raw markdown. Prefer those routes when you want to extract or summarize documentation:

/docs.md
/docs/installation.md
/docs/basic-usage.md
/docs/configuration.md
/docs/how-it-works.md
/docs/cli.md
/docs/components.md
/docs/blocks.md
/docs/agents.md

Practical agent workflow

Check whether the project already has AGENTS.md.
Read the relevant khotan skill.
Inspect khotan.ts to see registered plugs, resources, flows, wires, catches, and passes.
Use khotan plug, khotan wire, and khotan flows for live inspection when the app is running.
Prefer blocks when the request is "show the UI quickly".

Commands agents should know