Skills require
deepagents>=1.7.0.What are skills
Each skill is a directory containing aSKILL.md file: a markdown file with YAML frontmatter (name and description) followed by instructions the agent follows when the skill is activated. A skill directory can also include supporting files such as scripts, reference docs, and templates.
SKILL.md starts with YAML frontmatter followed by markdown instructions:
Reference any supporting files in your
SKILL.md with a description of what each file contains and when to use it. The agent discovers these files through the references in the skill instructions.SkillsMiddleware handles this in three stages:
- Discovery: At agent start, the middleware scans the configured skill paths, parses each
SKILL.mdfrontmatter, and injects skill names and descriptions into the system prompt. - Read: When the agent determines a skill matches the current task, it reads the full
SKILL.mdcontent viaread_file. There is no dedicated activation mechanism. - Execute: The agent follows the skill’s instructions and reads any supporting files (scripts, references, assets) as needed.
SKILL.md body under 5,000 tokens. Following these guidelines matters because every skill’s frontmatter is added to the system prompt at discovery, while the full body is only read when activated. Keeping both layers small means you can load many skills without crowding the context window.
Usage
Create a top level skills directory. Then create a directory inside that with aSKILL.md file for your first skill. Finally, pass the path to the top level skills directory when creating your agent:
FilesystemBackend to load skills from disk. For other storage options, including loading skills from remote sources, see Backends and remote skill loading.
List of skill source paths.Paths must be specified using forward slashes and are relative to the backend’s root.
- If omitted, no skills are loaded.
- When using
StateBackend(default), provide skill files withinvoke(files={...}). Usecreate_file_data()fromdeepagents.backends.utilsto format file contents; raw strings are not supported. - With
FilesystemBackend, skills are loaded from disk relative to the backend’sroot_dir.
When multiple skill sources contain a skill with the same name, the skill from the source listed later in the
skills array takes precedence (last one wins). This lets you layer skills from different origins, such as base skills overridden by project-specific versions.Write effective skills
The Agent Skills specification includes guidance on structuring skills for reliable discovery and activation. The following recommendations build on that foundation with practical patterns for Deep Agents. Write specific descriptions. During discovery, thedescription field is the only information the agent sees for each skill. A good description tells the agent both what the skill does and when to activate it, with specific keywords the agent can match against:
SKILL.md under 500 lines. When instructions grow longer, move detailed reference material into separate files and reference them from the main SKILL.md:
SKILL.md and avoid deeply nested reference chains, which force the agent through multiple reads to reach the information it needs.
Structure instructions for the agent. Write your SKILL.md body as clear instructions the agent can follow:
- Step-by-step procedures for multi-step workflows
- Decision criteria for choosing between approaches
- Examples of expected inputs and outputs so the agent knows what success looks like
- Edge cases the agent should handle or flag to the user
- Consolidating related capabilities into a single skill with sections for each sub-task
- Using reference files to keep the main
SKILL.mdconcise while covering multiple sub-tasks
Backends and remote skill loading
Deep Agents supports different backends depending on how you want to store and manage skill files:StateBackend: Stores files in LangGraph agent state for the current thread.StoreBackend: Stores files in a LangGraph store for durable, cross-thread storage.FilesystemBackend: Reads and writes skill files from disk under a configurableroot_dir.
- StateBackend
- StoreBackend
- FilesystemBackend
Load skills at runtime
When you have a large collection of skills but only a subset is relevant for a given run, select which skills to load based on runtime context such as user role, tenant, or request type. There are two main approaches:Dynamic skill lists
The simplest approach is to construct theskills array before creating the agent. Choose which skill paths to include based on whatever runtime context you have:
Namespaced skills
For multi-tenant applications where each user’s skill set is managed independently, route/skills/ to a StoreBackend with a namespace factory. Populate each namespace with only the skills that user should have access to, and the middleware resolves to the correct set at runtime:
Skills for subagents
When you use subagents, you can configure which skills each type has access to:- General-purpose subagent: Automatically inherits skills from the main agent when you pass
skillstocreate_deep_agent. No additional configuration is needed. - Custom subagents: Do not inherit the main agent’s skills. Add a
skillsparameter to each subagent definition with that subagent’s skill source paths.
Skill permissions
By default, agents can write to skill files if the backend permits it. Use these mechanisms to control that behavior:- Read-only skills: Use filesystem permissions to deny write operations under skill paths.
- Scoped permissions: Allow writes to user-scoped skill paths while keeping workspace or shared skills read-only, so agents can personalize their own skills without modifying shared ones.
- Human-in-the-loop: Use
interrupt_onto require approval before the agent executes write operations, adding a review step without fully blocking writes.
Read-only skills
A common production pattern is to give agents access to a curated skills library without allowing them to change it. Route/skills/ to a shared StoreBackend, pass that route in skills, and deny write operations under /skills/** with filesystem permissions. The agent can discover and read skills, while only your application code or an admin workflow updates the store.
/company-policies/SKILL.md and values that include content and encoding fields. The /skills/ route prefix is stripped before records are read from the store.
Use this for enterprise knowledge bases, approved tool instructions, or shared skill packs where the agent should benefit from centrally managed context but should not rewrite the source of truth. If you want agents to save their own learnings, route a separate path such as /memories/ to another backend with write permissions enabled. See Backends for routing and store setup.
Execute code with skills
Without code execution, skills are passive: the agent reads instructions and follows them using its available tools. Code execution turns skills into active capabilities. A skill can ship a tested script that calls an API, transforms data, validates output, or runs a pipeline — and the agent executes it deterministically rather than regenerating the logic from instructions each time. This is especially valuable for workflows that require exact behavior (data transformations, API integrations, compliance checks) or that depend on libraries the agent cannot use through tool calls alone. Skills support code execution in two ways:- Sandbox scripts when the agent needs to install dependencies, run tests, call CLIs, or work with an operating-system filesystem.
- Interpreter skills when the agent needs reusable, importable helpers available from interpreter code.
Sandbox scripts
Skills can include scripts alongside theSKILL.md file. Reference scripts in your SKILL.md so the agent knows they exist and when to run them:
before_agent: Read skill files from the backend and upload them into the sandbox so the agent can execute scripts from the start.after_agent: Download any updated or newly created skill files from the sandbox and write them back to the backend so changes persist across runs.
Interpreter skills
Interpreter skills expose code modules to an interpreter. Regular skills give the agent instructions and context. Interpreter skills also give the agent importable functions it can call from interpreter code. This lets you package domain-specific logic once and make it available as a deterministic building block. Instead of asking the model to re-create a parser, validator, or aggregation routine from scratch, the agent can import a tested helper and compose it with tools, subagents, and runtime state. Use interpreter skills for code that should be:- Reusable across prompts, agents, or projects
- Deterministic enough that you want the same behavior every time
- Too detailed to keep in the model context as instructions
Add an entrypoint
Add a
metadata.entrypoint key to the skill’s SKILL.md frontmatter. The value is a JavaScript or TypeScript file path relative to the skill directory.Configure skills normally
Pass the skill source path with the
skills argument when creating the agent.Use the same backend
Configure the interpreter middleware with the same backend that
SkillsMiddleware uses to load skill files.Reference
Skills, memory, and tools
Skills, memory (AGENTS.md files), and tools all provide context or capabilities to the agent. The following table summarizes when to reach for each:
| Skills | Memory | Tools | |
|---|---|---|---|
| Purpose | On-demand capabilities discovered through progressive disclosure | Persistent context loaded at startup | Programmatic actions the agent can call |
| Loading | Read only when the agent determines relevance | Loaded at agent start | Available every turn |
| Format | SKILL.md in named directories | AGENTS.md files | Functions bound to the agent |
| Layering | User, then project (last wins) | User, then project (combined) | Defined at agent creation |
| Use when | Instructions are task-specific and potentially large | Context is always relevant (project conventions, preferences) | The agent needs a programmatic action, or does not have access to the file system |
Frontmatter fields
The Agent Skills specification defines the following frontmatter fields:| Field | Required | Description |
|---|---|---|
name | Yes | Lowercase alphanumeric with hyphens, 1-64 characters. Must match the parent directory name. |
description | Yes | What the skill does and when to use it. Max 1,024 characters. |
license | No | License name or reference to a bundled license file. |
compatibility | No | Environment requirements (system packages, network access). Max 500 characters. |
metadata | No | Arbitrary key-value pairs for additional properties. |
allowed-tools | No | Space-separated list of pre-approved tools the skill can use. Experimental. |
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

