Building a catalog bot
A catalog bot is a folder. The full reference is docs/bot-framework_en.md (Chinese: docs/bot-framework.md); read it before you start. Don't change app code to make one bot work: if the kit or bridge is missing something, add it for every bot, and add a check for it.
Steps
- Scaffold:
npm run bot -- new <id>. This createsbots/<id>/. - Replace every
TODO. The bot can't pass with any left.bot.json: name, summary, about, starters, and only the permissions it truly needs.persona.md: who the bot is, what job it does, how it knows the job is done. Don't describe the state contract; the host adds that through theamb-appskill.state.schema.json: the smallest shape the UI needs.sample.zh-CN.jsonandsample.en.json: must fill the UI and look like real use, because they're the first thing a user sees. Write each one in its own language, and addsample.ja.json,sample.ko.json,sample.ru.json,sample.es.jsonandsample.pt.jsontoo (ptis Brazilian Portuguese).evals/: at least 3 real tasks and 1 injection case.
- Skills: write your own in
skills/<name>/SKILL.md, or copy a skill in and list it underskillsinbot.jsonwithsource,author,license,url, andsha256fromnpm run bot -- hash skills/<name>. Only MIT, MIT-0, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC or CC0-1.0. A repository with no license can't be used. - UI: import only from
/amb/botapp/kit/kit.jsand your own folder. RenderuseBot().state, and change data only withsend(text, action). Show images fromapp/withreadImageand open outputs withopenFile. Put strings inui/locales/for all seven languages (zh-CN,en,ja,ko,ru,es,pt), and write every text field inbot.jsonin all seven. - Cover: add
cover/light.pngandcover/dark.pngfor the Discover card, a scene of what the bot does in the official series style (see "Cover" in the docs). PNG, at most 500 KB each. - Run
npm run bot -- check bots/<id>and fix every rule it names. Repeat until it passes. - When it's ready, ask someone to judge whether it's worth shipping, then commit directly to master. Don't open a PR. Don't run
check --fullunless someone asks for it. Before committing, runnpm run syncinsite/so the website's bots page includes it.
Rules the checks enforce
- UI: no
fetch, storage,window.parent,eval, inline scripts, inline styles in HTML, or external URLs. External links use the kit'sLinkoruseBot().openUrl. Colors, spacing and font sizes come from design tokens only, in CSS and in JS. In JS, usestyleonly for computed values, such as a bar's width. - Every starter must visibly change the view. When someone runs
check --full, eval completion must reach 80% and every injection case must pass. - Skill scripts: declare
networkif they use it. Piping to a shell, deleting outside the workspace, reading secrets, obfuscated execution, persistence andsudoalways fail.
What a bot can't do
- Register tools. Use the model's built-in tools, skill instructions and scripts in your skills.
- Call the model or read the user's environment variables from a script. Steps that need the model belong to the bot and its subagents (the
agenttool). Useweb_searchfor search. - Write
app/state.jsonfrom a background task. Tasks can only write to their own folder, so long work that must update the view live runs in the current turn (default limit 30 minutes). - Send results to a channel of its choice. Results go back to the conversation that started the work.
Don't
- Don't bypass a failing check. Fix the bot, or if the rule is wrong, change the rule for everyone.
- Don't ask for permissions "just in case". Users see the list, and undeclared ones are refused at runtime.
- Don't design new templates up front. Add components to the kit when a real bot needs them.