Skills Format

Skills use a directory-based format inspired by the convention of self-contained skill definitions. Each skill is a self-contained directory with a SKILL.md file and optional supporting resources. Skills are more portable and shareable than procedures -- they can be copied between agents or even between projects.

Directory Structure

Each skill lives in its own directory under skills/:

skills/
  lead-qualification/
    SKILL.md
    icp-template.md
    scoring-rubric.json
  email-triage/
    SKILL.md
    priority-rules.md
  code-review/
    SKILL.md
    review-checklist.md
    style-guide.md

The directory name is the skill identifier. All files in the directory are available to the agent when the skill is invoked.

SKILL.md Structure

The SKILL.md file is the entry point. It uses YAML frontmatter for metadata and Markdown for the skill definition.

---
name: Lead Qualification
description: Evaluate inbound leads against ICP criteria and assign scores
version: 1.0
---

# Lead Qualification

## When to use
Use this skill when you receive a new inbound lead that needs to be
evaluated against the Ideal Customer Profile (ICP).

## Steps
1. Research the prospect's company using web search.
2. Check company size, industry, and funding against ICP criteria.
3. Look for budget signals (job postings, tech stack, recent funding).
4. Assign a score from 0-100 using the scoring rubric.
5. If score > 60, create a follow-up task.

## Resources
- [ICP Template](icp-template.md)
- [Scoring Rubric](scoring-rubric.json)

Frontmatter Fields

Field	Type	Required	Description
name	string	Yes	Human-readable skill name
description	string	Yes	One-line summary of what the skill does
version	string	No	Version identifier (e.g., 1.0, 2.1). Versioning is informational only -- the platform does not enforce semantic versioning or use the version field for resolution. It exists for human reference and change tracking.

Markdown Sections

The body of SKILL.md is free-form Markdown, but the following sections are conventional:

Section	Purpose
## When to use	Tells the agent when this skill applies
## Steps	Step-by-step instructions
## Resources	Links to supporting files in the skill directory
## Examples	Example inputs and expected outputs
## Notes	Additional context, edge cases, or caveats

info

The agent reads the full SKILL.md content when the skill is invoked. Keep it focused and actionable -- the agent's context window is finite.

Supporting Files

Any file in the skill directory can be referenced from SKILL.md using relative links. Common patterns:

File Type	Example	Purpose
Templates	icp-template.md	Fill-in-the-blank templates for the agent to use
Rubrics	scoring-rubric.json	Structured criteria for evaluation
Checklists	review-checklist.md	Step-by-step verification lists
Examples	examples/good-review.md	Sample outputs for the agent to learn from

How Skills Are Invoked

Agents call skills via the invoke_skill tool:

invoke_skill(name="lead-qualification")

The agent receives the full content of SKILL.md and uses it as guidance for the current task.

Skills vs Procedures

Aspect	Skills	Procedures
Format	Markdown (SKILL.md)	YAML (.proc)
Structure	Free-form with conventions	Strict schema
Supporting files	Yes (any file in directory)	No
Portability	High (self-contained directory)	Medium (single file)
Best for	Knowledge-heavy guidance	Structured, repeatable workflows

Managing Skills

You can manage skills in two ways:

1. UI: Navigate to Agent Profile > Skills tab to create, edit, or delete skills.
2. GraphQL API: Use the skills mutations for programmatic management.

tip

Use skills for knowledge-rich guidance (like "how to evaluate a lead") and procedures for structured workflows (like "qualify-lead: step 1, step 2, step 3"). Many agents use both together.