Caplet files

Caplet files are Markdown files with two independent projections. YAML frontmatter is the sole authority for runtime configuration and structured agent-selection metadata. The Markdown body is a publishable human operator README rendered separately; it is never a runtime input, interpolation source, selection channel, Code Mode declaration, or agent context. Do not include secrets, credentials, private endpoints, customer data, or other sensitive operational material in the body. Store a single-file Caplet as osv.md, or use a folder with CAPLET.md when frontmatter references nearby runtime assets.

useWhen and avoidWhen are literal public agent-selection metadata and are not template-interpolated. Existing hints such as useWhen: "Use for ${TENANT}" must be rewritten as literal selection prose. Move dynamic or private values into the appropriate runtime fields, such as backend configuration, auth, environment, or setup fields. Never put secrets or sensitive operational values in selection metadata.

Canonical schema: https://caplets.dev/caplet.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.
useWhen: Prefer for local evaluation of the example MCP tools.
avoidWhen: Avoid for production or provider-specific workflows.
exposure: code_mode
mcpServer:
  command: npx
  args: ["-y", "@modelcontextprotocol/server-everything"]
---

# Example Tools

## Prerequisites and setup context

Confirm Node.js and package-registry access before enabling this example.

## Safe operation and limits

This example server is intended for evaluation. Review its exposed tools and permissions before use.

## Troubleshooting

If startup fails, verify the local Node.js installation and package-registry connectivity.

## References

See the package documentation for supported tools and limits.

Runtime actions, paths, environment and authentication values, setup metadata, exposure, and agent-selection guidance belong in frontmatter. Use useWhen and avoidWhen for selection. Treat the body as publishable content: reserve it for human prerequisites, safety, troubleshooting, and references, and do not include secrets or sensitive operational material.

Project-bound Caplet with setup:

---
name: Repository Checks
description: Run repository-local checks before an agent edits this project.
useWhen: Prefer when repository-local test results are required.
avoidWhen: Avoid when no project is attached.
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"]
---

# Repository Checks

## Prerequisites and setup context

Install the repository dependencies before running the configured checks.

## Safe operation and limits

Review the repository scripts before enabling them; they execute with the attached project's permissions.

## Troubleshooting

If a check cannot start, confirm the package manager and dependencies match the repository lockfile.

## References

The repository's `package.json` and lockfile document the available scripts and tool versions.

Provider suite with multiple runtime children:

---
name: Google Workspace
description: Work with Gmail and Drive from one installable capability.
useWhen: Prefer when work spans Gmail and Drive.
avoidWhen: Avoid when only one provider surface is needed.
tags: [google, workspace]
auth:
  type: oauth2
  issuer: https://accounts.google.com
googleDiscoveryApis:
  drive:
    name: Google Drive
    description: Search and inspect Drive files.
    discoveryPath: ./drive.discovery.json
    includeOperations: [drive.files.list, drive.files.get]
    auth:
      type: oauth2
      issuer: https://accounts.google.com
      scopes:
        - https://www.googleapis.com/auth/drive.metadata.readonly
  gmail:
    name: Gmail
    description: Search and inspect Gmail messages.
    discoveryPath: ./gmail.discovery.json
    includeOperations: [gmail.users.messages.list, gmail.users.messages.get]
    auth:
      type: oauth2
      issuer: https://accounts.google.com
      scopes:
        - https://www.googleapis.com/auth/gmail.readonly
---

# Google Workspace

## Prerequisites and setup context

Confirm the operator has approved the OAuth consent and scopes declared in frontmatter.

## Safe operation and limits

This suite exposes read-only message and file metadata operations. Handle returned workspace data according to organizational policy.

## Troubleshooting

If a child capability is unavailable, verify its discovery document and granted OAuth scope.

## References

Consult the Gmail and Drive API documentation for operation and quota details.

Installing the parent google-workspace copies the whole suite. Runtime handles are google-workspace__drive and google-workspace__gmail; child IDs are not installed directly. Use plural backend maps for one authored provider suite, and use capletSet or capletSets only when composing or nesting another Caplets collection.

Top-level fields

