Skills

Learn how to extend your deep agent’s capabilities with skills

Skills package domain expertise, such as workflows, best practices, scripts, reference docs, and templates, into reusable directories. The agent gets a summary of the contents on startup and discovers and reads the contained files only when relevant.

Skills help you avoid context bloat by loading only summaries at startup and reading full instructions when a task requires them. You can share skills across agents and projects, and compose multiple skills in a single agent so each one covers a distinct capability.

Skills require deepagents>=1.7.0.

For ready-to-use skills that improve your agent’s performance on LangChain ecosystem tasks, see the LangChain Skills repository.

Usage

1. Create a top-level skills directory

   Create a directory to hold all skills for your project, such as skills/ under your backend root.

2. Create a subdirectory inside your skills directory for your skill

   Each skill is a directory containing a SKILL.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 optionally include supporting files such as scripts, reference docs, and templates.

   skills

   langgraph-docs

   SKILL.md

   scripts

   references

   assets

   Deep agent skills follow the Agent Skills specification.

3. Add a `SKILL.md` file with YAML frontmatter and instructions.

   The SKILL.md starts with YAML frontmatter followed by markdown instructions:

   ---
   name: langgraph-docs
   description: Use this skill for requests related to LangGraph in order to fetch relevant documentation to provide accurate, up-to-date guidance.
   ---
   
   # langgraph-docs
   
   ## Overview
   
   This skill explains how to access LangGraph documentation to help answer questions and guide implementation.
   
   ## Instructions
   
   ### 1. Fetch the documentation index
   
   Use the fetch_url tool to read the following URL:
   https://docs.langchain.com/llms.txt
   
   This provides a structured list of all available documentation with descriptions.
   
   ### 2. Select relevant documentation
   
   Based on the question, identify 2-4 most relevant documentation URLs from the index. Prioritize:
   
   - Specific how-to guides for implementation questions
   - Core concept pages for understanding questions
   - Tutorials for end-to-end examples
   - Reference docs for API details
   
   ### 3. Fetch and synthesize
   
   Use the fetch_url tool to read the selected documentation URLs, then answer the user's question. Give a direct answer first, include the minimum necessary context, and link to the source pages rather than quoting long passages.
   

   Reference any supporting resources 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.

4. Pass the skills path when creating your agent

   Pass the path to your top-level skills directory in the skills argument when creating your agent:

   import { createDeepAgent, FilesystemBackend } from "deepagents";
   
   const backend = new FilesystemBackend({ rootDir: process.cwd() });
   
   const agent = await createDeepAgent({
     model: "anthropic:claude-sonnet-4-6",
     backend,
     skills: ["/skills/"],
   });
   

   This example uses FilesystemBackend to load skills from disk. For other storage options, including loading skills from remote sources, see Backends and remote skill loading.

   skills · list[str]

   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 with invoke(files={...}). Use create_file_data() from deepagents.backends.utils to format file contents; raw strings are not supported.
   • With FilesystemBackend, skills are loaded from disk relative to the backend’s root_dir.

   Later sources override earlier ones for skills with the same name (last one wins).

   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.

5. Invoke the agent

   Send a task to the agent with invoke(). At startup, the agent loads each skill’s name and description from frontmatter into the system prompt. When your task matches a skill’s description, the agent reads that skill’s SKILL.md and follows its instructions.

   const result = await agent.invoke(
     { messages: [{ role: "user", content: "What is LangGraph?" }] },
     { configurable: { thread_id: "1" } },
   );
   

How skills work

As agents take on more complex tasks, the context they need grows with them. Loading all instructions into the system prompt wastes tokens on information irrelevant to the current task, and providing the same guidance manually across sessions does not scale.

Skills use progressive disclosure: the agent loads skill information in layers instead of all at once. At startup, it sees only each skill’s name and description. When a skill is invoked, it reads the full SKILL.md instructions. Supporting files load afterward, only when the instructions call for them.

Skills load in three levels. Each level adds more detail only when the task needs it:

Level	What loads	When
1. Metadata	name and description from SKILL.md frontmatter	Agent startup, for every configured skill
2. Instructions	Full SKILL.md body	When the skill is invoked
3. Resources	Supporting files under scripts/, references/, and assets/	As needed after invocation, when the instructions reference them

