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.
instruction	string	OPTIONAL	Natural language expertise injected into the node prompt when this skill is referenced.
mcp	McpServerConfig	OPTIONAL	External MCP server definition wired for nodes referencing this skill.

A valid Skill MUST provide at least one of tools, instruction, or mcp.

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.
data	Embeddings, vector stores, databases, ETL.
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.

McpServerConfig Object

Declares an external MCP (Model Context Protocol) server that provides tools to the AI model at runtime.

Field	Type	Required	Description
type	"stdio" | "http"	OPTIONAL	Transport type. Inferred from presence of command (stdio) or url (http) when omitted.
command	string	CONDITIONAL	Spawn command (stdio transport). Required if url absent.
args	string[]	OPTIONAL	Arguments for the command.
url	string	CONDITIONAL	HTTP endpoint (HTTP transport). Required if command absent.
headers	Record<string, string>	OPTIONAL	HTTP headers (HTTP transport only).
env	Record<string, string>	OPTIONAL	Environment variable names the server needs. Values are human-readable descriptions, not secrets. Actual values are resolved from process.env at runtime.

A conforming executor:

• MUST wire the MCP server only for nodes that reference the skill declaring it (node-scoped, not global).
• MUST resolve env values from process.env at runtime (the declared values are descriptions, not secrets).
• SHOULD prefer user-supplied MCP server configs over skill-declared ones when both exist for the same key.

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.
access	"read" | "write"	OPTIONAL	Side-effect class. read only reads; write creates, updates, deletes, posts, or sends. Absent means write. See Dry-Run Semantics.
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.

Built-in Skills

Implementations MAY provide built-in skills that are available without explicit definition by the user. Built-in skills follow the same Skill Object schema as custom skills — there is no structural distinction.

Skill ID Conventions

Skill IDs:

• MUST be non-empty strings.
• SHOULD use lowercase kebab-case (e.g., github, error-tracking, my-custom-tool).
• MUST be unique within a workflow. If a custom skill uses the same ID as a built-in skill, the custom skill’s instruction and mcp fields take precedence, but the built-in skill’s tools remain available.

Discovery

A conforming executor SHOULD document which built-in skills it provides, including their IDs, required config fields, and available tools. This catalog is implementation-specific and outside the scope of this specification.

Note

The reference implementation (@sweny-ai/core) documents its built-in skills at docs.sweny.ai/skills.

Custom Skills

Custom skills are authored as directories containing a SKILL.md file. The format follows the Agent Skills Open Standard.

SKILL.md Format

A skill directory contains a SKILL.md file with YAML frontmatter and a markdown body:

---
name: code-standards
description: Team coding conventions for TypeScript projects
mcp:
  command: npx
  args: ["-y", "@company/tool-server"]
  env:
    API_KEY: Company API key
---

When writing TypeScript code, follow these standards:

- Use camelCase for variables and functions
- Use PascalCase for types and interfaces

The markdown body becomes the skill’s instruction, injected into the node prompt when the skill is referenced. The mcp, category, and config frontmatter fields are SWEny-specific extensions:

Frontmatter field	Required	Description
name	REQUIRED	Skill ID. MUST satisfy Skill ID Conventions.
description	OPTIONAL	One-line summary. Defaults to Custom skill: <name> when omitted.
category	OPTIONAL	One of the Skill Categories. Defaults to general when omitted or invalid.
config	OPTIONAL	Map of env-var-backed config fields with the same shape as the Config Field Object.
mcp	OPTIONAL	External MCP server definition with the same shape as McpServerConfig.

Multi-Harness Discovery

A conforming executor SHOULD discover custom skills from the following directories, in priority order (highest first):

Priority	Directory	Convention
1	.sweny/skills/<name>/SKILL.md	SWEny-native
2	.claude/skills/<name>/SKILL.md	Claude Code
3	.agents/skills/<name>/SKILL.md	Universal (Codex, Gemini CLI, OpenCode)
4	.gemini/skills/<name>/SKILL.md	Gemini CLI

On ID collision, the higher-priority directory wins. When a custom skill overrides a built-in skill ID, the custom skill’s instruction and mcp fields take precedence, but the built-in skill’s tools remain available.

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.
    access: read
    input_schema:
      type: object
      properties:
        query: { type: string }
        repo: { type: string }
      required: [query]
  - name: create_issue
    description: Create a new issue in a repository.
    access: write
    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.