writing-caplets

Writing Caplets

Core Rule

Write Caplets from the active schema, local conventions, and nearby examples first, not from memory.

Treat the YAML frontmatter as the machine contract and the Markdown body as the agent operating guide. The body should help an agent decide when and how to use the Caplet; it should not read like an installer README.

Before editing, discover the user's environment:

1. Find the target Caplet file or intended destination. Common names include CAPLET.md, caplet.md, files under a caplets/ directory, or entries in a Caplet set.
2. Look for a local schema reference in the file. If none is present, prefer the public schema URL https://caplets.dev/caplet.schema.json when adding editor metadata.
3. Read nearby Caplets, project docs, or config files to match naming, auth, setup, and install conventions.
4. Use the repository's own package manager, scripts, and docs for validation when they exist. Do not assume this is the Caplets source repository.

Authoring Workflow

1. Clarify the integration goal: what the agent should be able to inspect, search, call, automate, or summarize.
2. Pick the backend family that matches the strongest real interface, such as mcpServer, openapiEndpoint, googleDiscoveryApi, graphqlEndpoint, httpApi, cliTools, or capletSet.
   • Prefer OpenAPI, GraphQL, Google Discovery, or explicit HTTP actions when the provider has a stable API contract that Caplets can filter into a compact workflow.
   • Prefer MCP when the provider's MCP server is the official curated agent surface or handles workflow/auth better than the raw API.
   • Prefer CLI/local backends when the capability is inherently local or project-bound.
   • Do not choose MCP only because an MCP server exists.
3. Use a multi-backend Caplet file when one provider-scale capability needs several child surfaces under one catalog card and install unit:
   • Use plural maps such as mcpServers, openapiEndpoints, googleDiscoveryApis, graphqlEndpoints, httpApis, cliTools, or capletSets.
   • Runtime child handles are parent__child, based on the file ID and child map key. Users install the parent ID, not the child handle.
   • Put shared guidance, tags, setup, runtime requirements, and provider-level auth at the parent when they truly apply to every child. Child fields override parent scalars; child auth should stay least-privilege when scopes differ.
   • Keep singular cliTools.actions for one CLI backend. In plural cliTools, actions is reserved and cannot be a child ID.
   • Use capletSet or capletSets only for nesting or composing another Caplets collection, not as the default shape for a single provider suite.
4. Keep checked-in Caplets safe for their audience:
   • For public Caplets, never include tokens, credential-bearing URLs, private provider IDs, browser profiles, user home paths, local absolute paths, or account-specific values.
   • For private Caplets, still isolate secrets and account-specific values so the Caplet can be reviewed and moved safely.
5. Use $vault:NAME or ${vault:NAME} for secrets the runtime should resolve. Use $env:NAME only for non-secret machine-local paths, feature flags, or runtime toggles.
6. Add projectBinding.required: true when the Caplet reads, searches, executes against, or mutates project files. Explain in the body why the bound project root is required.
7. Add setup.commands and setup.verify when the backend needs local binaries, browser dependencies, generated specs, provider setup, or a repeatable readiness check.
8. Add runtime.features only for real runtime requirements such as browser or docker.
9. Add optional catalog.icon only when it improves public catalog presentation:
   • Use a safe HTTPS image URL or a bundled image path relative to the Caplet directory.
   • Prefer a real provider, project, or capability icon from a license-safe public source when publishing public Caplets.
   • Do not use catalog metadata to imply trust, safety, setup readiness, endorsement, or runtime behavior.
10. Write the Markdown body for agents that will use the Caplet: