bot · diff
git:20260918.4764231 to git:20260918.60d1690
18 added, 7 removed. Audit A to A.
---
name: bot
description: "Create a Bot: a plain directory with BOT.md and long-term context, addressed as @name."
argument-hint: "[what the Bot is for]"
---
# 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 复盘一下` to review it, `@name 装上
- <path to SKILL.md>` to give it a tool, `@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.
+ 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 three lines — this is the only place the user learns the
+ 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> 复盘一下` — a sweep for stale entries, contradictions and dangling commitments
- - `@<name> 装上 <path to SKILL.md>` — teach it a tool it may use
+ - `@<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
```text
<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.
````markdown
---
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.