The following diagram shows what appears in agent context at a given moment. At startup, level 1 metadata for every skill is in the system prompt. When a skill is invoked, level 2 instructions join the context. Level 3 files stay on the backend until the agent reads them after invocation.

As the agent works through a task, it loads skill information in layers:

In Deep Agents, SkillsMiddleware handles the first two levels, with the third level being handled by the LLM:

1. Discovery (level 1): At agent start, the middleware scans the configured skill paths, parses each SKILL.md frontmatter, and injects the name and description fields into the system prompt.
2. Read (level 2): When the agent invokes a skill, it reads the full SKILL.md content via read_file.
3. Execute (level 3): After invocation, the agent follows the skill’s instructions and reads supporting files (scripts, references, assets) only as the instructions require.

When to use skills

If you find yourself giving similar instructions to an agent, especially if they are detailed and contain multiple steps, consider codifying the instructions for the agent. That way, in future when you want to accomplish a similar task, the agent will already know what to do.

You can also ask your agent to write a skill for a task you worked on with the agent.

Skills are especially helpful for codifying:

• Step-by-step workflows: Workflows that span multiple steps, similar to recipes.
• Domain-specific knowledge: Instruct the agent on how to use tools for the workflow. For example, include information on where to pull information from, including other reference information or scripts that the skill may have access to.
• Instructions with executable code: Bundle procedures with scripts or modules the agent can run, so it follows tested logic instead of regenerating it from instructions each time. See Execute code with skills.
• Guidelines: Provide the agent with supporting instructions about guardrails to adhere to. For example, following a specific format or style guide, or specifying to always run tests as part of the workflow.

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.

Keep frontmatter concise and the SKILL.md body under 5,000 tokens. 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.

Write specific descriptions. During discovery, the description 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:

# Good: specific about what and when
description: >-
  Extract text and tables from PDF files, fill PDF forms, and merge
  multiple PDFs. Use when working with PDF documents or when the user
  mentions PDFs, forms, or document extraction.

# Poor: too vague for reliable matching
description: Helps with PDFs.

When you have multiple skills in related domains, differentiate their descriptions clearly. Overlapping descriptions cause the agent to activate the wrong skill or hesitate between options. If two skills serve similar purposes, consolidate them into one.

Keep instructions focused. The Agent Skills specification recommends keeping your SKILL.md under 500 lines. When instructions grow longer, move detailed reference material into supporting resource files and reference them from the main SKILL.md:

skills

data-pipeline

SKILL.md

references

schema-reference.md

error-codes.md

The agent loads reference files only when the instructions call for them, keeping each layer of progressive disclosure appropriately sized. Keep file references one level deep from 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

Manage skill count. Fewer well-scoped skills outperform many overlapping ones. As the number of skills with similar descriptions grows, the agent’s ability to select the right one degrades. If you find yourself with many related skills, consider:

• Consolidating related capabilities into a single skill with sections for each sub-task
• Using reference files to keep the main SKILL.md concise while covering multiple sub-tasks

Use the skills-ref validation tool to check that your SKILL.md frontmatter follows the Agent Skills specification naming and format conventions.

Add supporting resources

Beyond SKILL.md, a skill directory can include any additional files or directories. The Agent Skills specification defines three optional directories for common resource types. Deep Agents does not load these files at discovery or activation. The agent reads or executes them only when your SKILL.md instructions say to.

scripts/

The scripts/ directory holds executable code the agent can run, such as API clients, data transforms, or validation checks. Scripts should:

• Be self-contained or clearly document dependencies
• Include helpful error messages
• Handle edge cases gracefully

Supported languages depend on your agent setup. Common options include Python, Bash, and JavaScript or TypeScript. To execute scripts rather than only read them, see Execute code with skills. Use sandbox scripts when the agent needs a shell, or interpreter skills when the agent needs importable helpers in an interpreter.

references/

The references/ directory holds supplementary documentation the agent reads on demand. Use it for material that is too detailed for SKILL.md but still task-specific, such as:

• REFERENCE.md for detailed technical reference
• FORMS.md for form templates or structured data formats
• Domain-specific guides (finance.md, legal.md, and similar)

Keep individual reference files focused. The agent loads them only when needed, so smaller files use less context.

assets/

The assets/ directory holds static resources the agent uses but does not need to read as instructions, such as:

