# Build with an AI agent

> The Markdown copies, llms.txt and llms-full.txt this site serves for AI tools, the buttons on every page, and the agent skill you can install.

Every page of this site is also served as plain Markdown, so an AI coding agent or a chat assistant can read the docs without guessing.

## Files for AI tools

| File | What it holds |
|---|---|
| [`/llms.txt`](https://docs.kosoor.com.sa/llms.txt) | an index of every page, with instructions for AI agents at the top |
| [`/llms-full.txt`](https://docs.kosoor.com.sa/llms-full.txt) | every guide and every endpoint contract (paths, parameters, request and reply fields) in one file |
| any page with `.md` added | that page as Markdown, for example [`/record-a-sale.md`](https://docs.kosoor.com.sa/record-a-sale.md); the home page is `/index.md` |
| [`/skill/kosoor-merchant-api/SKILL.md`](https://docs.kosoor.com.sa/skill/kosoor-merchant-api/SKILL.md) | an agent skill: the rules of this API in one short file |

The Arabic site has its own copies under `/ar`, such as `/ar/llms.txt`.

## On every page

Above every page are four buttons:

- **Copy page as Markdown** copies the page, ready to paste into a chat.
- **View as Markdown** opens the page's `.md` copy.
- **Open in Claude** and **Open in ChatGPT** start a chat that reads the page.

## Install the agent skill

The skill gives an AI coding agent the rules that matter most when it writes code against this API: send an `Idempotency-Key`, branch on `code`, build with a test key, take ids from the catalogue, and where to read the rest.

For Claude Code, save it as a project skill, so everyone working on the repository gets it:

```bash
mkdir -p .claude/skills/kosoor-merchant-api
curl -fsSL https://docs.kosoor.com.sa/skill/kosoor-merchant-api/SKILL.md \
  -o .claude/skills/kosoor-merchant-api/SKILL.md
```

Or as a personal skill, for every project on your machine:

```bash
mkdir -p ~/.claude/skills/kosoor-merchant-api
curl -fsSL https://docs.kosoor.com.sa/skill/kosoor-merchant-api/SKILL.md \
  -o ~/.claude/skills/kosoor-merchant-api/SKILL.md
```

Claude Code loads the skill when a task involves the Kosoor API. For another agent, add the file's contents to the instructions that agent reads, or point it at `https://docs.kosoor.com.sa/llms.txt`.

## Give the agent a test key

Let the agent build and run against the sandbox with a test key (`ksr_test_...`), never a live one. Put the key in an environment variable or a local file your repository ignores, not in the prompt or the code. See [Test mode](https://docs.kosoor.com.sa/test-mode.md).

Source: https://docs.kosoor.com.sa/ai-agents