Skills & Tools

A Skill is a composable bundle of tools that provides capabilities to Nodes. Skills group related tools with shared configuration requirements.

Skill Object

Field	Type	Required	Description
id	string	REQUIRED	Unique identifier. Referenced by node skills arrays. MUST be non-empty.
name	string	REQUIRED	Human-readable name.
description	string	REQUIRED	What this skill provides.
category	SkillCategory	REQUIRED	Functional category.
config	Record<string, ConfigField>	REQUIRED	Configuration fields required by this skill.
tools	Tool[]	REQUIRED	Tools this skill provides to nodes.

Skill Categories

The category field classifies a skill’s function. Valid values:

Category	Description
git	Source control operations (commits, PRs, code search).
observability	Error tracking, logs, metrics, incident management.
tasks	Issue tracking and project management.
notification	Messaging and alerting.
general	Catch-all for skills that don’t fit other categories.

Config Field Object

Each entry in a skill’s config map declares a configuration value the skill needs.

Field	Type	Required	Default	Description
description	string	REQUIRED	—	Human-readable description of this config field.
required	boolean	OPTIONAL	false	Whether this field must be provided for the skill to function.
env	string	OPTIONAL	—	Default environment variable name to read this value from.

Config Resolution

A conforming executor MUST resolve config values using the following precedence:

1. Explicit overrides — values passed directly to the executor at invocation.
2. Environment variables — if an env field is set, read from process.env[env].

If a required config field cannot be resolved from either source, the skill MUST be treated as unavailable. The executor SHOULD NOT fail the workflow — the skill is silently excluded, and any node that listed it will execute without that skill’s tools.

Tool Object

Field	Type	Required	Description
name	string	REQUIRED	Tool name. MUST be unique within the skill.
description	string	REQUIRED	What this tool does. Provided to the AI model for tool selection.
input_schema	JSON Schema object	REQUIRED	JSON Schema defining the tool’s input parameters.
handler	function	REQUIRED (runtime)	Implementation-defined. Receives validated input and a context object. Not serialized.

Tool Invocation Contract

A conforming executor:

• MUST validate tool inputs against input_schema before invoking the handler.
• MUST provide a ToolContext to the handler containing resolved config values and a logger.
• Tool outputs are opaque JSON values. They are included in the execution trace and available to the AI model within the current node’s execution.
• If a tool handler throws, the error is surfaced to the AI model as a tool result. The executor MUST NOT crash.

Well-Known Skill Registry

The specification defines the following well-known skill IDs. Implementations SHOULD support these when the required config is available. Implementations MAY support additional skills beyond this registry.

ID	Category	Required Config	Description
github	git	GITHUB_TOKEN	GitHub code search, issues, pull requests.
linear	tasks	LINEAR_API_KEY	Linear issue tracking.
slack	notification	SLACK_WEBHOOK_URL	Slack messaging.
sentry	observability	SENTRY_AUTH_TOKEN	Sentry error tracking.
datadog	observability	DD_API_KEY, DD_APP_KEY	Datadog logs and metrics.
betterstack	observability	BETTERSTACK_API_TOKEN	BetterStack incident management.
notification	notification	varies	Multi-channel notifications.
supabase	general	SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY	Supabase database operations.

Example

# Skill definition (programmatic, not YAML — shown for illustration)
id: github
name: GitHub
description: Search code, manage issues and pull requests on GitHub.
category: git
config:
  GITHUB_TOKEN:
    description: GitHub personal access token or installation token.
    required: true
    env: GITHUB_TOKEN
tools:
  - name: search_code
    description: Search for code across repositories.
    input_schema:
      type: object
      properties:
        query: { type: string }
        repo: { type: string }
      required: [query]
  - name: create_issue
    description: Create a new issue in a repository.
    input_schema:
      type: object
      properties:
        repo: { type: string }
        title: { type: string }
        body: { type: string }
      required: [repo, title]

JSON Schema

The canonical JSON Schema for validating Skill definitions is available at spec.sweny.ai/schemas/skill.json.