• Document or configuration templates
• Images (diagrams, examples)
• Data files (lookup tables, schemas)

Describe in SKILL.md when the agent should open or copy each asset.

Reference files from SKILL.md

When you reference supporting files, use paths relative to the skill root:

For API details, see the [reference guide](references/api-patterns.md).

To extract tables from a PDF, run:
scripts/extract.py

For each file you reference, state what it contains and when the agent should use it. Keep references one level deep from SKILL.md. Avoid deeply nested reference chains that force the agent through multiple reads to reach the information it needs.

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 configurable root_dir.

StateBackend

import { createCodeInterpreterMiddleware } from "@langchain/quickjs";
import { createDeepAgent, StateBackend, type FileData } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";

const checkpointer = new MemorySaver();
const backend = new StateBackend();

function createFileData(content: string): FileData {
  const now = new Date().toISOString();
  return {
    content: content.split("\n"),
    created_at: now,
    modified_at: now,
  };
}

const skillsFiles: Record<string, FileData> = {};
const skillUrl =
  "https://raw.githubusercontent.com/langchain-ai/deepagentsjs/refs/heads/main/examples/skills/langgraph-docs/SKILL.md";
const response = await fetch(skillUrl);
const skillContent = await response.text();

skillsFiles["/skills/langgraph-docs/SKILL.md"] = createFileData(skillContent);

const agent = await createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  backend,
  checkpointer, // Required !
  // IMPORTANT: deepagents skill source paths are virtual (POSIX) paths relative to the backend root.
  skills: ["/skills/"],
  middleware: [createCodeInterpreterMiddleware({ skillsBackend: backend })],
});

const config = { configurable: { thread_id: `thread-${Date.now()}` } };
const result = await agent.invoke(
  {
    messages: [{ role: "user", content: "what is langraph?" }],
    files: skillsFiles,
  },
  config,
);

StoreBackend

import { createCodeInterpreterMiddleware } from "@langchain/quickjs";
import { createDeepAgent, StoreBackend, type FileData } from "deepagents";
import { InMemoryStore, MemorySaver } from "@langchain/langgraph";

const checkpointer = new MemorySaver();
const store = new InMemoryStore();
const backend = new StoreBackend({
  namespace: () => ["filesystem"],
});

function createFileData(content: string): FileData {
  const now = new Date().toISOString();
  return {
    content: content.split("\n"),
    created_at: now,
    modified_at: now,
  };
}

const skillUrl =
  "https://raw.githubusercontent.com/langchain-ai/deepagentsjs/refs/heads/main/examples/skills/langgraph-docs/SKILL.md";

const response = await fetch(skillUrl);
const skillContent = await response.text();
const fileData = createFileData(skillContent);

await store.put(["filesystem"], "/skills/langgraph-docs/SKILL.md", fileData);

const agent = await createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  backend,
  store,
  checkpointer,
  // IMPORTANT: deepagents skill source paths are virtual (POSIX) paths relative to the backend root.
  skills: ["/skills/"],
  middleware: [createCodeInterpreterMiddleware({ skillsBackend: backend })],
});

const config = {
  recursionLimit: 50,
  configurable: { thread_id: `thread-${Date.now()}` },
};
const result = await agent.invoke(
  { messages: [{ role: "user", content: "what is langraph?" }] },
  config,
);

FilesystemBackend

import { createCodeInterpreterMiddleware } from "@langchain/quickjs";
import { createDeepAgent, FilesystemBackend } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";

const checkpointer = new MemorySaver();
const backend = new FilesystemBackend({ rootDir: process.cwd() });

const agent = await createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  backend,
  skills: ["./examples/skills/"],
  interruptOn: {
    read_file: true,
    write_file: true,
    delete_file: true,
  },
  checkpointer, // Required!
  middleware: [createCodeInterpreterMiddleware({ skillsBackend: backend })],
});

const config = { configurable: { thread_id: `thread-${Date.now()}` } };
const result = await agent.invoke(
  { messages: [{ role: "user", content: "what is langraph?" }] },
  config,
);

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 the skills array before creating the agent. Choose which skill paths to include based on whatever runtime context you have:

import { createDeepAgent } from "deepagents";

