Guide · Agent skill
How to use the Swarms multi-agent framework agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The swarms skill teaches an AI coding agent how to write, review and debug Python code that uses the Swarms multi-agent framework. It is for developers who build LLM applications from agents that have a model, a system prompt and optional Python tools. After this guide you will know how to install the skill, trigger it with plain requests, and check the code it produces.
Swarms Multi-Agent Frameworkkyegomez/swarms · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Get the swarms skill ZIP from the directory page.
- 2Unzip the skill folder. Unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project.
- 3Or upload it in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload the skill if you use the apps.
- 4Install swarms and set a key. Run pip install -U swarms and export the API key for your model provider.
- 5Ask in plain words. Describe the agent or workflow you want and name the framework, for example a sequential workflow of two agents.
- 6Run and check the code. Run the generated file yourself and confirm that max_loops and tools are set as the guide describes.
What the swarms skill makes the agent do
Swarms builds everything from one primitive, the Agent class, and combines agents into multi-agent structures. The skill loads a condensed guide into your coding assistant so it knows the main classes, parameters and common pitfalls before it writes code.
The skill covers the Agent class, tools, autonomous loops, memory and the multi-agent architectures named in its description, including SequentialWorkflow, ConcurrentWorkflow, GraphWorkflow, HierarchicalSwarm and SwarmRouter.
- Scaffold Agent classes with a model, system prompt and optional tools
- Wire agents into sequential, concurrent, hierarchical or routed workflows
- Add MCP servers, streaming or handoffs to an agent
- Review and debug existing code that imports swarms
Install the swarms skill in Claude
Download the ZIP from the directory page and unzip it. Place the folder in your personal skills folder at ~/.claude/skills/, or in a project's .claude/skills/ folder if you want the skill only for that project.
If you use the Claude apps instead, upload the skill under Settings, then Capabilities, then Skills.
The skill is packaged as a SKILL.md file with a name and description. Your assistant reads the description to decide when to use it.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills
Set up the Python package and API key
The code the skill writes needs the swarms Python package and an API key for your model provider. The source names OPENAI_API_KEY, ANTHROPIC_API_KEY and GROQ_API_KEY as examples, and says any LiteLLM model string works. A local model endpoint is also supported.
The skill's guide also mentions a WORKSPACE_DIR variable, which sets where agent state and memory are stored.
- Install the package with pip
- Set the key for the provider you use
- Optional: python-dotenv, used by the example.py file
pip install -U swarms
export OPENAI_API_KEY="sk-..."
export WORKSPACE_DIR="agent_workspace"Trigger the skill with natural requests
You do not need a special command. The skill is meant to activate when you write, review or debug code that imports swarms, so name the framework and the task in plain words.
Good requests say what the agent should do and which structure you want. Mention the file if you are debugging existing code.
- Write a Swarms agent that summarizes a document and set max_loops to 1
- Add a get_stock_price tool to my Swarms agent and make it call the tool
- Build a sequential workflow of a researcher agent and a writer agent
- Debug why this file that imports swarms ignores my tools
Example: an agent with a tool
The guide's tool pattern is a plain Python function with type hints and a docstring. The framework turns it into a tool schema automatically, and the docstring is the description the model reads, so it should be written for the model.
The guide sets max_loops above 1 for tool use. Loop 1 calls the tool and loop 2 uses the result.
- Pass tools=None, not tools=[], when there are no tools
- Give each agent a unique agent_name
from swarms import Agent
def get_stock_price(ticker: str) -> str:
"""Fetch the current stock price for a ticker symbol.
Args:
ticker: Stock ticker symbol, e.g. 'AAPL'.
Returns:
The current price as a formatted string.
"""
import yfinance as yf
return f"{ticker}: ${yf.Ticker(ticker).fast_info['last_price']:.2f}"
agent = Agent(
agent_name="StockAnalyst",
model_name="gpt-5.4",
tools=[get_stock_price],
max_loops=3,
)
agent.run("What are Apple and Microsoft trading at?")Know the safety and network notes
The skill's metadata says it does not run scripts and does use the network. The code it writes calls LLM providers using your keys. The skill can also point an assistant at hosted MCP servers.
The docs MCP server needs no key. The marketplace MCP server needs a Swarms API key for calls. The example.py file is a generic demo prompt for a trading-style agent and does not provide validated investment advice.
- Keep provider keys in environment variables, not in code
- Docs MCP server at https://docs.swarms.world/mcp needs no key
- Marketplace MCP server at https://swarms.world/mcp needs a Swarms API key
- Do not treat example.py output as investment advice
Tips for better results
Ask the skill to check the examples folder first. The guide says it contains 586 runnable examples, and one is often close to what you need.
When a signature in the skill disagrees with your installed version, check the live docs. The guide notes that the skill can lag the library.
- Default to max_loops=1 and raise it only for real multi-step work
- Use max_loops="auto" only for genuinely open-ended work
- Never set streaming_on=True and streaming_callback together
- Ask for a plain Python file you can run and read the output yourself
What people use it for
- Scaffold a single Agent with a model, system prompt and max_loops=1 for a summary task
- Add Python tools to an agent that must look up live data before answering
- Build a sequential or concurrent workflow of several agents
- Connect an agent to an MCP server and list its tools before wiring it up
- Review existing swarms code for missing tools=None or unset agent_name values
Frequently asked questions
How do I install the swarms agent skill?
Download the ZIP from the directory page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, upload it under Settings, then Capabilities, then Skills.
What do I need to use the swarms skill?
You need Python with the swarms package (pip install -U swarms) and an API key for your model provider, such as OPENAI_API_KEY or ANTHROPIC_API_KEY, or a local model endpoint. python-dotenv is optional and used by example.py. A Swarms API key is optional, for the marketplace MCP server.
Is the swarms skill free to use?
The project is licensed under Apache-2.0. The skill itself is a set of instructions for your assistant. Your model provider's API usage is a separate arrangement with that provider.
Why does my swarms code fail when I pass tools=[]?
The guide says an empty list breaks schema generation. Pass tools=None when an agent has no tools, and pass a list of functions only when it has some.
Why does my agent not use its tool?
The guide says max_loops must be greater than 1 for tool use, because loop 1 calls the tool and loop 2 uses the result. Also check that the tool has type hints and a clear docstring, since the model reads the docstring.
Does the swarms skill work with other frameworks or only Swarms?
It only helps with code that uses the swarms framework. It does not cover other agent libraries, and it is not for people who do not write Python.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you write or debug Python code with the Swarms framework and want an assistant that knows its classes, parameters and workflows. Pick something else if you do not use Python or the swarms library, because the skill does not help with other code.
Download the skill