Frontmatter Specification

Source Format: 1.0 | Updated: 2025-12-27

Calvin parses YAML frontmatter between --- delimiters. Frontmatter is required for:

• .promptpack/actions/**/*.md
• .promptpack/policies/**/*.md
• .promptpack/agents/**/*.md
• .promptpack/skills/<id>/SKILL.md (skills entrypoint)

Skill supplemental files (anything else under .promptpack/skills/<id>/) do not need frontmatter and are copied as-is to outputs.

Minimal Example

---
description: Generate unit tests for a file
scope: project
targets: [claude-code, cursor]
---

# Generate Tests

Your prompt content here...

Required Fields

description

Type: string
Required: Yes

A short description of the asset. Used by adapters for metadata (titles, summaries, listings).

description: Code style guidelines for TypeScript

Optional Fields

kind

Type: "action" | "policy" | "agent" | "skill"
Default: inferred from directory (or action)

Usually inferred from directory:

kind Support Matrix

Notes:

• In .promptpack/skills/<id>/SKILL.md, kind: skill is optional. If present, it must be skill.

kind: policy

scope

Type: "project" | "user"
Default: "project"

Controls where outputs are deployed:

• project: write to project directories (e.g., ./.claude/, ./.codex/)
• user: write to home directories (e.g., ~/.claude/, ~/.codex/)

scope: user

targets

Type: string[]
Default: all targets

List of platforms to compile for:

• claude-code (alias: claude)
• cursor
• vscode (alias: vs-code)
• antigravity
• codex
• all (meta-target that expands to all concrete targets)

targets:
  - claude-code
  - cursor

apply

Type: string
Default: none

Glob pattern used by adapters that support conditional rules (primarily policies).

apply: "**/*.rs"

Notes:

• Skills do not support apply (Calvin errors if present in SKILL.md frontmatter).
• Some targets ignore apply.

allowed-tools (skill-only)

Type: string[] (YAML sequence)
Default: none

Optional list of allowed tools for skills. Calvin validates this list and surfaces warnings for risky tools (e.g. rm, sudo, curl).

allowed-tools:
  - git
  - cat

Agent-Specific Fields

The following fields are only used for agents (kind: agent). They configure Claude Code subagent behavior.

name

Type: string
Default: asset ID (filename stem)

Custom name for the agent. If not specified, uses the filename (e.g., reviewer.md → reviewer).

name: code-reviewer

tools

Type: string (comma-separated) or string[] (YAML list)
Default: inherit all tools

Whitelist of tools this agent can use. If not specified, the agent inherits all tools from the main thread.

tools: Read, Grep, Glob, Bash

Calvin also accepts the YAML list format:

tools:
  - Read
  - Grep
  - Glob

For backward compatibility, the YAML list format is also accepted as agent-tools:

agent-tools:
  - Read
  - Grep
  - Glob

model

Type: "sonnet" | "opus" | "haiku" | "inherit"
Default: none (uses default model)

Model override for this agent.

model: sonnet

permissionMode

Type: "default" | "acceptEdits" | "dontAsk" | "bypassPermissions" | "plan" | "ignore"
Default: none

Controls how the agent handles permission prompts.

permissionMode: acceptEdits

Calvin also accepts kebab-case as permission-mode:

permission-mode: acceptEdits

skills

Type: string (comma-separated)
Default: none

Skills to preload when this agent starts. Custom subagents do NOT inherit skills from the main thread by default.

skills: repo-navigation, engineering-standards

Calvin also accepts the YAML list format as agent-skills:

agent-skills:
  - repo-navigation
  - engineering-standards

Skill Example

---
description: Draft a conventional commit message from staged changes.
kind: skill
scope: user
targets:
  - claude-code
  - codex
allowed-tools:
  - git
  - cat
---

# Instructions

1. Run `git diff --cached --stat`
2. Suggest a conventional commit message
3. Consult `reference.md` if needed

Placeholder Variables

In the body content, you can include placeholders that are passed through to adapters:

These are passed through unchanged; the target platform interprets them at runtime.

Platform-Specific Mapping (High Level)

Claude Code

• Source frontmatter is not used directly in outputs for actions/policies/agents (Calvin generates native files).
• Agents compile to .claude/agents/<id>.md with YAML frontmatter.
• Skills compile to .claude/skills/<id>/SKILL.md (plus supplementals).

Cursor

• Policies compile to .cursor/rules/<id>/RULE.md; apply is mapped to globs, and alwaysApply is derived.
• Skills compile to .claude/skills/<id>/SKILL.md (Cursor reads Claude's skills path).
• Agents are not supported and are skipped.

VS Code (Copilot)

• Policies compile to .github/copilot-instructions.md and/or .github/instructions/<id>.md; apply maps to applyTo.
• Skills and Agents are not supported and are skipped.

Antigravity

• Policies and actions compile to .agent/rules/ and .agent/workflows/.
• User scope: ~/.gemini/antigravity/global_rules/ and ~/.gemini/antigravity/workflows/.
• Skills and Agents are not supported and are skipped.

Codex

• Prompts compile to .codex/prompts/ (project scope) or ~/.codex/prompts/ (user scope).
• Skills compile to .codex/skills/<id>/SKILL.md (project scope) or ~/.codex/skills/<id>/SKILL.md (user scope).
• Agents are not supported and are skipped.

Validation

Calvin errors on invalid frontmatter, including:

• missing frontmatter delimiters (---)
• invalid YAML / invalid types (e.g., allowed-tools must be a list)
• missing required description
• invalid kind, scope, or targets values
• skills using unsupported fields (e.g., apply in SKILL.md)

When YAML contains : characters inside a string value, quote the string:

description: "My: Rule"

See Also

• Skills
• Library API