const SKILLS_BY_ROLE: Record<string, string[]> = {
  engineering: ["/skills/code-review/", "/skills/testing/", "/skills/deployment/"],
  data: ["/skills/sql-analysis/", "/skills/visualization/", "/skills/data-pipeline/"],
  support: ["/skills/ticket-triage/", "/skills/runbook/"],
};

function createAgentForUser(userRole: string) {
  return createDeepAgent({
    model: "anthropic:claude-sonnet-4-6",
    skills: SKILLS_BY_ROLE[userRole] ?? [],
  });
}

This works well when skills live on disk or in a shared backend and you just need to control which ones the agent sees. The skills themselves are not duplicated — you maintain one copy and vary the paths passed to each run.

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:

import {
  createDeepAgent,
  CompositeBackend,
  StateBackend,
  StoreBackend,
} from "deepagents";

const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  skills: ["/skills/"],
  backend: new CompositeBackend({
    default: new StateBackend(),
    routes: {
      "/skills/": new StoreBackend({
        namespace: (ctx) => [
          ctx.assistantId ?? "default",
          ctx.config?.configurable?.user_id ?? "anonymous",
        ],
      }),
    },
  }),
});

This pattern is useful when different users or tenants need fully independent skill libraries that can be updated separately. For a managed solution that handles skill access, sharing, and workspace-level visibility out of the box, see Fleet skills.

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 skills to create_deep_agent. No additional configuration is needed.
• Custom subagents: Do not inherit the main agent’s skills. Add a skills parameter to each subagent definition with that subagent’s skill source paths.

Skill state is fully isolated: the main agent’s skills are not visible to subagents, and subagent skills are not visible to the main agent.

const researchSubagent = {
  name: "researcher",
  description: "Research assistant with specialized skills",
  systemPrompt: "You are a researcher.",
  tools: [webSearch],
  skills: ["/skills/research/", "/skills/web-search/"],  // Subagent-specific skills
};

const agent = await createDeepAgent({
  model: "google_genai:gemini-3.5-flash",
  skills: ["/skills/main/"],  // Main agent and GP subagent get these
  subagents: [researchSubagent],  // Researcher gets only its own skills
});

For more information on subagent configuration and skills inheritance, see Subagents.

Skill permissions

Production deployments usually need to control three things: which skills each user can see, whether the agent can modify skill files, and whether writes require human approval. You control visibility with the skills argument and backend routing, access with filesystem permissions, and approval with interrupt_on or permission rules with mode="interrupt".

Share skills across users

To give every user access to the same curated library, route /skills/ to a shared StoreBackend and seed it from your application code or an admin workflow. Use an organization-scoped namespace so all agents in that org resolve to the same store:

• Namespace by org ID for workspace-wide skills (see Enforce read-only skills).
• Namespace by user ID when each user needs an independent library (namespaced skills).

Seed the store with keys like /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.

For a managed solution that handles skill access, sharing, and workspace-level visibility, see Fleet skills.

You can also combine shared and personal libraries: route /skills/shared/ to an organization-scoped StoreBackend, route /skills/personal/ to a user-scoped backend, and pass both paths in skills. See Allow agents to write skills.

Limit skills by user context

Not every user should see every skill. Control which skills load at runtime based on role, tenant, or other request context. There are two main approaches:

• Dynamic skill lists — Build the skills array before creating the agent. Pass different path lists for different roles or request types. Works when skills live in a shared backend and you filter by path.
• Namespaced skills — Route /skills/ to a StoreBackend with a namespace factory keyed on user or tenant ID. Populate each namespace with only the skills that identity should access.

These patterns work alongside the read and write controls below. For example, you can give admins a larger skill set than engineers while keeping both libraries read-only.

Enforce read-only skills

