Creating a Bot

A Bot is a plain directory with a BOT.md at its root. Once registered, a line starting with @name in any chat is handed to a session of its own, which reads BOT.md and uses the Bot's files as its long-term context. Its files change only when the user explicitly asks (remember / update / correct / forget), under a short write lock, so parallel sessions keep reading freely.

This skill does one thing: create a new Bot. Everything you can do to an existing Bot is addressed to the Bot itself, not to this command — @name review to sweep it, @name attach <path to SKILL.md> to give it a tool, @name export to <path> to make a shareable copy with no memory in it, @name <task> for ordinary work. That is where those instructions live too, so they improve for every existing Bot at once. If the request is about a Bot that already exists, say which @name line does it and stop.

Cloning one is not an exception. "Copy this Bot", "make me another one like it", "turn it into a template" all operate on a Bot that exists, so they are @name export to <path> — and they need a session that has read the whole source directory to tell a general procedure from this user's private memory. Say that line and stop; do not scaffold a copy from here.

curl -s {{BASE_URL}}/api/bots lists registered Bots with their name, description and absolute path — use it to check a new name for clashes.

1. Create: align first, write only after confirmation

1. Align on the Bot — restate in a few lines what this Bot is for: its role, what it should remember, and what it is responsible for keeping up to date. Ask back only when the request is genuinely ambiguous.

2. Tell the name and directory — resolve both and state them exactly:

   • You pick <name> from the request: lowercase letters, digits and -, starting with a letter or digit (it becomes the @name mention). Check it against the registry above.
   • The user gave a directory → <that directory>/<name>/; none given → {{COCKPIT_DIR}}/bots/<name>/.
   • The target must not already exist, or must be empty. Never overwrite an existing directory.

3. Write only after confirmation — once the user agrees, create the files below with Write.

4. Hand over registration — do NOT register it yourself. Tell the user the directory path and the two ways to add it: open the Bots panel → Add bot and paste the path, or open BOT.md in the file explorer and click its Add as Bot button.

5. Say what it can now be asked, in four lines — this is the only place the user learns the verbs, since @ autocomplete shows only the description:

   • @<name> <task> — ordinary work, in its own session, with its files as context
   • @<name> review — a sweep for stale entries, contradictions and dangling commitments
   • @<name> attach <path to SKILL.md> — teach it a tool it may use
   • @<name> export to <path> — a new Bot at that path with the manual and skills but none of the memory, to hand to someone else

   Say them in the user's own language if they wrote in another one — each mode answers to the phrasings listed at the top of its bot-turn file, English and Chinese alike.

2. Layout

<name>/
├── BOT.md                  # manifest + operating manual (the subagent reads this first)
├── identity/
│   ├── persona.md          # stable role, voice, scope
│   └── principles.md       # operating principles and boundaries
├── relationships/
│   └── user.md             # confirmed preferences of the people it works with
├── memory/
│   ├── facts.md            # durable, verified facts
│   └── procedures.md       # procedures proven by successful execution
├── projects/               # created on demand: projects/<project-name>/CONTEXT.md
├── skills/                 # created on demand: this Bot's own SKILL.md files
├── commitments/
│   └── active.md           # open promises and follow-ups
├── evidence/
│   └── refs.md             # sources backing the entries above
└── secrets/                # only if this Bot has credentials of its own — never read, never printed

Two more directories appear on their own and are never scaffolded: .locks/ (the write lock) and .reviews/ (one uniquely timestamped file per review sweep). Both are work products, never memory — nothing reads them as fact.

Credentials belong to the tool, not to the Bot: a skill's .env files stay next to that skill, so several Bots share one copy and no key is duplicated. <bot>/secrets/ is for the rare case where the credential really is this Bot's own (its own account). Either way it is gitignored when the directory is a repository.

Seed identity/persona.md and identity/principles.md from what the user told you. Every other file starts as a heading plus a one-line HTML comment describing its purpose — never invent facts, preferences, or history.

3. BOT.md

Frontmatter is only name and description (the description is what the @ autocomplete shows).

The body says who this Bot is — its role, which of its files to read, which skills it has, and where new entries belong. It does NOT restate how a Bot turn works: reading rules, entry format, the write lock, the non-recording list and the reporting rules all live in the hidden bot-turn skill, which is handed to the session alongside this file. Keep it that way. Anything written here is copied into every Bot and frozen on the user's disk; anything in bot-turn is fixed once and every existing Bot gets the fix. Put in BOT.md only what would be wrong in another Bot's.

---
name: <name>
description: "<one line: what this Bot knows and maintains>"
---

# <name>

<one paragraph: role and scope>

## Before working

Read, relative to this file's directory:

- identity/persona.md and identity/principles.md — always
- relationships/user.md and commitments/active.md — always
- memory/facts.md and memory/procedures.md — when relevant to the task
- projects/<project-name>/CONTEXT.md — when the task concerns that project
- the Skills table below — always; resolve and open a row's SKILL.md only when the task matches it

Reading rules, entry format, when writing is allowed, the write lock and the reporting rules are
the same for every Bot: they are in the `bot-turn` skill you were handed with this file. If you do
not have it, say so rather than inventing a protocol — especially the write lock.

## Skills

| Skill | When to use | Where |
|---|---|---|
| <name> | <the kind of task it applies to> | <the registered skill's name, or a path relative to this directory for one of this Bot's own> |

## Updating

Only when the task explicitly asks to remember, update, correct or forget something (`bot-turn`
§3–§4 covers the rest: metadata, what never gets recorded, the write lock). Where things go in
this Bot:

- a confirmed fact or a correction → memory/facts.md (mark the old entry `status: superseded` or replace it; never leave a contradiction)
- a decision and its reason → memory/facts.md under `## Decisions`, dated
- a user preference → relationships/user.md
- a promise made or completed → commitments/active.md, with `done-when`, `waiting-on` and
  `next-check` (`status: done` or `cancelled` when it ends)
- a procedure that just worked → memory/procedures.md
- project status changes → projects/<project-name>/CONTEXT.md, where `<project-name>` is the
  project's name in lowercase kebab-case (by default its root directory name); reuse an existing
  directory for the same project instead of creating a second one
- where the information came from → evidence/refs.md

<Anything that is true of THIS Bot only: a file it must never touch, a project whose CONTEXT.md
is authoritative, a person whose word settles a question.>

Adapt the lists to the Bot's purpose, but keep the sections: together with bot-turn they are the only contract between the Bot and whoever runs it. Resist copying any of bot-turn back in here — a frozen copy is exactly what this split exists to prevent.