Custom Skills

Build your own legal AI skills and make them available to your organization’s agents. Custom skills are stored with vector embeddings and automatically appear in unified search alongside the 870+ curated skills.

Requires authentication. All custom skills endpoints require a Case.dev API key with skills permission scope.

How It Works

Custom skills live in your organization and are the canonical way to manage private skills. When your agents search for skills via /skills/resolve, results from your custom skills are merged with curated skills in a single ranked list. If a custom skill has the same slug as a curated skill, the custom skill takes priority for your organization. Use the /skills API for the full lifecycle:

Endpoint	Purpose
`POST /skills`	Create a custom skill, optionally with bundled files
`GET /skills/custom`	List your organization’s custom skills
`GET /skills/:slug`	Read a custom or curated skill by slug
`PUT /skills/:slug`	Update a custom skill and optionally replace bundled files
`DELETE /skills/:slug`	Delete a custom skill
`GET /skills/:slug/export`	Inspect the installable file tree for an agent runtime
`GET /skills/resolve`	Search custom and curated skills together

Each custom skill includes:

Content in markdown, up to 64KB
Vector embedding (generated automatically) for semantic search
Tags for categorization and search boosting
Metadata for arbitrary key-value data
Optional companion files for Skills.sh-style SKILL.md bundles, scripts, templates, and references
Version tracking with automatic increment on updates
Soft-delete so deleted skills can be recreated

Create a Skill

curl -X POST https://api.case.dev/skills \
  -H "Authorization: Bearer $CASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deposition Prep Checklist",
    "summary": "Comprehensive checklist for deposition preparation.",
    "content": "# Deposition Prep Checklist\n\n## Pre-Deposition\n...",
    "tags": ["litigation", "deposition", "checklist"],
    "metadata": { "author": "Jane Smith", "practice_area": "litigation" }
  }'

import Casedev from 'casedev'

const client = new Casedev({ apiKey: process.env.CASEDEV_API_KEY })

const skill = await client.skills.create({
  name: 'Deposition Prep Checklist',
  summary: 'Comprehensive checklist for deposition preparation in federal litigation.',
  content:
    '# Deposition Prep Checklist\n\n## Pre-Deposition\n- Review all relevant documents\n- Prepare witness outline',
  tags: ['litigation', 'deposition', 'checklist'],
  metadata: { author: 'Jane Smith', practice_area: 'litigation' },
})

console.log(skill.slug) // "deposition-prep-checklist"

import os
import casedev

client = casedev.Casedev(api_key=os.environ['CASEDEV_API_KEY'])

skill = client.skills.create(
    name='Deposition Prep Checklist',
    summary='Comprehensive checklist for deposition preparation in federal litigation.',
    content='# Deposition Prep Checklist\n\n## Pre-Deposition\n- Review all relevant documents',
    tags=['litigation', 'deposition', 'checklist'],
    metadata={'author': 'Jane Smith', 'practice_area': 'litigation'},
)

print(skill.slug)  # "deposition-prep-checklist"

package main

import (
    "context"
    "fmt"

    "github.com/CaseMark/casedev-go"
)

func main() {
    client := casedev.NewClient()

    skill, _ := client.Skills.New(context.TODO(), casedev.SkillNewParams{
        Name:    casedev.F("Deposition Prep Checklist"),
        Summary: casedev.F("Comprehensive checklist for deposition preparation."),
        Content: casedev.F("# Deposition Prep Checklist\n\n## Pre-Deposition\n..."),
        Tags:    casedev.F([]string{"litigation", "deposition", "checklist"}),
    })

    fmt.Println(skill.Slug)
}

Request body:

Field	Type	Required	Description
`name`	string	Yes	Skill name (max 256 chars)
`content`	string	Yes	Full skill content in markdown (max 64KB)
`slug`	string	No	URL-safe identifier. Auto-generated from name if omitted
`summary`	string	No	Brief description (max 1000 chars)
`tags`	string[]	No	Tags for categorization and search boosting
`metadata`	object	No	Arbitrary key-value metadata
`files`	object[]	No	Companion files installed under the skill directory in agent sandboxes

