crewai-audit

name	crewai-audit
description	Audit a CrewAI project against official best practices (architecture, tasks, agents, flows, LLM config, tools, security) and generate/update the project's AGENTS.md context file. Use when the user asks to review, audit, or improve existing CrewAI code, or to refresh the project's AGENTS.md.
disable-model-invocation	true
argument-hint	[path]
arguments	["target_path"]
allowed-tools	Bash(${CLAUDE_SKILL_DIR}/scripts/*)

Audit a CrewAI project

Audit the project at $target_path (default: current directory). Two deliverables, in order: (1) a findings report, (2) a created/updated AGENTS.md.

Step 1 — Inventory

bash ${CLAUDE_SKILL_DIR}/scripts/inventory.sh $target_path

This prints every CrewAI artifact: JSONC/YAML configs, Flow subclasses, @CrewBase classes, load_crew call sites, custom tools, .env handling, plus a leaked-secrets check. Read each listed file. If the inventory finds no CrewAI artifacts, say so and stop.

Step 2 — Audit checklist

Check every artifact against this list. For deeper API context while judging, load the crewai-expert skill references (references/crews.md, references/flows.md, etc.). Severity: critical (breaks or leaks), high (wrong results or waste), medium (fragility), low (style).

Architecture

• Production logic not wrapped in a Flow (bare crew as the whole app) → recommend Flow-first.
• Agent/Crew used for deterministic work (parsing, I/O, computable branching) → plain Python step.
• LLM-based router where the decision is computable from state → plain @router returning a label.
• hierarchical process without manager_llm (breaks) or without a coordination need (waste).

Tasks

• God tasks (multiple outcomes in one description) → split.
• Vague expected_output (no format/length/sections) → tighten.
• Output consumed downstream without output_pydantic/output_json → structure it.
• Missing context links between dependent tasks.
• No guardrail on tasks feeding later steps; guardrail functions not returning (bool, Any).

Agents

• Generic role/goal/backstory ("Assistant", "Helper") → specialize.
• allow_delegation=True without demonstrated need.
• No max_rpm on crews hitting rate-limited providers.
• One giant do-everything agent → split into specialists.

Flows

• Unstructured self.state["..."] dict state in production → Flow[PydanticState].
• Long-running flow without @persist.
• Listeners/routers with side effects in router methods.

LLM config

• Anthropic model without max_tokens (breaks at call time) — critical.
• Model id without provider prefix; deprecated LiteLLM prefixes (ollama/, groq/, mistral/, ...).
• Hardcoded API keys anywhere, .env not gitignored, secrets in configs — critical.
• Same expensive model on trivial formatting steps → tier models (haiku for simple steps).
• Memory/knowledge in use with no embedder key available (default embedder is OpenAI even in all-Claude projects).

Tools

• args_schema fields without Field(description=...).
• Tools raising exceptions on expected failures instead of returning actionable messages.
• Custom tool re-implementing an existing crewai-tools tool.
• Large knowledge_sources re-embedded every kickoff (use the knowledge parameter instead).

Report format: group findings by severity; each finding = file:line — issue — concrete fix (with the reference file that justifies it). If everything passes, say so explicitly.

Step 3 — Generate/update AGENTS.md

CrewAI's convention (https://docs.crewai.com/en/guides/coding-tools/agents-md) is a repo-root AGENTS.md giving any coding agent the project's conventions, commands, architecture, and guardrails.

bash ${CLAUDE_SKILL_DIR}/scripts/project-context.sh $target_path

This dumps the full project context: tree, dependencies, config contents, flow/crew/agent/task/tool map, entry points, env var names (values redacted). Then:

1. If AGENTS.md does not exist: create it from ${CLAUDE_SKILL_DIR}/templates/AGENTS.md.template, filling every section from the context dump and audit findings.
2. If it exists: update it in place — refresh the sections that came from the template, preserve any user-written sections verbatim, and never delete content you can't map to a template section.
3. Ensure CLAUDE.md exists at the project root, symlinked to AGENTS.md — the same context must serve both AGENTS.md-reading agents (Codex, Cursor, Gemini) and CLAUDE.md-reading agents:
   • CLAUDE.md missing → ln -s AGENTS.md CLAUDE.md
   • CLAUDE.md is already a symlink to AGENTS.md → done
   • CLAUDE.md exists as a regular file with its own content → do NOT delete it; merge its unique content into AGENTS.md (preserving it verbatim under an appropriate section), then replace the file with the symlink. If the content can't be merged cleanly, keep the file and add a @AGENTS.md line instead — and tell the user why.
4. Never write secret values into AGENTS.md — env var names only.

Step 4 — Report

End with: findings summary (counts by severity), the top 3 fixes worth doing first, and what changed in AGENTS.md/CLAUDE.md. Do NOT apply fixes unless the user asks — this skill reports.