> For the complete documentation index, see [llms.txt](https://docs.codemate.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codemate.ai/cora-cli/configurations.md).

# Configurations

Teach CORA about your project, set up standing instructions it reaches for automatically, and connect it to outside tools.

## AGENTS.md, the project briefing

If your project has a file called `AGENTS.md` in its root folder, CORA reads it at the start of every conversation. It is the place to write down the things you would otherwise repeat every day:

* what the project is and how it is laid out
* the command that runs the tests
* conventions to follow, and things never to touch
* anything a new team member would be told in their first week

### /init writes one for you

Type `/init`. CORA surveys your repository and writes an `AGENTS.md` describing what it found.

Two things it deliberately refuses to do:

1. **It never overwrites an existing `AGENTS.md`.** That file shapes every future conversation, and replacing your hand-written notes is not helpful.
2. **It refuses in read-only modes** because writing the file is a file edit like any other. Switch to code mode first (it will tell you this).

Writing the file raises the normal approval, so you see it before it lands.

### Checking that it is being read

`/status` and `cora --doctor` both answer this:

```
context AGENTS.md (5020 bytes), read by the agent every session
```

or, when there is none:

```
context none — /init writes AGENTS.md
```

`cora` also reads a **CLAUDE.md** in the root if you have one. **AGENTS.md** wins if both exist. Only the **root** of the project is read; a file in a subfolder is not picked up. `/status` also reports the Toolbox workspace this project is linked into and the files in your CodeMate storage see [Your CodeMate files](#your-codemate-files-remote) below.

***

## Rules, skills, and workflows

Three ways to make `cora` behave the way your team works. They sound similar and are used at completely different moments.

|                           | Rules                     | Skills                               | Workflows                   |
| ------------------------- | ------------------------- | ------------------------------------ | --------------------------- |
| In one line               | What CORA **always** does | Expertise it **may reach for**       | A procedure **you** run     |
| What it is                | A markdown file           | A folder with a `SKILL.md` inside    | A markdown file             |
| When it applies           | Every single turn         | When the job matches its description | Only when you type its name |
| How you trigger it        | Nothing; it is always on  | `/<name>`, or `cora` decides         | `/<name>`                   |
| Takes your words as input | No                        | No                                   | **Yes**                     |
| Needs a restart to appear | No                        | **Yes**                              | No                          |
| Turn it off               | `/rules off <name>`       | `/skills off <name>`                 | `/workflows off <name>`     |

Where they live:

```
~/.cora-cli/rules/          <project>/.cora-cli/rules/          rules
~/.cora-cli/skills/         <project>/.cora-cli/skills/         skills
~/.cora-cli/workflows/      <project>/.cora-cli/workflows/      workflows
```

The left-hand column applies everywhere on your machine; the right-hand column travels with the repository, so your team gets it when they clone. **If both hold the same name, the project's copy wins.**

### Rules, the standing instructions

A rule is a markdown file, and every enabled one is sent with **every** message you write. Use rules for short, stable facts and constraints.

`<project>/.cora-cli/rules/testing.md`:

```
Run `npm test` before reporting any change as finished, and show the output.
Never change files under `legacy/`; that directory is frozen.
Prefer adding to an existing test file over creating a new one.
```

| Command             | What it does                                          |
| ------------------- | ----------------------------------------------------- |
| `/rules`            | What exists, which are on, and roughly what they cost |
| `/rules off <name>` | Stop sending one                                      |
| `/rules on <name>`  | Send it again                                         |

Three practical notes:

1. **They cost tokens every turn.** `/rules` tells you roughly how much and warns you when the total gets large. Keep them short.
2. **They take effect immediately.** Edit a rule and ask again; no restart.
3. **They are instructions, not enforcement.** A rule is something CORA is told every time, not a lock. Do not rely on one to prevent something dangerous that is what `/settings` is for.
4. **Do not write contradicting rules.** They are all sent together; if two disagree, the result is a coin toss.

### Skills, reusable expertise

A skill is a folder with a `SKILL.md` file in it. It holds a playbook CORA can pull out when the job calls for it.

`<project>/.cora-cli/skills/api-change/SKILL.md`:

```
---
name: api-change
description: The checklist for changing a public API endpoint. Use when the
  user is adding, removing, or altering an endpoint or its request or response.
---

# Changing an API endpoint

1. Check who calls it before changing the shape.
2. Add the new field as optional first; never remove one in the same release.
3. Update the contract tests, then the docs.
4. Run the contract suite and show the output.
```

| Command                | What it does                                    |
| ---------------------- | ----------------------------------------------- |
| `/skills`              | What exists, which are on, what needs a restart |
| `/skills off <name>`   | Hide it                                         |
| `/<name> <what to do>` | Use a skill on something                        |

Two things surprise people:

1. **A new skill needs a restart.** Skills are loaded once at the start. Write one mid-session, and it will not be available until you restart. `/skills` tells you which ones are waiting.
2. **You may see skills you did not write.** If you have other AI tools installed, CORA may find skills they left on your machine `~/.claude/skills` is the common one. They are listed so you can see where they came from. CORA itself ships no built-in skills in this release: every skill you see is one you or another tool put there.

Write the **description** carefully; it is how CORA decides whether the skill applies. The first sentence should read well to a person (it is what you see in the menu); put the "use this when..." triggers after it.

### Workflows, procedures you run by name

A workflow is a markdown file holding a procedure. Its filename becomes a command: `ship.md` becomes `/ship`.

`<project>/.cora-cli/workflows/ship.md`:

```
---
description: Plan, implement, and verify a change end-to-end
argument-hint: <what to change>
---

Work through this in order.

1. Survey the affected code before editing anything.
2. Make the change, following the nearest existing pattern.
3. Run the tests and the type check, and report anything that failed.

Task: $ARGUMENTS
```

Then:

```
/ship the auth refactor
```

`$ARGUMENTS` is replaced with whatever you typed after the command. If the file has no `$ARGUMENTS`, your words are added at the end instead.

| Command                 | What it does                                             |
| ----------------------- | -------------------------------------------------------- |
| `/workflows`            | What exists, which are on, and any file that was skipped |
| `/workflows off <name>` | Stop offering one                                        |
| `/workflows on <name>`  | Offer it again                                           |

Notes:

1. **No restart needed.** Write a workflow, and it runs. The only catch: the `/` autocomplete menu is built when `cora` starts, so a brand-new workflow will not appear in the menu until next time, but typing its name works immediately.
2. **The name must be lowercase letters, digits, and hyphens.** A file that cannot become a command is skipped, and `/workflows` tells you which and why.
3. **A workflow is one turn**, not a multi-step pipeline.

### Which one should I use?

| You want...                                                        | Use            |
| ------------------------------------------------------------------ | -------------- |
| A constraint that should shape everything ("always run the tests") | a **rule**     |
| A checklist for a recurring *kind* of work ("changing an API")     | a **skill**    |
| A sequence you kick off yourself ("do the release checks")         | a **workflow** |

***

## Connecting outside tools (MCP)

MCP is how `cora` reaches systems outside your project: an issue tracker, a documentation site, a database browser, an internal service. Each one is called an **MCP server**, and you add it once.

Type `/mcp`:

```
MCP servers

›  docs        connected
   tracker     needs sign-in
   database    disabled

↑↓ move · enter open · ctrl+r connect · ctrl+u edit · ctrl+a new
ctrl+t toggle · ctrl+o file · ctrl+d remove · esc
```

| Key               | What it does                                                |
| ----------------- | ----------------------------------------------------------- |
| **↑ / ↓**         | Move between servers                                        |
| **Enter**         | Open one, and start sign-in if it needs it                  |
| **Ctrl+A**        | Add a new server: a box opens, and you **paste** the config |
| **Ctrl+R**        | Connect (or reconnect)                                      |
| **Ctrl+T**        | Turn one on or off                                          |
| **Ctrl+U**        | Edit its config                                             |
| **Ctrl+O**        | Open the config file in your editor                         |
| **Ctrl+D**, twice | Remove it; the second press confirms                        |
| **Esc**           | Close                                                       |

### Adding one

Press **Ctrl+A** and paste the configuration snippet from the tool's own documentation. You do not have to retype it or reformat it; the paste box accepts the shapes those snippets normally come in.

You will then be asked where to save it:

| Scope       | Key | Meaning                                           |
| ----------- | --- | ------------------------------------------------- |
| **project** | p   | Saved with this project, so your team gets it too |
| **global**  | g   | Just for you, in every project                    |

**Signing in.** Some servers need you to sign in. Press **Enter** on one marked `needs sign-in` and `cora`:

{% stepper %}
{% step %}

## Open the provider sign-in page

`cora` opens your browser at the provider's sign-in page.
{% endstep %}

{% step %}

## Use the printed URL if needed

It also prints the URL, in case the browser did not open or you are working over a remote connection.
{% endstep %}

{% step %}

## Complete sign-in

`cora` catches the result when you finish and connects to the server.
{% endstep %}
{% endstepper %}

The consent screen you see names **CORA**, so you always know what you are granting access to.

### Statuses

| Status       | Meaning                                          |
| ------------ | ------------------------------------------------ |
| `connected`  | Working and available                            |
| `needs_auth` | Needs you to sign in; press Enter                |
| `failed`     | Could not connect; the error is shown next to it |
| `disabled`   | Turned off; press Ctrl+T to turn it on           |

### Using MCP well

1. **Enable only what a project needs.** Every connected server adds tools CORA has to choose between; a smaller set produces better choices.
2. **Keep write-capable tools on ask.** Reading an issue is safe; closing one is not.
3. **Treat what a server returns as information, not instructions.** A ticket description is someone's summary of a requirement; it is not a substitute for reading the code.
4. **A server added by mistake can be disconnected**, and it is dropped from the configuration on the next start.

***

## Your CodeMate files (/remote)

The files in your CodeMate account are listed to the agent on every turn, so it knows what is there without opening anything. Reading one raises the same approval as any other read, and the request names the file. PDF, DOCX, and XLSX come back as text.

Type `/remote` to see the list, what it costs per turn, and to fetch it again. To point the agent at one yourself, write `@remote:<path>` in your message. The list is remembered between runs and says so while it is still loading about twenty seconds from start-up. `/status` reports it too.

**Treat a shared file the way you treat a web page.** The shared scope is other people's files, written by someone who is not in this conversation. What comes back is information, not instruction which is why the read asks you first in every mode, including the read-only ones.

## Linked projects (/workspace)

If this project sits in a Toolbox workspace, CORA can read and change the other projects in that workspace under **this** project's permission settings, not theirs. The workspace name is drawn on the prompt's border with a ◈, and `/status` names it as well.

`/workspace` lists the workspace and the projects it links, and turns the linking on or off. Reaching outside this project is its own row in `/settings` "Reach outside this project" so you can set it to allow, ask, or deny like any other capability, and it is **ask** to begin with. A rewind reaches the linked projects too, not only this one.