Bundled Skill Files

Use files[] when a skill needs scripts, references, examples, or templates in addition to its root SKILL.md instructions. The root content becomes <slug>/SKILL.md; each companion file is installed at <slug>/<path>.

cURL

curl -X POST https://api.case.dev/skills \
  -H "Authorization: Bearer $CASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract Redline Review",
    "slug": "contract-redline-review",
    "summary": "Review contract redlines with a firm-specific checklist.",
    "content": "# Contract Redline Review\n\nUse the checklist and script before drafting comments.",
    "tags": ["transactional", "contracts"],
    "files": [
      {
        "path": "references/checklist.md",
        "content": "# Checklist\n\n- Confirm governing law\n- Flag assignment restrictions"
      },
      {
        "path": "scripts/clauses.ts",
        "content": "export const riskyClauses = [\"assignment\", \"indemnity\"];",
        "contentType": "text/typescript"
      }
    ]
  }'

Bundled paths must be relative, cannot contain . or .. segments, and cannot be SKILL.md. Send files[] again on PUT /skills/:slug to replace the companion tree; omit files to leave companion files unchanged. Response (201):

{
  "slug": "deposition-prep-checklist",
  "name": "Deposition Prep Checklist",
  "summary": "Comprehensive checklist for deposition preparation.",
  "content": "# Deposition Prep Checklist\n\n...",
  "tags": ["litigation", "deposition", "checklist"],
  "metadata": { "author": "Jane Smith", "practice_area": "litigation" },
  "bundle": null,
  "version": 1,
  "created_at": "2026-03-16T20:09:59.333Z"
}

Slugs are unique per organization. Reserved slugs (resolve, custom) cannot be used. If you omit slug, one is auto-generated from the skill name.

Read a Skill

Retrieve a skill by slug. For authenticated users, custom skills are checked first, then curated skills.

curl https://api.case.dev/skills/deposition-prep-checklist \
  -H "Authorization: Bearer $CASE_API_KEY"

const skill = await client.skills.read('deposition-prep-checklist')
console.log(skill.source) // "custom" or "curated"

skill = client.skills.read('deposition-prep-checklist')
print(skill.source)  # "custom" or "curated"

skill, _ := client.Skills.Read(context.TODO(), "deposition-prep-checklist")
fmt.Println(skill.Source)

The response includes a source field indicating whether the skill is "custom" (your organization’s) or "curated" (from the open-source library). For bundled root skills, GET /skills/:slug also includes a bundle object:

{
  "bundle": {
    "role": "root",
    "files": [
      {
        "slug": "contract-redline-review--file--references-checklist-md-a1b2c3d4e5f6",
        "path": "references/checklist.md",
        "content_type": "text/plain; charset=utf-8"
      }
    ]
  }
}

Export a Skill Tree

Use GET /skills/:slug/export to inspect the exact files that will be installed into an agent runtime sandbox. Custom skills in your organization are resolved first; curated skills are used as a fallback.

cURL

curl "https://api.case.dev/skills/contract-redline-review/export?target=agents" \
  -H "Authorization: Bearer $CASE_API_KEY"

Response:

{
  "slug": "contract-redline-review",
  "target": "agents",
  "root": "<runtime-skill-directory>/contract-redline-review",
  "source": "custom",
  "files": [
    {
      "path": "contract-redline-review/SKILL.md",
      "content": "# Contract Redline Review\n\n...",
      "content_type": "text/markdown; charset=utf-8",
      "sha256": "d3b07384d113edec49eaa6238ad5ff00",
      "size_bytes": 128
    },
    {
      "path": "contract-redline-review/references/checklist.md",
      "content": "# Checklist\n\n...",
      "content_type": "text/plain; charset=utf-8",
      "sha256": "98f13708210194c475687be6106a3b84",
      "size_bytes": 64
    }
  ]
}

