crewai-init

name	crewai-init
description	Scaffold a new CrewAI project the right way — Flow-first architecture, JSONC configs, Claude LLM wiring, guardrails, and a verified runnable baseline. Use when the user asks to create, bootstrap, or start a new CrewAI project, crew, or flow.
disable-model-invocation	true
argument-hint	[project-name]
arguments	["project_name"]
allowed-tools	Bash(${CLAUDE_SKILL_DIR}/scripts/*), Bash(crewai *), Bash(uv *)

Scaffold a new CrewAI project

Create a production-shaped CrewAI project for $project_name (ask for a name if empty). Follow the steps in order; run the bundled scripts rather than hand-typing CLI commands.

Step 1 — Understand the use case, pick the architecture

From the conversation (ask one round of questions if unclear): what is the process, what are the inputs/outputs, which steps need judgment vs. which are mechanical?

Pick using the decision matrix:

Complexity	Precision needed	Build
Low	High	Flow with direct LLM.call() steps — no agents
Low	Low	Single Agent
High	Low	Single Crew
High	High	Flow orchestrating Crews (default)

Default to Flow-first (crewai create flow). Choose crew-only (crewai create crew) only when the user explicitly wants a standalone crew with no orchestration.

Tell the user which shape you picked and why, in two sentences, before scaffolding.

Step 2 — Scaffold

bash ${CLAUDE_SKILL_DIR}/scripts/scaffold.sh <project_name> <flow|crew>

The script verifies prerequisites (Python 3.10–3.13, uv; installs the crewai CLI via uv tool install crewai if missing), runs crewai create + crewai install, and is safe to re-run. If it fails, fix the reported problem and re-run it — do not improvise around it.

Step 3 — Environment

bash ${CLAUDE_SKILL_DIR}/scripts/setup-env.sh <project_dir>

Writes a .env template (MODEL=anthropic/claude-sonnet-4-6, ANTHROPIC_API_KEY= placeholder) without overwriting an existing .env, ensures .env is gitignored, creates a starter AGENTS.md if the scaffold didn't, and symlinks CLAUDE.md → AGENTS.md so the same project context serves both AGENTS.md-reading agents (Codex, Cursor, Gemini) and CLAUDE.md-reading agents. Remind the user to fill in the real key; never write a real key yourself.

After the flow and crews are authored (Step 4), fill AGENTS.md in with the real project overview, architecture map, run commands, and conventions — don't leave the placeholder text.

Step 4 — Author the configs and flow

Load the crewai-expert skill references before writing code:

• Flow wiring and state → crewai-expert skill, references/flows.md
• JSONC config and task/agent params → crewai-expert skill, references/crews.md
• Claude LLM details → crewai-expert skill, references/llm-config.md

Apply, in this order:

1. Typed state: define a Pydantic state model; class MyFlow(Flow[MyState]).
2. Deterministic steps as plain methods — input normalization, validation, routing computable from state, output persistence. No LLM calls in these.
3. Crews in JSONC: crew.jsonc + agents/*.jsonc per crew, loaded via load_crew(Path(__file__).with_name("crew.jsonc")). Every agent: specific role/goal/backstory and "llm": "anthropic/claude-sonnet-4-6". Every task: one outcome, specific expected_output.
4. Structured handoffs: output_pydantic on any task whose output later steps consume.
5. Guardrail on the terminal task at minimum — function guardrail returning (bool, Any) for format rules, string guardrail for subjective criteria.
6. @persist on the flow class if the process is long-running or restart-sensitive.

Step 5 — Verify

bash ${CLAUDE_SKILL_DIR}/scripts/verify.sh <project_dir>

The script smoke-checks the project (imports resolve, JSONC parses, entry points exist) and, when an API key is available, offers crewai run. Also generate the flow diagram (crewai flow plot) and tell the user where the HTML landed.

Report to the user: the architecture chosen, files created, verification results, and the exact next commands (crewai run, crewai flow plot).

Rules

• Never commit or print secrets; .env stays gitignored.
• Don't add memory, knowledge, MCP, or hierarchical process to a fresh scaffold unless the use case demands it — start minimal (see the crewai-expert skill for when to add each).
• If the user's use case is a simple linear script with no judgment steps, say so and recommend plain Python instead of CrewAI.