How to Extend Deep Agents with Custom Skills

Mar 20, 2026

I was building a SQL query agent last week, and it kept struggling with complex joins. The agent knew the basics, but when it came to domain-specific patterns—like how to efficiently explore a database schema or write optimized queries with CTEs—it would fumble. I didn’t want to stuff all that knowledge into the base prompt because it would bloat the context window for every query.

Then I discovered Deep Agents’ skills system.

The Problem with Generic Agents

When you build an AI agent, you face a tension: generic prompts work okay for common tasks, but domain-specific work requires specialized knowledge. You could add all that knowledge to your base prompt, but then every query pays the token cost—even when that expertise isn’t needed.

I tried this approach first. My agent’s system prompt grew to 3000+ tokens with documentation about query optimization, schema exploration patterns, and best practices. The result? Slower responses and higher costs for simple queries that didn’t need any of that.

What I needed was progressive disclosure—let the agent know what specialized capabilities exist, but only load the full instructions when needed.

How Skills Work

Skills in Deep Agents solve this through a simple but clever pattern. Each skill is a SKILL.md file in its own directory:

skills/
├── query-writing/
│   └── SKILL.md    # Instructions for writing SQL queries
└── schema-exploration/
    └── SKILL.md    # Instructions for database discovery

The agent sees a brief description of each available skill in its context. When it determines a skill is relevant, it loads the full SKILL.md instructions on demand. This keeps the initial context lean while still providing deep expertise when needed.

Setting Up SkillsMiddleware

In your Deep Agents configuration, you add SkillsMiddleware with paths to your skill directories:

from deepagents import SkillsMiddleware, create_agent

skills_paths = [
    "/skills/project/",
    "/skills/user/",
]

agent = create_agent(
    middleware=[
        SkillsMiddleware(backend=backend, sources=skills_paths)
    ]
)

An important detail: later sources override earlier ones for skills with the same name. This lets you have project-level defaults that users can customize in their personal skill directories.

A Real Example: SQL Query Writing

Here’s a skill I wrote for my SQL agent:

# Query Writing Skill

## When to Use
- User asks to query data from tables
- Need to JOIN multiple tables
- Aggregations or window functions required

## Workflow

1. **Understand the Goal**: Clarify what data the user needs
2. **Explore Schema**: Use schema-exploration skill if unfamiliar
3. **Draft Query**: Write the SQL with proper JOINs and filters
4. **Validate**: Check for common issues (N+1, missing indexes)
5. **Execute**: Run the query and explain results

## Best Practices

- Prefer CTEs for complex logic over nested subqueries
- Use window functions for running totals and rankings
- Always include LIMIT for exploratory queries
- Index columns used in WHERE clauses

## Example Pattern

```sql
-- Running total with window function
SELECT
    date,
    revenue,
    SUM(revenue) OVER (ORDER BY date) as running_total
FROM daily_sales
ORDER BY date;

The agent now knows: "I have a query-writing skill available." When the user asks "Show me monthly revenue trends", the agent loads this full skill and follows the workflow.

## Why This Matters

The skills approach gives you three key benefits:

1. **Context Efficiency**: Base prompts stay small. My SQL agent went from 3000+ tokens to ~500 tokens in the base prompt, with skills loading only when needed.

2. **Reusability**: Skills are portable. I can share my `query-writing` skill across projects, and team members can use it in their agents.

3. **Progressive Enhancement**: Start simple, add skills as needed. My agent began with just query-writing, then I added schema-exploration when I noticed it struggled with unfamiliar databases.

## CLI Integration

The Deep Agents CLI supports skills out of the box. You can load skills from GitHub repositories:

```yaml title="action.yml"
inputs:
  skills_repo:
    description: 'GitHub repository containing skills'
    required: false
    default: ''

Skills are cloned and installed automatically, making it easy to share specialized workflows across teams.

The Trade-offs

Skills aren’t always the right solution. For agents with narrow, well-defined purposes, putting everything in the base prompt is simpler. Skills shine when:

Your agent handles multiple types of requests
Different workflows have specialized knowledge
You want to share capabilities across projects
Context window efficiency matters

For my SQL agent, skills were the right call. For a simple “summarize this text” agent, they’d be overkill.

Getting Started

To add skills to your Deep Agent:

Create a skills/ directory in your project
Add skill directories with SKILL.md files
Configure SkillsMiddleware with your skill paths
Run your agent and observe which tasks trigger skill loading

The documentation at the Deep Agents site has more examples, but the pattern is straightforward: describe the skill briefly, implement the workflow, and let the agent decide when to use it.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!