To share skills without letting agents modify them, route /skills/ to a shared store and deny write operations under /skills/** with filesystem permissions. The agent can discover and read skills; only your application code or an admin workflow updates the store.

Google

import { InMemoryStore } from "@langchain/langgraph";
import {
  createDeepAgent,
  CompositeBackend,
  StateBackend,
  StoreBackend,
} from "deepagents";

const store = new InMemoryStore(); // Good for local dev; omit for LangSmith Deployment

const agent = createDeepAgent({
  model: "google-genai:gemini-3.5-flash",
  backend: new CompositeBackend(new StateBackend(), {
    "/skills/": new StoreBackend({
      namespace: (rt) => ["curated-skills", rt.context.orgId],
    }),
  }),
  skills: ["/skills/"],
  permissions: [
    {
      operations: ["write"],
      paths: ["/skills/**"],
      mode: "deny",
    },
  ],
  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.

Require approval for skill writes

If agents may write to skill files but you want a human in the loop first, use either interrupt_on or a permission rule with mode="interrupt". Both pause before write_file or edit_file runs and use the same resume flow.

import { MemorySaver } from "@langchain/langgraph";
import { createDeepAgent } from "deepagents";

const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  skills: ["/skills/personal/"],
  permissions: [
    {
      operations: ["write"],
      paths: ["/skills/**"],
      mode: "interrupt",
    },
  ],
  checkpointer: new MemorySaver(), // Required to pause and resume
});

Alternatively, configure interrupt_on={"write_file": True, "edit_file": True} to require approval for all filesystem writes, not only skills paths. See Human-in-the-loop for handling and resuming interrupts.

Allow agents to edit personal skills

By default, agents can write to skill files if the backend permits it and no permission rule blocks the path. To let agents create or refine skills without touching shared libraries:

1. Route a writable path such as /skills/personal/ to a user-scoped StoreBackend.
2. Pass that path (along with any shared paths) in skills.
3. Do not add a deny rule for the writable path. Place more specific rules before broader deny rules if you mix shared and personal paths (rule ordering).

import {
  createDeepAgent,
  CompositeBackend,
  StateBackend,
  StoreBackend,
} from "deepagents";

const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  backend: new CompositeBackend({
    default: new StateBackend(),
    routes: {
      "/skills/shared/": new StoreBackend({
        namespace: (rt) => ["curated-skills", rt.context.orgId],
      }),
      "/skills/personal/": new StoreBackend({
        namespace: (ctx) => [
          "user-skills",
          ctx.config?.configurable?.user_id ?? "anonymous",
        ],
      }),
    },
  }),
  skills: ["/skills/shared/", "/skills/personal/"],
  permissions: [
    {
      operations: ["write"],
      paths: ["/skills/shared/**"],
      mode: "deny",
    },
  ],
});

The agent uses write_file and edit_file to create or update SKILL.md and supporting files under the writable path. To capture general learnings outside the skills format, route a separate path such as /memories/ to another writable backend. 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 the SKILL.md file. Reference scripts in your SKILL.md so the agent knows they exist and when to run them:

skills

arxiv-search

SKILL.md

scripts

search.ts

---
name: arxiv-search
description: Search the arXiv preprint repository for research papers. Use when the user asks about academic papers, recent research, or scientific literature.
---

# arxiv-search

Search arXiv for papers matching the user's query.

## Instructions

1. Run `scripts/search.ts` with the user's query as an argument.
2. Parse the results and present them with title, authors, abstract summary, and link.
3. If the user asks for more detail on a specific paper, fetch the full abstract.

The agent can read scripts from any backend, but to execute them, the agent needs access to a shell, which only sandbox backends provide.

Sandbox backends run in isolated containers. Skill files stored outside the sandbox are not available inside it, which means the agent cannot execute skill scripts or access skill resources unless they are transferred in first. Use custom middleware to handle this transfer:

• 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.

Google

import { readFile, readdir } from "node:fs/promises";
import { join, posix, relative, resolve } from "node:path";
import { fileURLToPath } from "node:url";

import { createMiddleware } from "langchain";
import {
  CompositeBackend,
  createDeepAgent,
  type FileData,
  StoreBackend,
} from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

import { DaytonaSandbox } from "@langchain/daytona";

/** Identical skill bundles for every user: one shared store namespace. */
const SKILLS_SHARED_NAMESPACE = ["skills", "builtin"] as const;

function createFileData(content: string): FileData {
  const now = new Date().toISOString();
  return {
    content: content.split("\n"),
    created_at: now,
    modified_at: now,
  };
}

function normalizeSkillsStoreKey(key: string): string {
  const k = String(key);
  if (k.includes("..") || /[*?]/.test(k)) {
    throw new Error(`Invalid key: ${key}`);
  }
  return k.startsWith("/") ? k : `/${k}`;
}

