Skill Structure

Skills are organized in a standardized directory structure. This format works for both disk-based skills and registry storage.

Directory layout

Each skill has a root directory containing:

<skill_root>/
  skill.toml          # Machine-readable manifest (required)
  SKILL.md            # LLM-readable instructions (required)
  code/               # Optional executable implementation
  resources/          # Optional supporting files

File purposes

Name
skill.toml
Required
required
Description
Machine-readable manifest with metadata, runtime configuration, permissions, and optional input schema.
Name
SKILL.md
Required
required
Description
Markdown file with YAML frontmatter. Instructions and examples for the LLM.
Name
code/
Description
Optional directory containing executable code. For action skills, includes the entrypoint file.
Name
resources/
Description
Optional directory for supporting files: schemas, examples, documentation, etc.

Required files

skill.toml

Every skill MUST have a skill.toml manifest. See Skill Manifest for the complete schema.

Minimal example:

name        = "salesforce.leads.sync"
version     = "0.1.0"
description = "Sync leads from a sheet blob into Salesforce."
kind        = "action"

SKILL.md

Every skill MUST have a SKILL.md file. It combines YAML frontmatter with markdown content:

---
name: Salesforce Lead Sync
short_description: Sync leads from a sheet blob into Salesforce.
tags: [crm, leads, sync]
---

# Salesforce Lead Sync

This skill syncs lead data from a CSV blob into Salesforce...

See Skill Documentation for details on the SKILL.md format.

Optional directories

code/ directory

Contains executable implementation. Required for action skills:

code/
  main.py              # Entrypoint file (as specified in skill.toml)
  utils.py             # Helper modules
  requirements.txt     # Dependencies (Python MVP)

For Python skills, the entrypoint file must define an export function:

def main(args):
    """
    args: dict passed from execute_skill or run_code
    returns: JSON-serializable result
    """
    return {"status": "completed"}

resources/ directory

Optional supporting files:

resources/
  examples.md          # Usage examples
  schema.json          # Input/output schema
  api-reference.md     # Detailed API docs
  sample-data.csv      # Example data

Action vs Instruction skills

Action Skills

Have runtime configuration and executable code. Can be executed via execute_skill:

name        = "salesforce.leads.sync"
kind        = "action"

[runtime]
language   = "python"
entrypoint = "code/main.py"
export     = "main"

Directory structure:

salesforce.leads.sync/
  skill.toml
  SKILL.md
  code/
    main.py          # Must define main(args) function

Instruction Skills

No runtime. Only provide documentation and context to the LLM. Cannot be executed:

name        = "best-practices.salesforce"
kind        = "instruction"
# No [runtime] section needed

Directory structure:

best-practices.salesforce/
  skill.toml         # kind = "instruction"
  SKILL.md           # Educational content for the LLM
  resources/
    guide.md
    examples.md

Example structure

Complete action skill

salesforce.leads.sync/
  skill.toml
  SKILL.md
  code/
    main.py
    utils.py
    requirements.txt
  resources/
    examples.md
    schema.json
    sample-leads.csv

Minimal action skill

gdrive.sheets.read/
  skill.toml
  SKILL.md
  code/
    main.py

Instruction skill

skills.protocol.guide/
  skill.toml
  SKILL.md
  resources/
    workflow.md
    best-practices.md

Naming conventions

Skill names

Use dot notation for namespacing:

Good: salesforce.leads.sync, gdrive.sheets.read, slack.messages.send
Bad: SalesforceLeadsSync, gdrive_sheets_read

Directory names

Use lowercase with dots:

salesforce.leads.sync/     ✓ Correct
salesforce-leads-sync/     ✗ Avoid dashes
SalesforceLeadsSync/       ✗ Avoid camelCase

Version format

Follow semantic versioning:

version = "0.1.0"    # major.minor.patch
version = "1.2.3"

Best practices

Clear naming — Use descriptive, hierarchical names (e.g., salesforce.accounts.export)
Comprehensive docs — SKILL.md should explain what the skill does, required inputs, and example usage
Optional schemas — Include JSON schemas in resources/ for complex inputs/outputs
Example data — Provide sample files in resources/ for reference
Clean code — Well-structured, documented implementation in code/
Dependency management — Include requirements.txt for Python skills

Next Steps

Skill Manifest (skill.toml)Skill Documentation (SKILL.md)