design-agent skill (crewAIInc): design and tune CrewAI agents

crewAI's own skill that guides a coding agent on designing and configuring CrewAI agents: roles, tools, limits, memory and knowledge.

Installs: 8.5K; on skills.sh
Stars: 48; on GitHub
Files: 2; besides SKILL.md
Updated: Oct 2026; last repo commit

design-agent makes your coding agent follow CrewAI's rules for building agents: default to one agent, write role, goal and backstory carefully, and set limits that behave the way the docs say. It also covers LLM choice, tools, planning, guardrails, knowledge sources and YAML versus code config.

It loads when you create, configure or debug a CrewAI agent. It edits your agent code and config files. SKILL.md says that where it disagrees with check-crewai-api or connect-tools-and-mcp, those skills win.

Good for

Python developers building agents or crews with the CrewAI framework
Developers whose agent loops, goes off-topic or ignores its tools
People deciding how many agents a workflow really needs

Install design-agent

Claude Code

Copy this prompt.

Install the design-agent skill in Claude Code. Run this command:

/plugin marketplace add crewAIInc/skills
/plugin install crewai-skills@crewai-plugins

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both, or you get every skill twice. The README documents the plugin route for Claude Code. The plugin installs all 10 skills in the crewai-skills plugin; the skills CLI route installs design-agent, check-crewai-api, connect-tools-and-mcp. design-agent says to follow check-crewai-api and connect-tools-and-mcp where they disagree with it. design-task, build-flow and the rest are optional hand-offs.

From the project README. Source.

What's in the skill

When it loads

CrewAI agent design and configuration. Use when creating, configuring, or debugging crewAI agents — choosing role/goal/backstory, selecting LLMs, assigning tools, tuning max_iter/max_rpm/max_execution_time, enabling planning/delegation, setting up knowledge sources, using guardrails, or configuring agents in YAML vs code.

Sections in SKILL.md

The 80/20 Rule
0. How Many Agents Do You Actually Need?
Anti-patterns
Once you've decided "one agent is enough"
1. The Role-Goal-Backstory Framework
Role — Who the Agent Is
Goal — What the Agent Wants
Backstory — Why the Agent Is Qualified
2. Agent Configuration Reference
Execution limits (measured on 1.15.23)
Tools
LLM Selection
Collaboration
Planning (Plan-and-Execute Mode)
Code Execution
Agent Guardrails

Key facts

Author: crewAI (the crewAIInc organisation); the plugin manifest names crewAI as author and the repo is the vendor's own
License: MIT (LICENSE file and README agree)
Installs on skills.sh: 8,525 as of 2026-11-02
GitHub stars: 48 for the whole crewAIInc/skills repo, 2026-11-02
What is inside: 3 files: SKILL.md and 2 files in references/ (custom tools, memory and knowledge). It bundles no scripts.
Last change to this skill: 2026-10-06
Part of: The crewai-skills plugin (10 skills) in the crewai-plugins marketplace
Checked against: crewai 1.15.23 on 2026-10-01, per the SKILL.md

What it includes

Default to one agent unless the work really splits
Gives four reasons to add another: different tools or permissions, personas, LLMs, or guardrails. It warns that every extra agent costs at least one more LLM kickoff.
Read · How many agents
How to write the three fields that shape an agent
Section 1 covers each field separately, with good and bad examples.
Write · Role, goal, backstory
Execution limits, tools, LLM choice, delegation and planning
Explains what max_iter, max_rpm and max_execution_time really do on crewai 1.15.23. For example, reaching max_iter does not raise an error.
Write · Configuration reference
Validate output with a function or an LLM check
Notes two limits on 1.15.23: agent guardrails run only on Agent.kickoff(), and the retry re-sent the original prompt without feedback. It prefers task-level guardrails.
Write · Agent guardrails
Sources, embedders that work without OpenAI, scoping
Warns that knowledge defaults to OpenAI embeddings and fails without OPENAI_API_KEY. The deeper guide is references/memory-and-knowledge.md.
Write · Knowledge and memory
Recommended way to define agents
Shows agents.yaml wired into a crew class.
Write · YAML configuration
Run one agent directly, including inside a Flow
Covers direct agent runs, structured output and file inputs, which need the crewai[file-processing] extra.
Runs code · Agent.kickoff()
Common errors and a closing review list
Sections 7 and 8 list common agent design mistakes and a checklist.
Read · Mistakes and checklist

From the official docs

Permissions

Low risk

The agent edits your CrewAI code and config files, and can run agents that call your model provider with your own API key. Review the diff and set a spending limit with your provider before you run what it writes.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It edits your project files
It changes agent definitions and config. Work in a git branch and read the diff. github.com
Test runs spend model credits
With no llm set, agents default to an OpenAI model and need OPENAI_API_KEY. Lower max_iter while testing. github.com
The plugin route installs all 10 skills
The crewai-skills plugin manifest lists 10 skills and holds no hooks, agents or MCP config in the git tree. Use the skills CLI route if you want only the skills this page names. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Talks to	Your model provider (OpenAI by default when no llm is set)
Sign-in and keys	Agents read provider keys such as OPENAI_API_KEY from your environment.
Scopes	Edits agent code and YAML config in your project Can run Agent.kickoff() examples, which call your model provider SKILL.md mentions uv add for extras such as crewai[anthropic] and crewai[file-processing]

Questions

What does the design-agent skill do?

It guides your coding agent on designing CrewAI agents: how many to use, how to write role, goal and backstory, which limits and tools to set, and how to configure knowledge and guardrails.

How do I install design-agent?

Use the install box at the top of this page. The README documents a Claude Code plugin with all 10 CrewAI skills. The skills CLI route in the box adds check-crewai-api and connect-tools-and-mcp, which design-agent says to follow where they disagree with it.

Does it need other skills?

Two of them matter: SKILL.md says check-crewai-api (exact API forms) and connect-tools-and-mcp (tools and MCP) win where they disagree, so the skills CLI route installs both. It also points to design-task and build-flow as optional hand-offs.

Does design-agent need an API key?

The skill itself does not. Agents you run need a provider key: SKILL.md says that with no llm set the default is an OpenAI model, so kickoff fails without OPENAI_API_KEY.

Is design-agent safe?

It edits your project files and may run agents that call your model provider. Use a branch, read the diff and cap your provider spending.

Is this the official CrewAI skill?

Yes, it is in the crewAIInc organisation's own repo, and the plugin manifest names crewAI as author.

design-agent or design-task?

design-agent is about the agent: role, tools, limits, memory. design-task is about the task: description, expected output, context and guardrails. SKILL.md says to spend about 80 percent of effort on task design and 20 percent on agent design.

Does it work in the Claude app or Codex?

The README documents Claude Code only. The skill edits project files, so there is no Claude app upload option here. The box lists the Codex skills folder as a generic route.

Information

updated Nov 2, 2026

Repository: crewaiinc/skills
Folder: skills/design-agent

crewaiinc/skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4

README.md · github.com
marketplace.json · github.com
plugin.json · github.com
SKILL.md · github.com