async function walkFiles(dir: string): Promise<string[]> {
  const entries = await readdir(dir, { withFileTypes: true });
  const files: string[] = [];
  for (const entry of entries) {
    const fullPath = join(dir, entry.name);
    if (entry.isDirectory()) {
      files.push(...(await walkFiles(fullPath)));
    } else if (entry.isFile()) {
      files.push(fullPath);
    }
  }
  return files.sort((a, b) => a.localeCompare(b));
}

/** Load canonical skill files from disk into the shared store namespace (run once at deploy).
 *  You can retrieve skills from any source (local filesystem, remote URL, etc.).
 */
async function seedSkillStore(store: InMemoryStore) {
  const moduleDir = resolve(fileURLToPath(new URL(".", import.meta.url)));
  const skillsDir = resolve(moduleDir, "skills");
  const filePaths = await walkFiles(skillsDir);
  for (const filePath of filePaths) {
    const rel = relative(skillsDir, filePath);
    // StoreBackend keys are paths *relative to the routed backend root*.
    // CompositeBackend strips the route prefix (`/skills/`) before delegating,
    // so store keys should look like "/<skillname>/SKILL.md".
    const key = `/${posix.normalize(rel.split("\\").join("/"))}`;
    const content = await readFile(filePath, "utf8");
    await store.put([...SKILLS_SHARED_NAMESPACE], key, createFileData(content));
  }
}

/** Copy shared skill files from the store into the sandbox before each agent run. */
function createSkillSandboxSyncMiddleware(backend: CompositeBackend) {
  return createMiddleware({
    name: "SkillSandboxSyncMiddleware",
    beforeAgent: async (state, runtime) => {
      const store = (runtime as any).store;
      if (!store) {
        throw new Error(
          "Store is required for syncing skills into the sandbox. " +
            "Pass `store` to createDeepAgent and ensure your runtime provides it.",
        );
      }

      const encoder = new TextEncoder();
      const files: Array<[string, Uint8Array]> = [];

      for (const item of await store.search([...SKILLS_SHARED_NAMESPACE])) {
        const normalized = normalizeSkillsStoreKey(String(item.key));
        const data = item.value as FileData;
        // CompositeBackend routes paths and batches uploads to the right backend.
        files.push([
          `/skills${normalized}`,
          encoder.encode(data.content.join("\n")),
        ]);
      }

      if (files.length > 0) await backend.uploadFiles(files);

      return state;
    },
  });
}

async function main() {
  const store = new InMemoryStore();
  await seedSkillStore(store);

  const sandbox = await DaytonaSandbox.create({
    language: "python",
    timeout: 300,
  });

  const backend = new CompositeBackend(sandbox, {
    "/skills/": new StoreBackend({
      store,
      namespace: () => [...SKILLS_SHARED_NAMESPACE],
    } as any),
  });

  try {
    const agent = await createDeepAgent({
      model: "google-genai:gemini-3.5-flash",
      backend,
      skills: ["/skills/"],
      store,
      middleware: [createSkillSandboxSyncMiddleware(backend)],
    });

  } finally {
    await sandbox.close();
  }
}

main().catch((err) => {
  console.error(err);
  process.exitCode = 1;
});

For a complete example that seeds both skills and memories before execution and syncs both back afterward, see syncing skills and memories with custom middleware.

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

To make a skill importable:

1. 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.

2. Configure skills normally

   Pass the skill source path with the skills argument when creating the agent.

3. Use the same backend

   Configure the interpreter middleware with the same backend that SkillsMiddleware uses to load skill files.

4. Import from interpreter code

   The agent imports the helper module with await import("@/skills/<name>").

Minimal skill layout:

skills

order-helpers

SKILL.md

scripts

index.ts

---
name: order-helpers
description: Helper functions for normalizing and grouping order records.
metadata:
  entrypoint: scripts/index.ts
---

# order-helpers

Use this skill when order records need deterministic cleanup or aggregation.

Import these utilities into the REPL in order to interact with order data:

```typescript
const { groupByStatus } = await import("@/skills/order-helpers");
groupByStatus(...);
```

// skills/order-helpers/scripts/index.ts
interface Order {
  id: string;
  status: string;
}

export function groupByStatus(orders: Order[]) {
  return orders.reduce((acc, order) => {
    acc[order.status] = acc[order.status] ?? [];
    acc[order.status].push(order);
    return acc;
  }, {});
}

Then configure the agent:

import { createDeepAgent, StateBackend } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const backend = new StateBackend();

