Runtype Templates
Use this skill when a Runtype product should become a portable Full Product Object (FPO) template that another workspace, team, customer, or marketplace user can import. It also covers installing a product from a shared example or template link.
Source of truth
When the Runtype MCP server is available, read the schema docs before you write or validate a template.
Always read:
get_platform_documentation(topic="types-fpo-template")for the template wrapper.get_platform_documentation(topic="types-fpo")for the wrappedproductObject. Use FPO version2.0for new templates.get_platform_documentation(topic="product-schema")for the JSON Schema of the product object.
Read these when the template contains that part:
- Surfaces:
surface-typesandtypes-surface-configs. - Flows:
flow-step-types. - Tools:
builtin-tools,orthogonal-tools, andexternal-tools.
For prose guidance, call search_documentation for "FPO templates" or read the public
guides: FPO templates and
Importing products.
Template shape
An FPO template has three top-level keys:
version: the template format version,"1.0"or"1.1". This is separate fromproductObject.version, which is"2.0"for new templates.productObject: the full product definition.template.variables: the non-secret values the importer supplies.
A template must declare at least one variable or at least one pending secret: a tool with
auth.setupRequired: true and a non-empty auth.secrets array, a top-level
productObject.secrets[] entry, or a {{secret:KEY}} reference anywhere in the product.
Use variables for names, public URLs, recipient lists, selected models, and other non-secret configuration. Every credential uses the pending-secret pattern.
Variables
Each variable needs key, label, inputType, and required:
{
"key": "companyName",
"label": "Company name",
"inputType": "text",
"required": true,
"defaultValue": "Acme"
}
inputTypeis one oftext,textarea,url,secret,select,number, orboolean.- A
selectvariable needs a non-emptyoptionsarray of{ "label", "value" }. Onlyselectvariables can haveoptions. - A template can declare up to 50 variables.
- Set defaults with
defaultValue. Inline{{key|default}}syntax is rejected. - When a string field is exactly
{{key}}and the variable isnumberorboolean, the field keeps that type. Every other substitution produces a string. - A typed field (a URL such as
externalConfig.endpoint, a number such asconfig.loopConfig.maxTurns, an enum, or a datetime such as a schedule'srunAt) can hold a variable. Validation checks such fields after substitution, so a bad default or import value fails there instead.
Runtime tokens and template variables
Import treats every bare {{name}} in productObject as a template variable. That
includes runtime tokens such as a step output in a prompt. Only these references pass
through to run time without a declaration:
{{secret:KEY}}{{flow:name}}, which resolves to the flow variablenameat run time- System and message variables, such as
{{_record.metadata.field}},{{_now}},{{userMessage}}, and{{messages}} - Host-resolved variables:
{{_identity.token}}in a tool or MCP header, and{{_agent.*}}/{{_organization.id}}in a memoryprofileTemplate, including a fallback such as{{_agent.alias || "live"}}
When you turn a working product into a template, rewrite runtime flow tokens with the
flow: prefix. For example, change Summarize {{research}} to
Summarize {{flow:research}}. Do not declare a runtime token as a template variable,
because import replaces it with a fixed value.
If a field cannot take the flow: prefix, such as a Liquid template body, declare a
template variable whose defaultValue is the runtime text, and reference that variable in
the field.
Optional bundled resources
A template can also ship these productObject arrays. Import creates each resource:
schedules[]: cron or one-time runs that target a capability throughcapabilityId. A scheduled capability does not need atype: "schedule"surface.evals[]: eval suites with their cases.skills[]: agent skills, bound to agent capabilities throughbindTo.
For the field tables, see the FPO templates guide.
Pending secrets
Use this pattern for every credential:
- Declare the key on the target tool's
auth.secretsarray. - Set
auth.setupRequired: true, plusauth.typeandauth.setupInstructions. - Reference the key in the tool config as
{{secret:KEY}}. - Leave the value out of the template. Import creates the secret as unconfigured, and the importer fills it in after import.
{
"config": {
"headers": { "Authorization": "Bearer {{secret:ACME_API_KEY}}" }
},
"auth": {
"type": "api_key",
"setupRequired": true,
"secrets": [{ "key": "ACME_API_KEY", "required": true }],
"setupInstructions": {
"summary": "Add your Acme API key.",
"steps": ["Create an API key in Acme.", "Add it as a secret after import."]
}
}
}
Each auth.secrets entry is an object with key and required, not a bare string.
When the credential belongs to the product rather than one tool (an MCP server header, an
external agent's auth, a model key), declare it in top-level productObject.secrets[]
({ "id", "key", "description"?, "required"? }) and reference it as {{secret:KEY}}
wherever it is used. Import lists it with the other pending secrets.
Do not use a variable with inputType: "secret" for credentials. Import writes that value
into the product object as plain text. A secret variable cannot have a defaultValue.
Validation workflow
- Validate the template document with
runtype validate-product ./template.json --templateorPOST https://api.runtype.com/v1/public/products/validate-template. Fix every error, such asUNDECLARED_TEMPLATE_VARIABLE,INLINE_TEMPLATE_DEFAULT_NOT_ALLOWED, andDUPLICATE_TEMPLATE_VARIABLE. Review warnings such asUNUSED_TEMPLATE_VARIABLEandTEMPLATE_VARIABLE_SECRET_IS_UNSAFE. - Resolve template defaults, or supply test values for required variables.
- Run
validate_producton the resolved product object. - Run the focused validators for changed parts:
validate_product_tool,validate_product_flow,validate_product_agent, andvalidate_product_surface. - Confirm that every route references a real capability id.
- Confirm that every secret reference has a matching pending-secret declaration.
- Confirm that importer-visible variables are few and meaningful.
Share a template
Host the template JSON at a public HTTPS URL, such as a raw GitHub file URL.
URL-encode that URL and share
https://use.runtype.com/now?from=ENCODED_TEMPLATE_URL.Optional: Prefill a variable with
&templateParam%3AVARIABLE_KEY=VALUE. The import page ignores prefilled values for secret variables.Optional: Add a button to a repository
README:[Deploy to Runtype](https://use.runtype.com/now?from=https%3A%2F%2Fexample.com%2FYOUR_TEMPLATE.json)Test the link: pass it to
create_product_from_exampleasurland confirm the product is created.
Set up a product from a link
When a user provides a use.runtype.com/now?... link, a runtype.com/examples/<slug> page,
or a direct FPO or template JSON URL, do not open the dashboard page, which requires
sign-in. Pass the original link to create_product_from_example as url, or pass a known
slug from list_example_templates.
- Supply import-time values in the tool's
variablesargument. Omitted keys fall back totemplateParamvalues in the link, then to template defaults. If a required variable still has no value, the tool returns the variable specs and creates nothing. Ask the user for those values, then call the tool again with them invariables. - Draft examples require
allow_draft: true. Use it only when the user intends to install that draft. - Call
get_product_setupwith the created product id. Complete the steps you can automate, and give the user the remaining secret, OAuth, or surface-install links. Never ask the user to paste secret values in chat. Give them the dashboard link fromget_product_setuporget_secret_intake_manifest, then confirm withcheck_secrets. - Test the product at its user-facing layer. For an agent, call
execute_agentwith amessagesarray of{ "role": "user", "content": "..." }turns.
The tool rejects some links:
- A link with
?import=or?sessionId=points to a temporary import preview. Ask for the original source: an example slug, a?session=link, or the document URL. - A link with
?template=points to a built-in dashboard template. Open it in the dashboard, or build the product withcreate_product. - A
/nowlink with none ofexample,session,templateUrl, orfromhas nothing to import. Ask the user for the full link.
Anti-patterns
- Hardcoded API keys, tokens, client secrets, or bearer values.
- Too many variables. Every variable adds setup work for the importer.
- Workspace ids, runtime ids, or surface keys as template variables.
- Bare runtime tokens such as
{{research}}left in the product object. - Partial product schemas with a note that validation still needs work.
- Templates for one-off private account updates. Use the
runtype-adminskill instead.
For platform scoping and account setup, use the runtype skill.