Most applications do not need to call export directly. Pass skillSlugs when creating an agent runtime and Case.dev installs the right tree for that sandbox.

Install Skills in Agent Runtimes

When creating an agent runtime through a Case.dev integration that supports skills, pass skillSlugs to install custom or curated skills into the sandbox before the runtime starts. Case.dev installs the root SKILL.md and any companion files into the sandbox’s skill directory before the runtime process starts. Use the same skillSlugs field for any Case.dev runtime that supports skill installation. Case.dev selects the correct sandbox paths for that runtime.

Search Skills

Use /skills/resolve to search across both curated and custom skills. Results are ranked by relevance using semantic search, BM25 text matching, and tag boosting.

curl "https://api.case.dev/skills/resolve?q=deposition+preparation&limit=5" \
  -H "Authorization: Bearer $CASE_API_KEY"

const results = await client.skills.resolve({
  q: 'deposition preparation',
  limit: 5,
})

for (const skill of results.results) {
  console.log(skill.source + ': ' + skill.name + ' (' + skill.score + ')')
}

results = client.skills.resolve(q='deposition preparation', limit=5)

for skill in results.results:
    print(f"{skill.source}: {skill.name} ({skill.score})")

results, _ := client.Skills.Resolve(context.TODO(), casedev.SkillResolveParams{
    Q:     casedev.F("deposition preparation"),
    Limit: casedev.Int(5),
})

for _, skill := range results.Results {
    fmt.Printf("%s: %s (%f)\n", skill.Source, skill.Name, skill.Score)
}

Each result includes:

Field	Description
`slug`	Skill identifier
`name`	Skill name
`summary`	Brief description
`tags`	Practice area tags
`score`	Relevance score (0-1)
`source`	`"curated"` or `"custom"`

Custom skills with the same slug as a curated skill take priority in your organization’s results. This lets you override curated skills with org-specific versions.

List Custom Skills

List all custom skills in your organization, with optional filtering.

# List all
curl "https://api.case.dev/skills/custom" \
  -H "Authorization: Bearer $CASE_API_KEY"

# Filter by tag
curl "https://api.case.dev/skills/custom?tag=litigation" \
  -H "Authorization: Bearer $CASE_API_KEY"

# Paginate
curl "https://api.case.dev/skills/custom?limit=10&cursor=csk_abc123" \
  -H "Authorization: Bearer $CASE_API_KEY"

// List all
const list = await client.skills.custom.list()

// Filter by tag
const filtered = await client.skills.custom.list({ tag: 'litigation' })

// Paginate
const page2 = await client.skills.custom.list({
  limit: 10,
  cursor: list.next_cursor,
})

# List all
skills_list = client.skills.custom.list()

# Filter by tag
filtered = client.skills.custom.list(tag='litigation')

# Paginate
page2 = client.skills.custom.list(limit=10, cursor=skills_list.next_cursor)

// List all
list, _ := client.Skills.Custom.List(context.TODO(), casedev.SkillCustomListParams{})

// Filter by tag
filtered, _ := client.Skills.Custom.List(context.TODO(), casedev.SkillCustomListParams{
    Tag: casedev.String("litigation"),
})

// Paginate
page2, _ := client.Skills.Custom.List(context.TODO(), casedev.SkillCustomListParams{
    Limit:  casedev.Int(10),
    Cursor: list.NextCursor,
})

Query parameters:

Parameter	Type	Description
`limit`	integer	Results per page (1-100, default 50)
`cursor`	string	Cursor from previous response for pagination
`tag`	string	Filter by tag

Response:

{
  "skills": [
    {
      "slug": "deposition-prep-checklist",
      "name": "Deposition Prep Checklist",
      "summary": "...",
      "tags": ["litigation", "deposition"],
      "metadata": {},
      "version": 1,
      "created_at": "2026-03-16T20:09:59.333Z",
      "updated_at": "2026-03-16T20:09:59.333Z"
    }
  ],
  "next_cursor": "csk_abc123",
  "has_more": true
}

Update a Skill

