Build with AI agents
If you build on Casama with a coding agent such as Claude Code, Codex or Cursor, give it these and it can answer from the real docs and API instead of guessing. Every option is free and needs no Casama account.
| What | Gives your agent | Set up |
|---|---|---|
| Agent kit | Skills for plugins, the API, A2A, bot templates, the gallery and the Casama repo, plus the docs server | One command in Claude Code |
| Docs server (MCP) | Search the docs, read any page, look up any API operation | One URL |
| Docs as markdown | llms.txt, a markdown copy of every page, the OpenAPI document | Nothing |
| The gallery | Ready-made skills, apps, routines, bots, plugins and looks to reuse before building | gallery_search, or plain JSON |
| Starter projects | A plugin, skill, bot or routine to start from, with an AGENTS.md | casama init |
| Plugin checker | The same checks Casama runs at install | npx @casama/plugin-check |
| TypeScript client | Typed calls for every API route | npm i @casama/client |
The agent kit
The agent kit is a set of skills, one per job, plus the docs server. A skill holds the exact formats, limits and steps for its job, and the agent loads it only when the task calls for it.
| Skill | For |
|---|---|
casama-overview | What Casama is, its concepts, where the docs are, and which skill to load next |
casama-plugin | Write, check and publish a plugin |
casama-api | Call the HTTP API: sign in, chat with a bot, follow runs, approvals, webhooks, SDKs and the CLI |
casama-a2a | Publish a bot over A2A, or call an outside agent |
casama-bot-template | Bot templates, and routines and skills as files |
casama-gallery | Add apps, skills, starter bots, routine ideas, plugins and themes to the gallery |
casama-contribute | Change Casama itself. See also Contribute to Casama. |
Claude Code:
/plugin marketplace add stackwares/casama
/plugin install casama-dev@casamaCodex, Cursor and other tools: copy the folders in agent-kit/skills to where your tool reads skills (for Codex, ~/.codex/skills), and add the docs server below.
A Casama bot: the kit is also a Casama plugin. In a bot's settings, under Plugins, paste https://github.com/stackwares/casama/tree/main/agent-kit.
The docs server
https://api.casama.ai/mcp/docs is an MCP server (Streamable HTTP) with the docs tools. It needs no sign-in and can't see any account.
claude mcp add --transport http casama-docs https://api.casama.ai/mcp/docsCursor (~/.cursor/mcp.json) and other tools that take JSON:
{
"mcpServers": {
"casama-docs": { "url": "https://api.casama.ai/mcp/docs" }
}
}| Tool | What it does |
|---|---|
search_docs | Searches the docs by keyword and returns the best-matching sections |
read_doc | One page as markdown, or one section of it |
list_doc_pages | Every page, with its title and address |
get_api_operation | Finds API operations by operationId (sendMessage), METHOD /path (POST /v1/routines) or keywords, and shows their parameters, request body and responses as types |
The local server, npx -y @casama/mcp, has the same tools plus check_plugin and gallery_search, and the tools that work with your bots once you sign in. With --docs-only it runs without a sign-in. See Connect AI apps.
A self-hosted server answers at /mcp/docs too, from the docs that shipped with it.
Docs as markdown
| Address | What's there |
|---|---|
docs.casama.ai/llms.txt | An index of every page, with a one-line summary and a link to its markdown (llmstxt.org) |
docs.casama.ai/<page>.md | Any page as markdown: add .md to its address, for example /develop/plugins.md |
docs.casama.ai/llms-full.txt | Every page in one file, about 600 KB |
docs.casama.ai/api/openapi.json | The HTTP API as OpenAPI 3.1. Your own server serves its version at /openapi.json. |
The buttons at the top of every page do the same by hand: Copy page copies its markdown, and Open in Claude and Open in ChatGPT start a chat that reads it.
Check the gallery first
Before your agent writes a new skill, bot, routine, plugin or look, have it look in the gallery: someone may have made it already, and a gallery item comes checked and ready to add.
- MCP: the
gallery_searchtool ofnpx -y @casama/mcptakes plain words and, optionally, the kinds to search (skill,app,routine,bot,plugin,set,theme,scheme,wallpaper). It returns the best matches with what each can access, what it needs and its page. - Terminal:
casama gallery search "summarize unread email", or start from a bot or plugin withcasama init --from-gallery bot/<id>(orplugin/<id>). See the CLI. - Plain JSON, no sign-in:
| File | What's in it |
|---|---|
index.json | Themes, color schemes, wallpapers and skills |
apps.json | Apps bots can connect to |
bots.json | Starter bots |
routines.json | Routine ideas |
plugins.json | Reviewed plugins, each pinned to a commit |
sets.json | Starter sets of items that go together |
authors.json | Authors and their items |
manifest.json | The SHA-256 of every file above, signed with Ed25519 in manifest.sig |
api.casama.ai/v1/gallery/stats | How many people use each item, what's trending and how often its runs finish, keyed <type>/<id>. Small numbers are left out. |
Each item has a page at https://gallery.casama.ai/i/<type>/<id>/ with an Open in Casama button. The item formats are in Gallery catalog format.
Bots inside Casama do the same: when someone asks for something a bot has no skill or app for, the bot searches the gallery and offers a match as a card with an Add button.
Starter projects
The CLI writes a starting point that already passes Casama's checks:
casama init plugin acme-weather # plugin.json, mcp.json, a small server, a skill, a CI check
casama init skill weekly-report # a SKILL.md
casama init bot support --name "Support Desk" # a .casama-bot.json template
casama init routine routines --name "Daily digest" # a routine fileEach one includes an AGENTS.md that tells your coding agent the format's rules, how to check the work and where the docs are. init needs no sign-in and never overwrites a file unless you pass --force.
The examples in the repository have one too: examples/hello-plugin and examples/sdk_sample.
Check a plugin
npx @casama/plugin-check . --strictIt runs the code Casama runs when someone installs a plugin, and exits 1 when Casama would refuse it (with --strict, also when it would skip anything). Agents can run it after every change and fix what it reports. In CI, use the GitHub Action, as described in Plugins.
Tips for working with an agent
- Ask it to load
casama-overviewfirst, or to readllms.txt, before it plans anything. - Have it search the gallery before it builds a skill, bot, routine or plugin.
- For API work, have it look up each operation with
get_api_operationrather than writing request bodies from memory. The API changes between versions; the OpenAPI document doesn't lie. - Point it at your own server: the local MCP server reads
CASAMA_API_URL, and/openapi.jsonon your server describes exactly what it runs. - For plugins, put the plugin check in the loop: write, check, fix, then commit.