Skill Manifest (skill.toml)

The skill.toml file is a TOML manifest that describes a skill's metadata, runtime configuration, permissions, and optional input schema.

Overview

Every skill MUST have a skill.toml file in its root directory. This file:

Defines the skill's unique identifier and version
Specifies how to execute the skill (for action skills)
Declares permissions and resource requirements
Provides metadata for discovery and documentation

Required fields

name

Globally unique skill identifier using dot notation:

name = "salesforce.leads.sync"

Requirements:

Lowercase alphanumeric and dots only
Hierarchical structure: <namespace>.<domain>.<action>
Unique across all skills in the runtime

version

Semantic version (major.minor.patch):

version = "0.1.0"

description

Brief one-line description:

description = "Sync leads from a sheet blob into Salesforce."

kind

Skill type: either "action" or "instruction":

kind = "action"    # Has runtime, can be executed
# or
kind = "instruction"  # Documentation only, cannot execute

Runtime section

Required for action skills, omitted for instruction skills:

[runtime]
language   = "python"           # Only "python" in MVP
entrypoint = "code/main.py"     # Path to module relative to skill root
export     = "main"             # Function name to call

Fields

Name
language
Type
string
Required
required
Description
Programming language. MVP: "python" only. Runtimes may support additional languages in future versions.
Name
entrypoint
Type
string
Required
required
Description
Path to the executable module relative to skill root (e.g., "code/main.py"). The file MUST define a function named by the export field.
Name
export
Type
string
Required
required
Description
Name of the function to call. Must exist in the entrypoint module and accept args parameter.

Example

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

The code/main.py must define:

def main(args):
    # args is a dict passed from execute_skill or run_code
    return {"status": "completed", ...}

Optional fields

namespace

Grouping for related skills (for filtering with list_skills):

namespace = "salesforce"

Permissions

Declare what the skill needs to run:

[permissions]
network = ["https://*.salesforce.com", "https://api.salesforce.com"]
secrets = ["SALESFORCE_API_KEY", "SALESFORCE_ORG_ID"]

Fields

Name
network
Type
array
Description
List of allowed outbound network URLs (wildcard patterns allowed). If omitted, no network access.
Name
secrets
Type
array
Description
List of environment variable names the skill requires. Runtime injects these from secure storage.

Input schema

Informal input documentation (for LLM and humans):

[inputs]
sheet_blob = { type = "blob", description = "Blob id of the source sheet" }
env = { type = "string", description = "Which Salesforce env (dev, staging, prod)" }
row_limit = { type = "integer", description = "Maximum rows to sync (optional)" }

Input schema is informal. Runtimes MAY validate against it but are not required to in MVP.

Examples

Minimal action skill

name = "hello.world"
version = "0.1.0"
description = "A simple hello world skill."
kind = "action"

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

Complete action skill

name = "salesforce.leads.sync"
version = "0.1.0"
description = "Sync leads from a sheet blob into Salesforce."
kind = "action"
namespace = "salesforce"
tags = ["crm", "leads", "sync"]

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

[inputs]
sheet_blob = { type = "blob", description = "Blob id of the CSV sheet" }
env = { type = "string", enum = ["dev", "staging", "prod"], description = "Target environment" }
batch_size = { type = "integer", default = 100, description = "Records per batch" }

[permissions]
network = ["https://*.salesforce.com"]
secrets = ["SALESFORCE_API_KEY", "SALESFORCE_ORG_ID"]

Instruction skill

name = "best-practices.salesforce"
version = "1.0.0"
description = "Best practices for Salesforce integrations."
kind = "instruction"
namespace = "best-practices"
tags = ["guide", "salesforce"]

Versioned skill

name = "stripe.payments.process"
version = "2.3.1"
description = "Process payments via Stripe."
kind = "action"

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

[inputs]
amount_cents = { type = "integer", description = "Amount in cents" }
currency = { type = "string", default = "USD", description = "Currency code" }
customer_id = { type = "string", description = "Stripe customer ID" }

[permissions]
network = ["https://api.stripe.com"]
secrets = ["STRIPE_API_KEY"]

Next Steps

Skill Documentation (SKILL.md)Skill Structure