const agent = createDeepAgent({
  model: "openai:gpt-5.4",
  backend,
  skills: ["/skills/"],
  middleware: [createCodeInterpreterMiddleware({ skillsBackend: backend })],
});

The agent can now import the module from interpreter code:

const { groupByStatus } = await import("@/skills/order-helpers");

const grouped = groupByStatus(orders);
grouped;

Troubleshooting

Use LangSmith traces to debug skill discovery, read_file calls on SKILL.md, and supporting resource access. Follow the tracing quickstart to get set up. We recommend you also set up LangSmith Engine, which monitors your traces, detects issues, and proposes fixes.

Skill not activated

Problem: The agent handles the task without reading the skill’s SKILL.md.

Solutions:

1. Make the description more specific. The agent selects skills from the description field alone at discovery. Include what the skill does, when to use it, and keywords the agent can match:

   # Good
   description: >-
     Search the arXiv preprint repository for research papers. Use when the
     user asks about academic papers, recent research, or scientific literature.
   
   # Poor
   description: Helps with research.
   

2. Reduce overlap between skills. If multiple skills have similar descriptions, the agent may skip the right one or pick the wrong one. Differentiate descriptions or consolidate related skills.

3. Confirm the skill is in the skills array. Skills load only from paths you pass at agent creation or from subagent-specific skills parameters.

Skills missing at startup

Problem: The agent does not list a skill in its system prompt, or read_file on SKILL.md fails.

Solutions:

1. Check the skill path. Paths must use forward slashes and be relative to the backend root. With FilesystemBackend, the path is relative to root_dir. With StateBackend, pass skill files in invoke(files={...}) using create_file_data().

2. Validate SKILL.md frontmatter. The name must match the parent directory name and follow the Agent Skills specification. Use the skills-ref validation tool to check formatting.

3. Check file size. Deep Agents skips SKILL.md files over 10 MB during discovery.

4. Check layered sources. When the same skill name appears in multiple sources, the last source wins. An older or empty skill from a later path can override the one you expect.

Supporting files not found

Problem: The agent reads SKILL.md but cannot access scripts, references, or assets.

Solutions:

1. Reference files from SKILL.md. The agent does not auto-discover supporting files. State what each file contains and when to use it. Use relative paths from the skill root.

2. Keep paths within the skill directory. File paths resolve against the backend. Confirm supporting files exist at the paths your instructions reference.

3. Sync skills into sandboxes. If you use sandbox backends, skill files outside the container are not available until you copy them in. See Sandbox scripts and syncing skills and memories with custom middleware.

Scripts or imports fail

Problem: The agent reads a script but cannot run it, or import("@/skills/<name>") fails in the interpreter.

Solutions:

1. Use a sandbox for shell execution. The agent can read scripts from any backend, but running them requires a sandbox backend. See Execute code with skills.

2. Configure interpreter middleware. Interpreter skills require metadata.entrypoint in SKILL.md frontmatter and interpreter middleware with the same backend that loads skill files.

3. Match skill and interpreter backends. If SkillsMiddleware and the interpreter use different backends, import paths may not resolve to the files you expect.

Subagent cannot access a skill

Problem: A custom subagent does not see skills that the main agent uses.

Solution: Custom subagents do not inherit the main agent’s skills. Add a skills parameter to each subagent definition with that subagent’s skill source paths. The general-purpose subagent inherits skills from create_deep_agent automatically.

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

These are guidelines, not hard boundaries. In practice, skills and memory sit on a spectrum. An agent can update its own skills as it works, capturing new procedures and refining instructions over time. In this way, skills can function as a form of progressive-disclosure memory: context the agent builds up and retrieves on demand rather than loading on every prompt.

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.

---
name: langgraph-docs
description: Use this skill for requests related to LangGraph in order to fetch relevant documentation to provide accurate, up-to-date guidance.
license: MIT
compatibility: Requires internet access for fetching documentation URLs
metadata:
  author: langchain
  version: "1.0"
allowed-tools: fetch_url
---

# langgraph-docs

Instructions for the agent go here. See [Usage](#usage) for a complete example of skill instructions.

Refer to the full Agent Skills specification for detailed constraints and validation rules. In Deep Agents, SKILL.md files must be under 10 MB. Files exceeding this limit are skipped during skill loading.

For more example skills, see Deep Agents example skills.

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.