Caplet files

Caplet files are Markdown files with YAML frontmatter. Store a single-file Caplet as osv.md, or use a folder with CAPLET.md when the capability needs nearby assets.

Canonical schema: https://caplets.dev/caplet-frontmatter.schema.json

Status values are Required or Optional according to the schema’s top-level required array.

Top-level fields

Field	Status	Type	Description
$schema	Optional	string	Optional JSON Schema URL for editor validation.
name	Required	string	Human-readable Caplet display name.
description	Required	string	Compact capability description shown before the full Caplet card is disclosed.
tags	Optional	array	Optional tags for grouping or searching Caplets.
exposure	Optional	”direct” | “progressive” | “code_mode” | “direct_and_code_mode” | “progressive_and_code_mode”	How this Caplet is exposed to agents.
shadowing	Optional	”forbid” | “allow”	Whether attached local Caplets may shadow this remote Caplet ID.
useWhen	Optional	string	When agents should prefer this Caplet or configured action.
avoidWhen	Optional	string	When agents should avoid this Caplet or configured action.
setup	Optional	object	Optional explicit setup and verification metadata for this Caplet.
projectBinding	Optional	object	Project Binding requirements for Caplets that need an attached project.
runtime	Optional	object	Runtime feature and resource requirements for hosted execution.
mcpServer	Optional	object	MCP server backend configuration for this Caplet.
openapiEndpoint	Optional	object	OpenAPI endpoint backend configuration for this Caplet.
graphqlEndpoint	Optional	object	GraphQL endpoint backend configuration for this Caplet.
httpApi	Optional	object	HTTP API backend configuration for this Caplet.
cliTools	Optional	object	CLI tools backend configuration for this Caplet.
capletSet	Optional	object	Nested Caplet collection backend configuration for this Caplet.

Major sections

setup

Optional explicit setup and verification metadata for this Caplet.

Field	Status	Type	Description
commands	Optional	array
verify	Optional	array

projectBinding

Project Binding requirements for Caplets that need an attached project.

Field	Status	Type	Description
required	Required	boolean

runtime

Runtime feature and resource requirements for hosted execution.

Field	Status	Type	Description
features	Optional	array
resources	Optional	object

mcpServer

MCP server backend configuration for this Caplet.

Field	Status	Type	Description
transport	Optional	”stdio” | “http” | “sse”	Downstream MCP transport. Defaults to stdio when command is present.
command	Optional	string	Executable command for stdio servers.
args	Optional	array	Arguments passed to the stdio command.
env	Optional	object	Environment variables for stdio servers. Supports ${VAR} and $env:VAR.
cwd	Optional	string	Working directory for stdio servers.
url	Optional	string	Remote MCP server URL for http or sse transport.
auth	Optional	object | object | object | object | object	Authentication settings for a remote MCP server.
startupTimeoutMs	Optional	integer	Timeout in milliseconds for starting or checking a downstream server.
callTimeoutMs	Optional	integer	Timeout in milliseconds for downstream tool calls.
toolCacheTtlMs	Optional	integer	Milliseconds downstream tool metadata stays fresh. Set 0 to refresh every time.
disabled	Optional	boolean	When true, omit this Caplet from discovery and do not start its MCP server.
projectBinding	Optional	object	Project Binding requirements for Caplets that need an attached project.
runtime	Optional	object	Runtime feature and resource requirements for hosted execution.

openapiEndpoint

OpenAPI endpoint backend configuration for this Caplet.

Field	Status	Type	Description
specPath	Optional	string	Local OpenAPI specification path.
specUrl	Optional	string	Remote OpenAPI specification URL.
baseUrl	Optional	string	Override base URL for OpenAPI requests.
auth	Required	object | object | object | object | object	Explicit OpenAPI request auth config. Use {“type”:“none”} for public APIs.
requestTimeoutMs	Optional	integer	Timeout in milliseconds for OpenAPI HTTP requests.
operationCacheTtlMs	Optional	integer	Milliseconds OpenAPI operation metadata stays fresh. Set 0 to refresh every time.
disabled	Optional	boolean	When true, omit this Caplet from discovery.
projectBinding	Optional	object	Project Binding requirements for Caplets that need an attached project.
runtime	Optional	object	Runtime feature and resource requirements for hosted execution.

graphqlEndpoint

GraphQL endpoint backend configuration for this Caplet.

Field	Status	Type	Description
endpointUrl	Required	string	GraphQL HTTP endpoint URL.
schemaPath	Optional	string	Local GraphQL SDL or introspection path.
schemaUrl	Optional	string	Remote GraphQL SDL or introspection URL.
introspection	Optional	boolean	Load schema through endpoint introspection.
operations	Optional	object	Configured GraphQL operations keyed by stable tool name.
auth	Required	object | object | object | object | object	Explicit GraphQL request auth config. Use {“type”:“none”} for public APIs.
requestTimeoutMs	Optional	integer	Timeout in milliseconds for GraphQL HTTP requests.
operationCacheTtlMs	Optional	integer	Milliseconds GraphQL operation metadata stays fresh. Set 0 to refresh every time.
selectionDepth	Optional	integer	Maximum depth for auto-generated GraphQL selection sets.
disabled	Optional	boolean	When true, omit this Caplet from discovery.
projectBinding	Optional	object	Project Binding requirements for Caplets that need an attached project.
runtime	Optional	object	Runtime feature and resource requirements for hosted execution.

httpApi

HTTP API backend configuration for this Caplet.

Field	Status	Type	Description
baseUrl	Required	string	Base URL for HTTP action requests.
auth	Required	object | object | object | object | object	Explicit HTTP API request auth config. Use {“type”:“none”} for public APIs.
actions	Required	object	Configured HTTP actions keyed by stable tool name.
requestTimeoutMs	Optional	integer	Timeout in milliseconds for HTTP action requests.
maxResponseBytes	Optional	integer	Maximum HTTP action response body bytes to read.
disabled	Optional	boolean	When true, omit this Caplet from discovery.
projectBinding	Optional	object	Project Binding requirements for Caplets that need an attached project.
runtime	Optional	object	Runtime feature and resource requirements for hosted execution.

cliTools

CLI tools backend configuration for this Caplet.

Field	Status	Type	Description
actions	Required	object	Configured CLI actions keyed by stable tool name.
cwd	Optional	string	Default working directory for CLI actions.
env	Optional	object	Default environment variables.
timeoutMs	Optional	integer
maxOutputBytes	Optional	integer
disabled	Optional	boolean	When true, omit this Caplet from discovery.
projectBinding	Optional	object	Project Binding requirements for Caplets that need an attached project.
runtime	Optional	object	Runtime feature and resource requirements for hosted execution.

capletSet

Nested Caplet collection backend configuration for this Caplet.

Field	Status	Type	Description
configPath	Optional	string	Child Caplets config.json path.
capletsRoot	Optional	string	Child Markdown Caplets root directory.
defaultSearchLimit	Optional	integer
maxSearchLimit	Optional	integer
toolCacheTtlMs	Optional	integer
disabled	Optional	boolean	When true, omit this Caplet from discovery.
projectBinding	Optional	object	Project Binding requirements for Caplets that need an attached project.
runtime	Optional	object	Runtime feature and resource requirements for hosted execution.