A reusable definition of an agent ability that can be referenced by tasks and resolved by bindings.
Overview
Capabilities define abstract abilities that agents or tools can provide. By separating capability definitions from their implementations, plans become portable across different environments. A task can require "code-generation" capability without specifying which specific agent provides it—that's determined at runtime through bindings.
Schema
yaml
apiVersion: planspec.io/v1alpha1
kind: Capability
metadata:
name: string # Required, unique identifier
namespace: string # Required, resource namespace
labels: object # Optional, key-value pairs
annotations: object # Optional, metadata
spec:
description: string # Required, what this capability provides
displayName: string # Optional, human-friendly name
category: string # Optional, capability category
inputs: # Optional, inputs the capability accepts
- name: string # Input name
type: string # Input type (string, number, boolean, object, array)
required: boolean # Whether input is required
description: string # Input description
default: any # Default value
format: string # Format hint (e.g., "uri", "email", "date-time")
enum: any[] # Allowed values
itemType: string # Type of array items (if type is array)
objectProperties: object # Property definitions (if type is object)
outputs: # Optional, what the capability produces
- name: string # Output name
type: string # Output type
description: string # Output description
requirements: # Optional, capability dependencies
- name: string # Required capability name
status:
phase: string # Capability availability phase
conditions: object[] # Status conditions
observedGeneration: number # Last observed generation
replacement: # Replacement capability (if deprecated)
name: string # Name of replacement capability
namespace: string # Optional, namespace of replacement
deprecationMessage: string # Deprecation notice
Fields
Spec Fields
Field
Type
Required
Description
description
string
Yes
What this capability provides
displayName
string
No
Human-friendly display name
category
string
No
Capability category for organization
inputs
object[]
No
Inputs the capability accepts
outputs
object[]
No
What the capability produces
requirements
object[]
No
Other capabilities this one depends on
Input Definition Fields
Field
Type
Required
Description
name
string
Yes
Input name
type
string
Yes
Type: string, number, boolean, object, array
required
boolean
No
Whether required (default: false)
description
string
No
Input description
default
any
No
Default value
format
string
No
Format hint (e.g., "uri", "email", "date-time")
enum
any[]
No
List of allowed values
itemType
string
No
Type of array items (when type is array)
objectProperties
object
No
Property definitions (when type is object)
Output Definition Fields
Field
Type
Required
Description
name
string
Yes
Output name
type
string
Yes
Output type
description
string
No
Output description
Requirement Fields
Field
Type
Required
Description
name
string
Yes
Name of required capability
Status Fields
Field
Type
Description
phase
string
Capability availability phase
conditions
object[]
Status conditions with details
observedGeneration
number
Last observed spec generation
replacement
object
Reference to replacement capability (if deprecated)
deprecationMessage
string
Message explaining deprecation
Capability Phases
Phase
Description
Available
Capability is available for use
Unavailable
Capability is not currently available
Deprecated
Capability is deprecated (see replacement)
Common Categories
Category
Description
code
Code generation, review, and refactoring
data
Data access, transformation, and analysis
test
Test execution and validation
deploy
Deployment and infrastructure
communication
Notifications and messaging
Example
yaml
apiVersion: planspec.io/v1alpha1
kind: Capability
metadata:
name: code-generation
namespace: default
labels:
category: code
spec:
description: Generate code in specified programming languages
displayName: Code Generation
category: code
inputs:
- name: language
type: string
required: true
description: Target programming language
enum: ["typescript", "python", "go", "rust", "java"]
- name: framework
type: string
required: false
description: Framework or library context
- name: style
type: string
required: false
description: Code style guidelines to follow
default: "standard"
- name: files
type: array
required: false
description: Existing files for context
itemType: string
outputs:
- name: code
type: string
description: Generated source code
- name: explanation
type: string
description: Explanation of the generated code
---
apiVersion: planspec.io/v1alpha1
kind: Capability
metadata:
name: database-access
namespace: default
spec:
description: Read and write data to SQL databases
displayName: Database Access
category: data
inputs:
- name: dialect
type: string
required: true
description: SQL dialect (postgres, mysql, sqlite)
enum: ["postgres", "mysql", "sqlite"]
- name: readOnly
type: boolean
required: false
default: true
description: Whether to restrict to read operations
- name: connectionConfig
type: object
required: false
description: Connection configuration
objectProperties:
host:
name: host
type: string
port:
name: port
type: number
database:
name: database
type: string
outputs:
- name: results
type: object
description: Query results
requirements:
- name: network-access
---
apiVersion: planspec.io/v1alpha1
kind: Capability
metadata:
name: test-execution
namespace: default
spec:
description: Execute test suites and report results
displayName: Test Execution
category: test
inputs:
- name: testPattern
type: string
required: false
description: Pattern to filter tests
- name: coverage
type: boolean
required: false
default: false
description: Whether to collect coverage data
- name: parallel
type: number
required: false
description: Number of parallel test runners
outputs:
- name: passed
type: boolean
description: Whether all tests passed
- name: summary
type: object
description: Test results summary