README.md

@funkai/prompts

Prompt SDK for authoring .prompt files with LiquidJS templating and Zod validation.

Features

• ✏️ built-in templating — Write prompts as Liquid templates (in .prompt format) with YAML frontmatter.
• 🛡️ Zod validation — Schema variables are validated at render time.
• 📦 Codegen — Generate typed TypeScript modules from .prompt files.
• 🧩 Partials — Reusable prompt fragments with {% render %} tags, flattened at build time.
• 📁 Groups — Organize prompts into nested namespaces via the group field.

Install

npm install @funkai/prompts

Usage

Define a prompt

Create a .prompt file with YAML frontmatter and a Liquid template body:

---
name: writer
schema:
  tone: string
---
You are a {{ tone }} writer.

Generate typed modules

npx funkai prompts generate --out .prompts/client --includes "src/agents/**"

Consume prompts

Add the ~prompts alias to your tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "~prompts": ["./.prompts/client/index.ts"]
    }
  }
}

Then import and use:

import { prompts } from "~prompts";

const instructions = prompts.agents.writer.render({ tone: "concise" });

Frontmatter

Field	Required	Description
name	Yes	Unique kebab-case identifier
group	No	Namespace path for grouping
version	No	Version number
schema	No	Variable declarations (see below)

Schema variables

Each key under schema declares a template variable:

Field	Default	Description
type	string	Variable type (only string supported)
required	true	Whether the variable must be provided
description	—	Human-readable description

Shorthand: tone: string is equivalent to tone: { type: string, required: true }.

Partials

Use {% render 'name', key: 'value' %} to include shared partials. Partials resolve from:

1. Custom partials — .prompts/partials/ in your project (takes precedence)
2. Built-in partials — SDK's bundled identity, constraints, tools

Documentation

For comprehensive documentation, see the Prompts concept and Prompts CLI reference.

License

MIT