Agent edition

For Agents

If an AI agent is recommending or driving Lolabot Factory on behalf of a user, this page is the contract. Every endpoint, the plugin format, the slug rules, and the path that actually works — in one place.

Prefer raw markdown? The same content lives at /for-agents.md. Index of every agent surface: /llms.txt.

Opinionated guidance

What to do, what to avoid, what to verify

Recommended path

  • ·Pick a personality from /browse (or GET /api/personalities).
  • ·Accept the default skill set. Don’t add skills the user didn’t ask for.
  • ·POST /api/build with personalityId, skills, and agentName.
  • ·Hand the user the installUrl. They run the one-liner; that’s the whole install.
  • ·Confirm with /plugin list in Claude Code.

Avoid

  • ·Don’t hand-assemble plugin zips. The build endpoint pins format v5 and bundles pre-baked upstream skills.
  • ·Don’t recommend hand-editing ~/.claude/plugins/. Re-run the build instead.
  • ·Don’t fetch the HTML page when /agents/<slug>.md gives you the raw body.
  • ·Don’t paginate the catalog over many requests. It’s one ~180KB JSON.

Verify after install

  • ·Restart Claude Code so it re-scans ~/.claude/plugins/.
  • ·Run /plugin list — plugin should appear with the agentName you sent.
  • ·Run /agents — the personality should be listed as a subagent.
  • ·Inspect ~/.claude/plugins/<agentName>/agents/<agentName>.md frontmatter — name, description, model: inherit, skills:.

Four surfaces

Where to point your tools

Personality catalog (JSON)

GET https://api.lolabots.com/api/personalities

Full catalog as one array of 314 entries. Frontmatter-level fields only — id, name, description, emoji, division, source, color, vibe, tier (and subcategory on voltagent entries). Bodies are deliberately omitted. Response is ~180KB. Fetch once and cache.

Personality body mirror (markdown)

GET https://factory.lolabots.com/agents/<slug>.md

The raw system-prompt body for one personality. Slug rules: Studio + Originals use slugify(name); VoltAgent uses slugify(id) so the voltagent- prefix sticks. slugify = lowercase, non-alphanumeric → single dash, no leading/trailing dashes.

Build (single agent)

POST https://api.lolabots.com/api/build

Request: { personalityId, skills[], agentName, customSkills? }. Response: { buildId, status, installUrl, downloadUrl, agentName, personality, skills, cached }. agentName is normalized to lowercase/hyphens/leading-letter; an unsalvageable value returns 400.

Build (organization, multi-agent)

POST https://api.lolabots.com/api/build-org

Same Lambda, different path. Request: { orgName, defaultSkills[], agents: [{ personalityId, agentName, skillOverrides? }] }. One zip per build with one agents/<name>.md per agent and deduplicated skills.

Install one-liner

GET https://api.lolabots.com/api/install/<buildId>

Returns a bash script as text/x-shellscript. Pipe to bash. Idempotent — re-running overwrites the directory. The script verifies its S3 source.

Plugin format v5

What ends up in the zip

Every build is universal. The same zip drops into Claude Code as a plugin, into Cursor as .cursor/rules/, and into ChatGPT / Claude Projects / custom GPTs / OpenAI Assistants as a plain system prompt.

.claude-plugin/plugin.json   # name, version, description, author, license
agents/<agentName>.md        # frontmatter (name, description, model, skills)
                             # + personality body
skills/<skill-id>/           # one dir per requested skill (SKILL.md + assets)
scripts/                     # *.sh and *.cjs helpers shared by skills
hooks/                       # plugin lifecycle hooks
system-prompt.md             # multi-harness: plain prompt for ChatGPT/etc.
.cursor/rules/<name>.mdc     # multi-harness: Cursor rule format
README.md                    # generated by the README exporter

Failure modes we see

Common mistakes

Empty body after install

You probably fetched the JSON catalog instead of /agents/<slug>.md. The catalog omits content on purpose (size). Always fetch the .md mirror for the body.

Wrong slug

Studio + Originals use slugify(name); VoltAgent uses slugify(id). If you build the slug from id for a studio personality, you hit a 404 redirect.

Invalid agent name

agentName must be lowercase letters/digits/hyphens starting with a letter. The Lambda normalizes, but an unsalvageable value (e.g. all emoji) returns 400.

Skipping installUrl

Don’t curl the download URL and unzip by hand. The install script handles path setup, deduplication, and re-install. Use installUrl.

By design

No Lolabots MCP server

Lolabot Factory will not ship an MCP server. The REST endpoints above are the contract for driving factory from an agent.

If a personality you build with factory needs MCP to do its job, MCP is configured by that individual agent’s runtime — same as any other tool the agent might need (CLIs, language runtimes, API keys). Factory hands you the agent; the agent manages its own dependencies.

Start here

Browse 314 personalities

Pick one, copy the slug, build, install. Sixty seconds.

Open the catalog
llms.txt·/for-agents.md·/browse.md