Reference

Capability File Format

Capability files define a reusable skill that agents can use during task execution. The on-disk filename is SKILL.md (kept for runtime compatibility); in Exponential they're surfaced as capabilities.

File structure

---
# YAML Frontmatter
name: Capability Name
description: One-sentence purpose
tools: [bash, read, write]
tags: [tag1, tag2]
category: certified
author: author-name
source: org/repo-name
---

## Overview
What this capability does and when to use it.

## Steps
Detailed procedure the agent should follow.

## Rules
Constraints and non-negotiables.

## Examples
Concrete scenarios with expected inputs and outputs.

Frontmatter fields

All frontmatter fields are optional.

FieldTypeDescription
idstringKebab-case identifier (e.g., database-migration). Auto-derived from directory name if omitted.
namestringHuman-readable display name.
descriptionstringOne-sentence summary of what the capability does.
toolsstring[]Tools the capability requires (see below).
tagsstring[]Lowercase kebab-case tags for categorization.
categorystringTrust tier: certified, community, or omit for local.
authorstringCreator name or handle.
sourcestringOrigin repository (e.g., exponential-work/skills).

Supported tools

ToolDescription
bashExecute shell commands
readRead file contents
writeCreate or overwrite files
editModify existing files
globFind files by pattern
grepSearch file contents

Body sections

The markdown body contains the capability's instructions. While the section names are flexible, these are the recommended sections:

Overview

A brief explanation of what the capability does, when it's useful, and any prerequisites.

## Overview
This capability creates PDF documents from HTML content using Puppeteer.
Use it when a task requires generating downloadable PDF output.
Requires Node.js 18+ installed on the machine.

Steps

A numbered, procedural guide that the agent follows. Be specific and actionable.

## Steps
1. Read the source content (HTML, Markdown, or structured data)
2. Set up the HTML template with proper styling
3. Launch a headless browser using Puppeteer
4. Render the HTML and generate the PDF
5. Save the PDF to the specified output path
6. Verify the PDF opens correctly

Rules

Constraints the agent must follow when using this capability.

## Rules
- Always use A4 page size unless the task specifies otherwise
- Include page numbers in the footer
- Never embed external fonts — use system fonts only
- Maximum file size: 10MB
- Always set `printBackground: true` for styled documents

Examples

Concrete scenarios showing expected behavior.

## Examples

### Invoice generation
Input: JSON invoice data with line items
Output: Formatted PDF invoice with company header, line items table, and total

### Report export
Input: Markdown report with charts (as images)
Output: Multi-page PDF with proper page breaks between sections

File locations

Capabilities live in a directory named after the capability, containing a SKILL.md file:

~/.claude/skills/
└── my-capability/
    └── SKILL.md
PathScope
~/.claude/skills/{capability-name}/SKILL.mdGlobal — available in all spaces
<project>/.claude/skills/{capability-name}/SKILL.mdProject — available in that project's space only

Certified capabilities location

Certified capabilities are stored in the Exponential registry:

~/.exponential/registry/skills/{capability-id}/SKILL.md

These are managed by Exponential and should not be manually edited.

Quality requirements

  • Minimum length: 100 words in the body content. Capabilities shorter than this are typically too vague to be useful.
  • Actionable content: Capabilities should contain procedures, not descriptions. "Here's how to do X" not "X is a thing that exists."
  • Specific examples: Include at least one concrete example with expected inputs and outputs.

Complete example

---
name: Code Documentation
description: Generates comprehensive code documentation from source files
tools: [read, write, glob, grep]
tags: [documentation, code, jsdoc]
author: marc
---

## Overview

This capability generates documentation for codebases. It reads source files,
extracts function signatures, types, and comments, then produces structured
markdown documentation.

Best used for: API documentation, library reference docs, internal code guides.

## Steps

1. Use `glob` to find all source files matching the target patterns
   (e.g., `src/**/*.ts`, `lib/**/*.py`)
2. Read each file and extract:
   - Exported functions and their signatures
   - Type definitions and interfaces
   - JSDoc/docstring comments
   - Module-level documentation
3. Organize by module/directory structure
4. Generate markdown documentation with:
   - Table of contents
   - Module overview sections
   - Function reference tables (name, params, return type, description)
   - Type definitions
   - Usage examples from existing comments
5. Write the documentation to the specified output file

## Rules

- Only document exported/public APIs — skip internal/private functions
- Preserve the original directory structure in the documentation hierarchy
- If a function has no documentation, note it as "Undocumented" — don't invent docs
- Use fenced code blocks for all code examples
- Link between related types and functions using markdown anchors
- Generate a table of contents for documents with more than 5 sections

## Examples

### TypeScript library

Input: `src/` directory with TypeScript modules
Output: `docs/API.md` with:
- Module listing
- Function signatures with parameter types
- Interface definitions
- Usage examples from JSDoc @example tags

### Python package

Input: `mypackage/` directory with Python modules
Output: `docs/reference.md` with:
- Module listing
- Function signatures with type hints
- Class definitions with method tables
- Docstring content preserved as descriptions

Conventions

  • Directory naming: Use lowercase kebab-case for capability directories (e.g., code-documentation/).
  • One capability per directory: Each SKILL.md defines exactly one capability.
  • Keep it focused: A capability should do one thing well. "Generate PDFs" is a capability. "Generate PDFs, send emails, and update databases" is three.

On this page