---
title: Agent Guide
description: How coding agents should discover khotan, install its built-in skills, and consume the docs efficiently.
section: Reference
url: /docs/agents
---

# 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

If khotan has not been initialized yet:

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

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

## What gets installed for agents

When skills are installed, khotan writes:

- 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](/docs/skills) for the full contents of each.

| Skill | Installed with | Use for |
|-------|----------------|---------|
| `khotan-build` | `npx khotan add skill-build` | Integrating a service end to end — the workflow and consent gates. Start here. |
| `khotan-setup` | `npx khotan add skill-setup` | Init, schema, factory registration, securing the API, middleware fixes |
| `khotan-plug` | `npx khotan add skill-plug` | Plug authoring, auth strategies, typed endpoints |
| `khotan-probe` | `npx khotan add agent-skill` | The `khotan plug` CLI — verifying endpoint shapes, GET-first |
| `khotan-flow` | `npx khotan add skill-flow` | Inflows, outflows, relays; triggering and scheduling |
| `khotan-webhook` | `npx khotan add skill-webhook` | Wire registration, verification, Catch and Pass handlers |
| `khotan-cache` | `npx khotan add skill-cache` | Durable caching of snapshots, checkpoints, dedupe markers |
| `khotan-mappings` | `npx khotan add skill-mappings` | Resources and cross-service record matching/dedupe |
| `khotan-frontend` | `npx khotan 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.

## Recommended reading order for agents

When entering a khotan project, read in this order:

1. project-root `AGENTS.md`
2. this page
3. `khotan-build` (the workflow orchestrator)
4. `/docs/components.md`
5. `/docs/cli.md`
6. the specific skill relevant to the current step

Then read the project's local `khotan.ts` and generated component files.

## 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`

Use the rendered pages for browsing. Use the `.md` routes for ingestion.

## Practical agent workflow

For most khotan tasks:

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

## Commands agents should know

```terminal
$ npx khotan init --yes
$ npx khotan add plug --yes
$ npx khotan add wire --yes
$ npx khotan add catch --yes
$ npx khotan add pass --yes
$ npx khotan add inflow --yes
$ npx khotan add hub --yes
$ npx khotan add runs --yes
$ npx khotan add logs --yes
$ npx khotan add config-page-1 --yes
$ npx khotan plug --list
$ npx khotan wire --list
$ npx khotan flows list
```

## Key idea

An agent working on khotan should not treat khotan as just another package dependency. It is also a documentation and skill distribution system for agents. The package expects agents to use those skills.