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.

Common frontmatter

Minimal Markdown Caplet:

---
name: Example Tools
description: Expose a small local MCP server to agents.
exposure: code_mode
mcpServer:
  command: npx
  args: ["-y", "@modelcontextprotocol/server-everything"]
---

Use this Caplet when an agent needs the example MCP tools.

Use useWhen and avoidWhen to guide agent selection, and add setup metadata when a Caplet needs local commands before it can run.

Project-bound Caplet with setup:

---
name: Repository Checks
description: Run repository-local checks before an agent edits this project.
exposure: code_mode
cliTools:
  actions:
    test:
      description: Run the project test suite.
      command: pnpm
      args: ["test"]
projectBinding:
  required: true
setup:
  verify:
    - label: Test suite
      command: pnpm
      args: ["test"]
---

Use this Caplet when an agent needs the current repository's local test signal.

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.
`googleDiscoveryApi`	Optional	object	Google Discovery API 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	Setup commands users can run before using this Caplet.
`verify`	Optional	array	Verification commands users can run to check setup.

`projectBinding`

Project Binding requirements for Caplets that need an attached project.

Field	Status	Type	Description
`required`	Required	boolean	Whether this capability requires the declared runtime feature or binding.

`runtime`

Runtime feature and resource requirements for hosted execution.

Field	Status	Type	Description
`features`	Optional	array	Runtime features this Caplet expects from the host.
`resources`	Optional	object	Hosted resource requirements for this Caplet.

`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	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	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	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	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	Timeout in milliseconds.
`maxOutputBytes`	Optional	integer	Maximum combined stdout and stderr bytes to keep.
`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	Default number of search results returned when no limit is provided.
`maxSearchLimit`	Optional	integer	Maximum accepted search result limit.
`toolCacheTtlMs`	Optional	integer	Milliseconds tool metadata stays fresh.
`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.