deepagents-skills

name	deepagents-skills
description	Creating and using custom skills with progressive disclosure, SKILL.md format, and the Agent Skills protocol in Deep Agents.
language	js

deepagents-skills (JavaScript/TypeScript)

Overview

Skills provide specialized capabilities through progressive disclosure: agents load content only when relevant.

Process: Match (see descriptions) → Read (load SKILL.md) → Execute (follow instructions)

Skills vs Memory

Skills	Memory (AGENTS.md)
On-demand loading	Always loaded
Task-specific	General preferences
Large docs	Compact context

Code Examples

With FilesystemBackend

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

const agent = await createDeepAgent({
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
  skills: ["./skills/"],
  checkpointer: new MemorySaver()
});

const result = await agent.invoke({
  messages: [{
    role: "user",
    content: "What is LangGraph? Use langgraph-docs skill if available."
  }]
});

With StoreBackend

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

const store = new InMemoryStore();

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/.../SKILL.md";
const response = await fetch(skillUrl);
const skillContent = await response.text();

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

const agent = await createDeepAgent({
  backend: (config) => new StoreBackend(config),
  store,
  skills: ["/skills/"]
});

With StateBackend

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

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

const skillContent = `---
name: python-testing
description: Pytest best practices
---
# Python Testing Skill
...`;

const skillsFiles: Record<string, FileData> = {
  "/skills/python-testing/SKILL.md": createFileData(skillContent)
};

const agent = await createDeepAgent({
  skills: ["/skills/"],
  checkpointer: new MemorySaver()
});

await agent.invoke({
  messages: [{ role: "user", content: "How should I write tests?" }],
  files: skillsFiles
});

SKILL.md Format

---
name: fastapi-docs
description: FastAPI best practices and patterns
---

# FastAPI Documentation Skill

## When to Use
When working with FastAPI endpoints.

## Instructions
Always use async handlers:
\`\`\`typescript
app.get("/users/:id", async (req, res) => {
  const user = await db.users.findById(req.params.id);
  res.json(user);
});
\`\`\`

Boundaries

What CAN Configure

✅ Skill directories (global and project-scoped) ✅ Skill content and structure within SKILL.md format ✅ Backend type for skill storage (Filesystem, Store, State) ✅ Skill descriptions for matching ✅ Multiple skill directories per agent

What CANNOT Configure

❌ SKILL.md file format (must follow Agent Skills protocol) ❌ Frontmatter fields (name and description are required) ❌ Progressive disclosure behavior (always on-demand) ❌ Skill file name (must be SKILL.md) ❌ Skill matching algorithm (handled by the framework)

Gotchas

1. Skills Need Backend

// ❌ No backend
await createDeepAgent({ skills: ["./skills/"] });

// ✅ Provide backend
await createDeepAgent({
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
  skills: ["./skills/"]
});

2. Frontmatter Required

# ❌ Missing
# My Skill

# ✅ Include
---
name: my-skill
description: What this does
---
# My Skill

3. Specific Descriptions

# ❌ Vague
description: Helpful skill

# ✅ Specific
description: TypeScript testing with Jest and mocking patterns

Full Documentation

• Skills Guide
• Agent Skills Protocol