Field	Status	Type	Description
$schema	Optional	string	Optional JSON Schema 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” | “namespace”	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.
auth	Optional	object	Shared auth inherited by plural remote backend entries.
catalog	Optional	object	Optional presentation metadata for public catalog surfaces.
mcpServer	Optional	object	MCP server backend configuration for this Caplet.
mcpServers	Optional	object	Multiple MCP server backend configurations keyed by child ID.
openapiEndpoint	Optional	object	OpenAPI endpoint backend configuration for this Caplet.
openapiEndpoints	Optional	object	Multiple OpenAPI endpoint backend configurations keyed by child ID.
googleDiscoveryApi	Optional	object	Google Discovery API backend configuration for this Caplet.
googleDiscoveryApis	Optional	object	Multiple Google Discovery API backend configurations keyed by child ID.
graphqlEndpoint	Optional	object	GraphQL endpoint backend configuration for this Caplet.
graphqlEndpoints	Optional	object	Multiple GraphQL endpoint backend configurations keyed by child ID.
httpApi	Optional	object	HTTP API backend configuration for this Caplet.
httpApis	Optional	object	Multiple HTTP API backend configurations keyed by child ID.
cliTools	Optional	object	CLI tools backend configuration, or plural CLI backend configurations.
capletSet	Optional	object	Nested Caplet collection backend configuration for this Caplet.
capletSets	Optional	object	Multiple nested Caplet collection backend configurations keyed by child ID.

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.

mcpServers

Multiple MCP server backend configurations keyed by child ID.

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.
name	Optional	string	See the canonical schema for details.
description	Optional	string	See the canonical schema for details.
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” | “namespace”	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.

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.

openapiEndpoints

Multiple OpenAPI endpoint backend configurations keyed by child ID.

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	Optional	object	Explicit OpenAPI request auth config.
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.
name	Optional	string	See the canonical schema for details.
description	Optional	string	See the canonical schema for details.
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” | “namespace”	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.

googleDiscoveryApi

Google Discovery API backend configuration for this Caplet.

Field	Status	Type	Description
discoveryPath	Optional	string	Local Google Discovery document path.
discoveryUrl	Optional	string	Remote Google Discovery document URL.
baseUrl	Optional	string	Override base URL for Google API requests.
auth	Required	object	Explicit Google API request auth config. Use {“type”:“none”} for public APIs.
requestTimeoutMs	Optional	integer	Timeout in milliseconds for Google API HTTP requests.
operationCacheTtlMs	Optional	integer	Milliseconds Google Discovery operation metadata stays fresh. Set 0 to refresh every time.
includeOperations	Optional	array	Optional list of includeOperations.
excludeOperations	Optional	array	Optional list of excludeOperations.
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.

googleDiscoveryApis

Multiple Google Discovery API backend configurations keyed by child ID.

Field	Status	Type	Description
discoveryPath	Optional	string	Local Google Discovery document path.
discoveryUrl	Optional	string	Remote Google Discovery document URL.
baseUrl	Optional	string	Override base URL for Google API requests.
auth	Optional	object	Explicit Google API request auth config.
requestTimeoutMs	Optional	integer	Timeout in milliseconds for Google API HTTP requests.
operationCacheTtlMs	Optional	integer	Milliseconds Google Discovery operation metadata stays fresh. Set 0 to refresh every time.
includeOperations	Optional	array	Optional list of includeOperations.
excludeOperations	Optional	array	Optional list of excludeOperations.
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.
name	Optional	string	See the canonical schema for details.
description	Optional	string	See the canonical schema for details.
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” | “namespace”	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.

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.

graphqlEndpoints

Multiple GraphQL endpoint backend configurations keyed by child ID.

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	Optional	object	Explicit GraphQL request auth config.
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.
name	Optional	string	See the canonical schema for details.
description	Optional	string	See the canonical schema for details.
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” | “namespace”	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.

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.

httpApis

Multiple HTTP API backend configurations keyed by child ID.

Field	Status	Type	Description
baseUrl	Required	string	Base URL for HTTP action requests.
auth	Optional	object	Explicit HTTP API request auth config.
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.
name	Optional	string	See the canonical schema for details.
description	Optional	string	See the canonical schema for details.
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” | “namespace”	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.

cliTools

CLI tools backend configuration, or plural CLI backend configurations.

Singular form:

Field	Status	Type	Description
actions	Required	object	Configured CLI actions keyed by stable tool name.
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.

Plural form child fields:

Field	Status	Type	Description
actions	Required	object	Configured CLI actions keyed by stable tool name.
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.
name	Optional	string	See the canonical schema for details.
description	Optional	string	See the canonical schema for details.
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” | “namespace”	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.

Plural cliTools is recognized only when the value is a child-ID map. actions is reserved for the singular form and cannot be used as a plural child ID.

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.

capletSets

Multiple nested Caplet collection backend configurations keyed by child ID.

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.
name	Optional	string	See the canonical schema for details.
description	Optional	string	See the canonical schema for details.
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” | “namespace”	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.