---
title: "Add, write and share domains"
url: https://temet.ai/docs/ask-kit/domains/
modified: 2026-11-19
summary: "A domain is something ask can answer about."
---

# Add, write and share domains

A domain is something `ask` can answer about. ask-kit ships two, `sessions` and `code`. You can
add one someone shared, write your own, or share yours. The `ask-kit-domain` skill walks an agent
through all three.

## The files in a domain

A folder with:

- `domain.mjs`: the REPL's globals, the prompts and the words the router knows it by,
- `api.d.ts`: a typed description of what the domain lets the investigator's programs reach,
- `instructions.md`: how to investigate, what counts as evidence and how to cite it,
- `scripts/`: ready-made scripts for the common questions.

Your own go in `~/.config/ask-kit/domains/<name>/`. One there wins over a built-in of the same
name. The contract is in `src/domains.mjs`, and `domains/code` is a short example.

## Add one someone shared

```
Read ~/.config/ask-kit/AGENTS.md, then add this domain: github.com/<owner>/<repo>
```

or from the shell:

```sh
ask-kit gallery                  # shared domains: GitHub repos with the topic ask-kit-domain
ask-kit add <owner>/<repo>       # fetch it and show its files, without enabling it
ask-kit add <owner>/<repo> --yes # install and enable it
```

A domain is code that runs in the investigator's REPL with your rights. `ask-kit add` always
shows the files first, and the agent tells you what the domain reads and runs before it asks
for your yes.

## Write one

1. Copy the shape of `domains/code`. Keep the globals read-only and narrow: a client for the
   thing, with methods that return plain data.
2. Write `api.d.ts` with every global and method, its parameters and what it returns. The
   investigator learns what its programs can reach from this file alone.
3. Write `instructions.md`: what the data holds, how to search it narrowly, how to cite.
4. Add two or three scripts for the questions people will ask most.
5. Enable it under `domains` in the config, ask it three real questions, and fix what it got
   wrong ([Make it better](https://temet.ai/docs/ask-kit/tuning/)).

## Share one

Put the domain folder and a `RECIPE.md` in a public GitHub repository and give it the topic
`ask-kit-domain`. The recipe says what the domain answers, what it needs (programs, keys,
access), what it reads and runs, and a brief another agent could rebuild it from in an empty
folder. It then shows in `ask-kit gallery`, and others add it with one line.

## More on domains

- [Write a domain](https://temet.ai/docs/ask-kit/guides/write-a-domain/): a working domain over a folder of notes, every
  file in full.
- [Add a script](https://temet.ai/docs/ask-kit/guides/add-a-script/)
- [What the investigator's programs can reach](https://temet.ai/docs/ask-kit/reference/domain-api/): the built-in domains'
  globals, helpers and scripts.
- [Domains in the code](https://temet.ai/docs/ask-kit/internals/domains/): the contract in `src/domains.mjs`, how domains are
  found and which one wins.
