Skills

Calvin supports Skills as a directory-based asset type under .promptpack/skills/. A skill compiles to a platform-native SKILL.md folder and can include additional files (reference docs, scripts, examples).

When to Use Skills

Choose Skills when you need:

• Supporting files: reference docs, scripts, or examples alongside instructions
• Tool restrictions: explicit allowed-tools for security
• Encapsulated capability: a complete, reusable unit of functionality

Layout

.promptpack/
└── skills/
    └── <id>/
        ├── SKILL.md          # Required entrypoint (has YAML frontmatter)
        ├── reference.md      # Optional supplemental
        └── scripts/          # Optional supplemental subtree
            └── validate.py

• The skill id is the directory name (<id>).
• SKILL.md is required and must start with YAML frontmatter (---).
• All other files under the directory are treated as supplementals and are copied to outputs with the same relative paths.

SKILL.md frontmatter

SKILL.md frontmatter uses the same YAML schema as other PromptPack assets:

• Required: description
• Optional: scope, targets, allowed-tools
• Not supported for skills: apply (Calvin errors if present)

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` to summarize staged changes
2. Suggest a conventional commit message
3. If needed, consult `reference.md`

Supplemental file rules (safety)

To keep skills safe and portable, Calvin enforces:

• Valid UTF-8 for text files: text files with invalid encodings are rejected
• No symlinks: symlinks inside skill directories are rejected
• Hidden files/dirs are skipped: any .-prefixed path is ignored
• Path safety: supplemental paths cannot escape the skill directory (no ../ traversal)

Binary asset support

Binary files (images, PDFs, fonts, etc.) in skill directories are automatically detected and deployed:

.promptpack/skills/my-skill/
├── SKILL.md
├── references/
│   └── guide.md          # Text file
└── assets/
    ├── logo.png          # Binary file - deployed
    └── diagram.pdf       # Binary file - deployed

Calvin uses a null-byte heuristic to detect binary files. When a binary file is found:

1. The file is stored separately from text supplementals
2. A warning is displayed: Skill 'my-skill': binary file 'assets/logo.png' will be deployed (45.2 KB)
3. The file is deployed byte-for-byte to the target directory
4. The lockfile tracks the file with is_binary = true

Binary files are fully supported for orphan detection and cleanup (--cleanup).

Output paths

Skills compile to SKILL.md folders on supported platforms:

Multi-layer semantics (override, not merge)

Skills follow Calvin’s layer precedence rules (project > additional layers > user). When the same skills/<id>/ exists in multiple layers, the higher-priority layer fully replaces the lower-priority skill directory (no file-level merging).

Commands

• calvin deploy: compiles skills alongside policies/actions/agents.
• calvin deploy -v: shows skill structure (skill + supplemental files).
• calvin layers: shows per-layer counts for both assets and skills.
• calvin check: validates deployed skill folders and warns on dangerous allowed-tools.

See Also

• Multi-Layer PromptPacks — Share skills across projects
• Frontmatter Spec — Complete frontmatter reference
• Configuration — Configure target platforms