# Develop With AI

KOS Developers provides documentation for both humans and AI agents. When using AI, do not ask the agent to download every document by default. Ask it to read the documentation map first, then fetch only the pages needed for the task.

## Recommended Path

If your AI agent supports skills, install the KOS Developers skills.

```sh
npx skills add https://developers.kos-solution.com
```

To check whether the skill is discoverable without installing it, list the available skills.

```sh
npx skills add https://developers.kos-solution.com --list
```

This installs three skills. The common skill chooses the language and product path, the OpenAPI skill handles API contracts and auth, and the KOS Connect skill handles widget setup, appId, and client runtime constraints. These skills are not API-calling tools; they are documentation workflows that tell the agent to read `llms.txt`, individual Markdown pages, and `openapi.yaml` only when exact API contracts are needed.

## If You Cannot Install The Skill

Give the agent this reading order.

1. Read `/en/skill.md` or `/en/.well-known/agent-skills/kos-developers/SKILL.md`.
2. Read the `llms.txt` file for the user's language.
3. Use the page index in `llms.txt` to fetch only the needed Markdown pages.
4. Check `openapi.yaml` only when exact OpenAPI request, response, schema, or error variants are needed.
5. Use `docs.zip` only when broad cross-document search is genuinely necessary. If a zip was already downloaded, compare `docs-manifest.json` or `docs.zip.sha256` and re-download only when it changed.

| Purpose | Path |
| --- | --- |
| Full documentation map | `/llms.txt` |
| Japanese documentation map | `/ja/llms.txt` |
| English documentation map | `/en/llms.txt` |
| Common skill | `/en/skill.md` |
| OpenAPI skill | `/en/.well-known/agent-skills/kos-openapi/SKILL.md` |
| KOS Connect skill | `/en/.well-known/agent-skills/kos-connect/SKILL.md` |
| Skill discovery | `/en/.well-known/agent-skills/index.json` |
| OpenAPI source spec | `/en/openapi.yaml` |

## Choose The Product Path First

Good AI answers start by choosing the correct product path.

| Path | When to choose it |
| --- | --- |
| KOS Connect | Use this when embedding a ready-made booking journey into a clinic website, campaign page, or LINE. Questions about npm package setup, Script tag setup, opening the widget, starting reservations, language changes, and GA4/GTM events belong here. |
| OpenAPI | Use this when directly reading KOS data and building custom UI and server flows. Questions about products, categories, options, prices, reservation slots, reservation creation, clients, purchase data, requests, responses, errors, and schemas belong here. |
| Guide | Use this first when planning a new integration or combining multiple APIs, such as treatment menu and reservation flows. |

If an external developer is only adding buttons, widgets, or LINE booking entry points to a clinic website or campaign page, start with KOS Connect in most cases. If they are reading KOS data from their own server or implementing reservation and purchase flows directly, use OpenAPI. In that case, first confirm whether they are the development team for a clinic using KOS or a partner team working with that clinic, and whether API Key access and permissions are ready.

If the question is ambiguous, decide by who owns the screen. If the team is building its own screen and server, use OpenAPI. If the team is embedding the booking screen provided by KOS, use KOS Connect.

## If You Are A New External Developer

Before asking AI for implementation details, prepare these facts first.

- Whether your scope is only clinic-site buttons, widgets, or LINE booking entry points, or also includes custom screens and server flows
- Whether the target clinic uses KOS and whether your team is a partner development team working with that clinic
- Whether you need a KOS Connect `appId` or OpenAPI `API Key` and permissions
- Whether you are validating in development or working toward a scheduled production rollout
- Whether your environment can use the npm package with React/TypeScript or can only insert a Script tag

Providing this context helps AI avoid mixing up KOS Connect and OpenAPI, then point you to the right docs and next action.

## Prompt Examples

```text
Answer using the KOS Developers documentation.
First decide whether this is KOS Connect, OpenAPI, or Guide.
Fetch only the needed Markdown pages and openapi.yaml when exact API details are required.
Do not guess anything that is not confirmed by the docs.
End with the public documentation URLs you used.

Question:
We want a reservation button on a React clinic website to open the KOS Connect widget.
Should we use the npm package or Script tag, and what should we watch out for in development and production?
```

```text
Answer using the KOS Developers documentation.
We are building our own reservation UI and server flow.
Check reserveV2 method/path, authentication, required request fields, 400 oneOf error variants,
and linked schema docs, then summarize this as an implementation checklist.
```

## What To Tell The AI

When asking AI for help, include the screen you are building and who owns the user flow. For example, say whether you are embedding the KOS booking screen into a clinic website or building your own booking UI and server.

For KOS Connect, include your framework, where the widget-opening button lives, whether you prefer the npm package or Script tag setup, and whether you separate development and production appIds.

For OpenAPI, include the server-side feature you are building, the data you need, the authentication scope you already have, and any endpoint or schema names you want to inspect. For multi-step flows such as reservation creation, include the current implementation step and where you are blocked.

Ask the AI to use `docs.zip` only when broad cross-document review is necessary. If a docs bundle was already downloaded, ask it to check whether `docs-manifest.json` or `docs.zip.sha256` changed before downloading again.

## What To Ask For In Answers

Ask the AI to end with the public KOS Developers documentation URLs it used. This makes it easier to see which parts are grounded in the docs and which parts are project-specific assumptions that still need confirmation.

```text
End with the public KOS Developers documentation URLs you actually used.
Separate what the docs confirm from assumptions we need to verify in our project.
If appId issuance, API Key or permission state, clinic-specific settings, or production availability
cannot be confirmed from the docs alone, mark them as requiring confirmation.
```

KOS Connect appIds and production availability, and OpenAPI API Keys and access permissions can vary by project or clinic. Do not let the AI invent values that are not in the docs; keep them as follow-up items for the responsible team when needed.

## Language Routing

Unless explicitly requested otherwise, answer in the user's language. Use `/llms.txt` for Korean, `/ja/llms.txt` for Japanese, and `/en/llms.txt` for English. If a page is not fully translated, the AI should state that limitation.