ai tooling

@yaebal/ai ships the dev tooling that makes ai coding assistants good at yaebal: a one-command installer that teaches your agents the framework, an mcp server with the exact bot api schema, and agent playbooks for the recurring bot-building tasks. the same package also contains the runtime plugin (ctx.ai, streamed llm replies) — that side has its own page.

one-command setup

run the installer in your bot project. it detects which agents you use (from .claude/, .cursor/, AGENTS.md, …), lets you pick, and writes the right rules files and mcp config for each:

# interactive — detects which agents live in your project and preselects them
npx @yaebal/ai

# non-interactive — pick agents explicitly (ci, dotfiles, scripts)
npx @yaebal/ai install --agents claude,cursor

supported agents

nine targets; each gets the files its ecosystem expects:

existing files are merged, never clobbered: markdown gets an upserted yaebal section, json configs get a yaebal entry with everything else preserved (an unparseable config is left alone with a manual note instead).

claude code marketplace

claude code users can skip the installer entirely — the plugin marketplace delivers the skills and the mcp server as one managed, updatable plugin:

claude plugin marketplace add neverlane/yaebal
claude plugin install yaebal

the mcp server

the mcp server gives agents exact answers instead of guesses — the full bot api schema (the same schema.json that generates @yaebal/types), the plugin catalog, docs search and runnable examples. it runs over stdio:

# stdio launch — what the installer writes into .mcp.json and friends
npx -y @yaebal/ai mcp

{
	"mcpServers": {
		"yaebal": {
			"command": "npx",
			"args": ["-y", "@yaebal/ai", "mcp"]
		}
	}
}

shipped skills

nine playbooks travel with the installer — verbatim claude code skills, converted into cursor rules and AGENTS.md sections for the others. each teaches one recurring task in a bot project:

• yaebal-write-bot — bot setup, handlers, filter queries, commands, context typing
• yaebal-pick-plugin — which @yaebal/* package solves a given problem
• yaebal-keyboards-and-callbacks — keyboard builders and typed callback payloads
• yaebal-flows — choosing between scenes, conversation, and prompt, and wiring persistence
• yaebal-ai-features — adding llm features with the @yaebal/ai runtime plugin
• yaebal-test-bot — @yaebal/test actors, api-call assertions, the virtual clock
• yaebal-deploy — long polling vs webhooks, graceful shutdown, error handling
• yaebal-debug — install-order type errors, esm specifier errors, telegram 400/409/429
• yaebal-author-plugin — the Plugin<In, Out> contract and typed dependencies

machine-readable docs

the site exposes two plain-text files for agents and search tools:

https://yaebal.mom/llms.txt
https://yaebal.mom/llms-full.txt

agent prompt

if you are using an assistant that accepts project instructions but can't run the installer, give it this baseline before it writes yaebal code:

use yaebal as an esm typescript telegram bot api framework.
prefer createBot() from "yaebal" for app code.
context type flows through .derive(), .decorate(), .install(), and .extend().
use on("message:text") for typed text-message handlers.
use @yaebal/test for tests instead of hitting telegram in ci.

where an assistant should look first

// canonical docs entry points for agents
/docs/getting-started/
/docs/core/
/docs/context/
/docs/plugins/
/docs/api/
/docs/troubleshooting/
/docs/production/

rules that prevent hallucinations

• use createBot() from yaebal for application examples unless the docs specifically show @yaebal/core.
• use explicit .js extensions in local esm imports in generated projects.
• use bot.install(plugin()) for yaebal plugins, not raw use().
• do not invent callback-data formats; use callbackData().
• do not hit real telegram in tests; use @yaebal/test.
• check the generated bot api reference for method params and return types.