skills-handler

A framework-agnostic handler for serving Agent Skills via well-known URIs. Implements the Agent Skills Discovery specification.

Repository: github.com/vercel-labs/skills-handler

Installation

npm install skills-handler

For file-based skill loading:

npm install skills-handler gray-matter

Quick Start (Next.js)

Create a catch-all route at app/.well-known/skills/[[...path]]/route.ts:

import { createSkillsHandler, createStaticProvider } from "skills-handler";

const handler = createSkillsHandler(
  createStaticProvider([
    {
      name: "git-workflow",
      description: "Follow team Git conventions for branching and commits.",
      body: `# Git Workflow

Create feature branches from \`main\`:

\`\`\`bash
git checkout -b feature/my-feature main
\`\`\``,
      files: ["SKILL.md"],
    },
  ])
);

export { handler as GET, handler as OPTIONS };

Your skills are now available at:

• GET /.well-known/skills/index.json - Discovery index
• GET /.well-known/skills/git-workflow/SKILL.md - Skill instructions

File-Based Skills

Load skills from the filesystem instead of defining them in code:

// app/.well-known/skills/[[...path]]/route.ts
import { createSkillsHandler, createFileProvider } from "skills-handler";
import path from "path";

const provider = await createFileProvider(path.join(process.cwd(), "skills"));
const handler = createSkillsHandler(provider);

export { handler as GET, handler as OPTIONS };

Directory structure:

project/
├── app/.well-known/skills/[[...path]]/route.ts
└── skills/
    ├── git-workflow/
    │   └── SKILL.md
    └── pdf-processing/
        ├── SKILL.md
        ├── scripts/
        │   └── extract.py
        └── references/
            └── TABLES.md

Each SKILL.md file requires YAML frontmatter:

---
name: git-workflow
description: Follow team Git conventions for branching and commits.
---

# Git Workflow

Your skill instructions here...

API Reference

createSkillsHandler(provider, config?)

Creates the request handler.

const handler = createSkillsHandler(provider, {
  basePath: "/.well-known/skills", // URL base path (default)
  verboseLogs: false,              // Enable debug logging
  cacheControl: "public, max-age=3600", // Cache header
  cors: "*",                       // CORS origin (* | string[] | false)
  onEvent: (event) => {},          // Analytics callback
});

createStaticProvider(skills, additionalFiles?)

Creates a provider from skills defined in code.

const provider = createStaticProvider([
  {
    name: "my-skill",
    description: "What the skill does and when to use it.",
    body: "# Skill Instructions\n\nMarkdown content...",
    files: ["SKILL.md"],
  },
]);