Update one or more fields. The version is automatically incremented. If you change content-related fields (name, summary, or content), the embedding is regenerated.

curl -X PUT https://api.case.dev/skills/deposition-prep-checklist \
  -H "Authorization: Bearer $CASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Deposition Prep Checklist",
    "tags": ["litigation", "deposition", "checklist", "federal"],
    "content": "# Updated content..."
  }'

const updated = await client.skills.update('deposition-prep-checklist', {
  name: 'Updated Deposition Prep Checklist',
  tags: ['litigation', 'deposition', 'checklist', 'federal'],
  content: '# Updated content...',
})

console.log(updated.version) // 2

updated = client.skills.update(
    'deposition-prep-checklist',
    name='Updated Deposition Prep Checklist',
    tags=['litigation', 'deposition', 'checklist', 'federal'],
    content='# Updated content...',
)

print(updated.version)  # 2

updated, _ := client.Skills.Update(context.TODO(), "deposition-prep-checklist", casedev.SkillUpdateParams{
    Name:    casedev.String("Updated Deposition Prep Checklist"),
    Tags:    casedev.F([]string{"litigation", "deposition", "checklist", "federal"}),
    Content: casedev.String("# Updated content..."),
})

fmt.Println(updated.Version)

You can also rename a skill’s slug:

cURL

curl -X PUT https://api.case.dev/skills/deposition-prep-checklist \
  -H "Authorization: Bearer $CASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "depo-prep-v2" }'

After renaming, the old slug returns 404 and the new slug is active.

Delete a Skill

Soft-deletes a skill. It will no longer appear in search results or be accessible by slug.

curl -X DELETE https://api.case.dev/skills/deposition-prep-checklist \
  -H "Authorization: Bearer $CASE_API_KEY"

await client.skills.delete('deposition-prep-checklist')

client.skills.delete('deposition-prep-checklist')

client.Skills.Delete(context.TODO(), "deposition-prep-checklist")

Response (200):

{
  "slug": "deposition-prep-checklist",
  "deleted": true
}

Deletion frees the slug. You can create a new skill with the same slug after deleting.

Permissions

Custom skills require the skills permission scope on your API key.

Endpoint	Permission
`GET /skills/resolve`	`skills` (read)
`GET /skills/:slug`	`skills` (read)
`GET /skills/custom`	`skills` (read)
`POST /skills`	`skills` (write)
`PUT /skills/:slug`	`skills` (write)
`DELETE /skills/:slug`	`skills` (write)
`GET /skills/:slug/export`	`skills` (read)

Configure permissions when creating API keys in the Console.

Limits

Limit	Value
Content size	64KB per skill
Companion files	100 per skill
Companion file size	64KB per file
Name length	256 characters
Summary length	1,000 characters
Tag length	100 characters per tag
Slug length	128 characters
Slugs per org	Unlimited

What’s Next?

Browse Curated Skills

Explore 870+ open-source legal skills

API Reference

Full endpoint documentation

Skills Overview

Learn about the curated skills library and MCP setup

Rate Limits

Understand request limits and pricing

Get Started

Platform

Resources

How It Works

Create a Skill

Bundled Skill Files

Read a Skill

Export a Skill Tree

Install Skills in Agent Runtimes

Search Skills

List Custom Skills

Update a Skill

Delete a Skill

Permissions

Limits

What’s Next?

Browse Curated Skills

API Reference

Skills Overview

Rate Limits

​How It Works

​Create a Skill

​Bundled Skill Files

​Read a Skill

​Export a Skill Tree

​Install Skills in Agent Runtimes

​Search Skills

​List Custom Skills

​Update a Skill

​Delete a Skill

​Permissions

​Limits

​What’s Next?

Browse Curated Skills

API Reference

Skills Overview

Rate Limits

How It Works

Create a Skill

Bundled Skill Files

Read a Skill

Export a Skill Tree

Install Skills in Agent Runtimes

Search Skills

List Custom Skills

Update a Skill

Delete a Skill

Permissions

Limits

What’s Next?