The AI path — Build an actor with /create-actor

](en/track-a/setup-and-generate/) makes you the driver: you answer copier’s questions, you write the domain code. The AI path splits the work differently — a skill conducts a structured discovery conversation with you, then generates the actor and implements the domain code. You bring the domain knowledge and the judgment; it brings the template knowledge and the typing.

The skill is /create-actor (SKILL.md). It ships inside the kaboum repo, and its ground rule is that the kaboum template is the single source of truth: it re-reads the template files on every run and never copies patterns from previously generated actors, because those lag the template.

This path is for you if you can hold a precise conversation about your domain but do not want to hand-write Python, client code, and migrations.

Prerequisites

• Claude Code. The skill drives an interactive question-and-answer flow inside it.
• Access to the kaboum repo. The skill lives in kaboum’s .claude/skills/create-actor/ and reads the template from that checkout. You need a checkout you can point Claude Code at.
• A verification environment. The skill checks its own work, so it needs: Python 3.11–3.13 with copier 9.4.0 or newer (older claimed minimums do not actually install on modern Python), ruff, and the actor test stack — pytest, with Docker available so PostgreSQL and Redis can be booted for the tests that need them.
• Nothing from Kaoohi yet. You only need a Kaoohi account at publishing time, in the Creator Hub.

The six phases

Phase 1 — Domain discovery

The skill asks structured questions in three batched rounds: identity and domain first; then capabilities, agent framework, intelligence toggles, connectors, and MCP servers; then one open-ended deep dive into how the actor should actually behave. Answer in your words — this conversation is the raw material for everything downstream.

Phase 2 — The discovery document

The skill writes documentation/discovery.md into your new actor project: identity, integration choices, MCP servers, tools, data model, actor behavior, config, and the resolved template variables. Read it. If something is wrong, say so now — it is cheap to fix here and expensive later.

Phase 3 — Scaffold generation

The skill renders the project from the kaboum Copier template pinned to the exact commit your checkout is on — a reproducible snapshot, so your actor can later follow template updates cleanly. The fresh scaffold is then cleaned up with ruff before any domain code lands.

Phase 4 — Domain code implementation

This is the part Track A does by hand. The skill implements the real domain code following the template’s conventions:

• Domain models and the domain client.
• LangChain tools, registered properly in the tool registry.
• The ROLE_PLAYBOOK system prompt. The template-owned prompts are never edited; the phrases that matter are pinned in a system-prompt test, so later template updates cannot silently drift your actor’s behavior.
• A capability-boundary test encoding what the actor must and must not do.
• Config fields annotated with x-kaoohi-* — these drive the marketplace settings form and the actor metadata.
• Marketplace metadata, safety and egress declarations in pyproject.
• Database migrations, numbered from 004_ (the first three belong to the template), with a guard against exposing sensitive columns.
• .env.example with placeholder values, and MCP_SERVERS_JSON wiring if your discovery called for MCP tools.

Phase 5 — Verification

The skill verifies before handing over: ruff must pass clean, the derived src/kaoohi/config.json must be regenerated and freshness-checked (it is emitted from your config fields — hand-editing it is forbidden, and a malformed one fails the image build later), and the test suite must be green. The refreshed config file is committed alongside the code that produced it.

Phase 6 — Summary and publish guidance

You get a summary: which files were written, test results, which values are still placeholders (credentials, mostly), and how to run and publish the actor.

What stays yours

• Answering discovery honestly. The actor is only as good as your answers. Vague answers produce a vague actor.
• Real credentials. The skill writes placeholders. Real secrets are yours to supply at runtime — never committed to the repo.
• Marketplace polish. Display name, description, category, pricing model: the commercial identity of the actor is your call, not the skill’s.
• Publishing. You do the registration and submission in the Creator Hub.

Publishing after the skill

The actor is code until you make it a product: build the image (its config baked in), push it to a public registry such as GHCR, then register it in the Creator Hub. Registration takes the image reference, not a pasted config — the platform pulls the image and extracts the config itself. You preview, adjust name, description, category, tags, and pricing, then either save as a draft or submit for review. The full walkthrough, including versioning and tagging the image, is in ](en/publishing/); before submitting, test the draft in the ](en/track-b/sandbox/).

If the skill disagrees with this guide

The skill’s older closing guidance tells you to paste config.json into a “Develop a new actor” dialog. That flow is gone. Registration today is the Creator Hub wizard above, and it takes an image URL — the platform extracts the config itself. Where the skill’s text and this guide disagree, this guide wins; the skill is being aligned.

How to invoke it

Open Claude Code where it can read your kaboum checkout, and type:

/create-actor

Then answer the questions as they come.

Tips for good discovery answers

• Arrive with a one-sentence purpose. “A hotel front-desk actor that answers booking questions and creates housekeeping tickets” beats “an assistant for hotels.”
• Name the external services, and what the actor does with them. Read, write, or both? Which actions are dangerous and should be refused?
• Describe the data entities as you would to a new colleague: a booking has a guest, dates, a room, a status.
• In the open-ended round, walk through one real user story end to end. This is where the skill picks up behavior the checkboxes cannot express.
• Treat defaults deliberately. Sub-agent fan-out is the most expensive intelligence toggle; planning and summarization default on. Say so if you want them off.
• Choose the domain module name with care — reserved names are rejected, and it becomes a directory and import path you will live with.
• When unsure about connectors, say none. MCP servers can be added later with no code changes.

Where to go next

• Test your draft in the ](en/track-b/sandbox/) before submitting.
• Want to understand what the skill built? The extension points it filled in are the same ones ](en/track-a/extension-points/).
• kaboum development and extension guide — the how-tos behind every file the skill writes.