Skip to content

Skill Contracts

Skills can declare their expected inputs and produced outputs, creating a clear contract for how they interact with the environment.

Defining Contracts in SKILL.md

Add inputs and outputs sections to the YAML frontmatter:

---
name: security-scan
description: Scan for vulnerabilities
inputs:
files:
description: List of file paths to scan
type: string
severity:
description: Minimum severity level
type: enum
options: [low, medium, high]
default: medium
outputs:
report:
description: Scan report in markdown
type: string
passed:
description: Whether scan passed
type: boolean
---
Scan the provided files for security issues.
Report findings with at least {{severity}} severity.

Field Properties

Each input or output field supports:

PropertyRequiredDescription
descriptionYesWhat the field represents
typeYesstring, number, boolean, enum
optionsEnum onlyValid values for enum type
defaultNoDefault value if not provided

Combining with Parameters

A skill can have params, inputs, and outputs together:

  • params - Template variables interpolated at compile time ({{var}} syntax)
  • inputs - Runtime data the skill expects to receive
  • outputs - Runtime data the skill produces
---
name: code-review
description: Review {{language}} code
params:
language:
type: string
default: typescript
inputs:
files:
description: Files to review
type: string
outputs:
issues:
description: List of issues found
type: string
score:
description: Quality score
type: number
---
Review the provided {{language}} files.

Validation

The PS017 validation rule checks contract definitions:

  • Field types must be string, number, boolean, or enum
  • Enum fields must include an options array
  • Name collisions between params and inputs are flagged

See Also