promptkitty

README

PromptKitty

PromptKit workflows for coding agents, the command line, and Go.

Install PromptKitty as a plugin or native Agent Skills, then describe the engineering work you want done. Its skills discover the most relevant PromptKit template, collect every required input, run interactive intake when needed, and assemble a complete prompt. They can also turn that behavior into provider-native project instructions or a subagent profile.

The same embedded catalog is available through a standalone CLI and a deterministic Go library. PromptKitty performs runtime discovery and assembly without reading external component files or contacting a service.

The embedded snapshot is PromptKit v0.6.1: 15 personas, 56 protocols, 24 formats, 5 taxonomies, 71 templates, and 4 pipelines. Every declared parameter must be resolved before assembly succeeds.

Agent skills

PromptKitty installs two complementary skills:

Skill	What it does	Result
PromptKitty Assemble	Turns a natural-language engineering task into a catalog search, template selection, required-parameter intake, and final PromptKit assembly.	A raw prompt, or a handoff for project instructions or a subagent profile.
PromptKitty Author Agent Instructions	Accepts assembled source — or asks Assemble to prepare it — and adapts the behavior to the selected agent host.	Ready-to-commit project instructions or a provider-native subagent profile.

Assemble handles both single-shot and interactive templates. Single-shot templates offer Raw prompt, Project instructions, or Subagent profile as the result. Interactive templates perform their first safe questioning and confirmation phase, fold the answers into the declared parameters, and then produce the final assembled source without executing the later task.

Author Agent Instructions resolves the provider, output type, slug, and project root; validates the provider-native file; and previews a manifest and concise diff. It requires explicit confirmation before writing anything.

Install for your agent

Run setup directly from npm; no global PromptKitty installation is required:

npx --yes @baldaworks/promptkitty@latest --version
npx --yes @baldaworks/promptkitty@latest setup codex

PromptKitty supports six agent hosts. Setup installs both skills:

Host	Setup	Assemble	Author Agent Instructions
Codex	npx --yes @baldaworks/promptkitty@latest setup codex	$promptkitty:assemble	$promptkitty:author-agent-instructions
Claude Code	npx --yes @baldaworks/promptkitty@latest setup claude	/promptkitty:assemble	/promptkitty:author-agent-instructions
Grok Build	npx --yes @baldaworks/promptkitty@latest setup grok	/promptkitty-assemble	/promptkitty-author-agent-instructions
Copilot CLI	npx --yes @baldaworks/promptkitty@latest setup copilot	/promptkitty-assemble	/promptkitty-author-agent-instructions
OpenCode	npx --yes @baldaworks/promptkitty@latest setup opencode	/promptkitty-assemble	/promptkitty-author-agent-instructions
Cursor	npx --yes @baldaworks/promptkitty@latest setup cursor	promptkitty-assemble skill	promptkitty-author-agent-instructions skill

Codex, Claude Code, Grok Build, and Copilot CLI setup use the repository's plugin marketplace. OpenCode setup writes both skills and matching commands under .opencode/; Cursor setup writes both skills under .cursor/skills/. Existing local files are preserved; use --force only when known PromptKitty assets should be replaced. Host CLIs and credentials remain external.

Use PromptKitty from Codex

Ask Assemble for an engineering artifact or workflow instead of selecting and parameterizing a template yourself:

$promptkitty:assemble Write a requirements document for deterministic offline prompt discovery.

The skill searches the embedded catalog, explains any materially different template choices, inspects the selected template, and asks only for required values that are not already available from the request or repository context. It then returns the raw assembled prompt or hands the resolved source to Author Agent Instructions when you choose a reusable result.

You can also request reusable behavior directly:

$promptkitty:author-agent-instructions Create a spec-writing subagent for Codex in this repository.

When no assembled source was supplied, the authoring skill asks Assemble to prepare it in source-only mode. It then collects the Codex target and slug, shows the proposed path and diff, validates the TOML, and waits for explicit approval before creating the subagent file.

Project instructions and subagents

Author Agent Instructions uses the pinned PromptKit author-agent-instructions template, with current provider paths supplied by PromptKitty:

Host	Project instructions	Subagent profile
Codex	AGENTS.md	.codex/agents/<name>.toml
Claude Code	.claude/rules/<name>.md	.claude/agents/<name>.md
Grok Build	.grok/rules/<name>.md	.grok/agents/<name>.md
Copilot CLI	.github/instructions/*.instructions.md	.github/agents/<name>.agent.md
OpenCode	AGENTS.md	.opencode/agents/<name>.md
Cursor	.cursor/rules/<name>.mdc	.cursor/agents/<name>.md

Project guidance is maintained inside stable PromptKitty markers, so unrelated instructions remain untouched. Existing subagent profiles require an explicit overwrite confirmation. Codex and OpenCode share one managed AGENTS.md block when both are selected.

CLI quick start

The agent skills drive this same public CLI internally. Use it directly for shell workflows, automation, or catalog exploration.

Run the CLI directly from npm without installing it:

npx --yes @baldaworks/promptkitty@latest search "write a requirements document" --type template
npx --yes @baldaworks/promptkitty@latest show author-requirements-doc --json

For repeated use, install the same native command globally from npm or with Go:

npm install --global @baldaworks/promptkitty@latest
# Or install with Go:
go install github.com/baldaworks/promptkitty/cmd/promptkitty@v0.4.2

The remaining examples use the installed promptkitty command. Assemble the selected template after supplying every declared parameter:

promptkitty assemble author-requirements-doc \
  --param project_name=PromptKitty \
  --param description='Add deterministic offline prompt discovery' \
  --param context='Go library and CLI with an embedded PromptKit catalog' \
  --param audience='Go maintainers and coding agents'

assemble writes Markdown to stdout. Use --output only when a file is wanted, --json for the complete assembly result, and repeatable --param-file, --protocol, and --taxonomy flags for multiline or additional composition inputs.

BM25 relevance search

search uses the in-memory BM25 index from vecgo. PromptKitty indexes component names, descriptions, remaining metadata, and complete Markdown bodies with weights 4 / 2 / 1 / 1.

promptkitty search "review Go code" --type template --json
promptkitty search "root cause of a memory leak bug" --type template
promptkitty search "thread safety" --type protocol

Tokenization is Unicode-aware, common query terms are suppressed, filters retain global corpus scoring, and ties use stable catalog order. Scores stay internal so the existing Component JSON contract remains unchanged.

The installed command performs search and assembly offline. npx may contact npm to acquire the package when it is not already cached; the native package then uses only the embedded catalog.

Command surface

promptkitty list [--type ...] [--category ...] [--language ...] [--json]
promptkitty search <query> [--type ...] [--json]
promptkitty show <name> [--json]
promptkitty assemble <template> [composition flags]
promptkitty setup <codex|claude|grok|copilot|opencode|cursor> [--force]

Applications that already use Cobra can mount the same command tree:

cmd := cli.NewCommand(cli.Options{Use: "promptkit"})
host.AddCommand(cmd)

The reusable cli package keeps successful output on stdout and diagnostics on stderr. The root package remains library-first and has no CLI or process dependencies.

Go library

Install the module:

go get github.com/baldaworks/promptkitty@v0.4.2

Load the embedded catalog and assemble a fully parameterized prompt:

library, err := promptkitty.New()
if err != nil {
    return err
}

result, err := library.Assemble(promptkitty.AssembleRequest{
    Template: "investigate-bug",
    Params: map[string]string{
        "problem_description": "Parser crashes on empty input",
        "code_context":        "src/parser.c",
        "environment":         "Linux amd64",
    },
})
if err != nil {
    return err
}

fmt.Println(result.Markdown)

Browse the same immutable catalog through Go:

templates := library.List(promptkitty.Filter{Type: promptkitty.ComponentTemplate})
matches := library.Search("security review", promptkitty.Filter{Type: promptkitty.ComponentTemplate})
detail, err := library.Show("review-code")
pipelines := library.Pipelines()

NewFromFS loads a compatible private catalog for tests or applications. Runtime assembly remains one-pass, deterministic, and strict about unresolved parameters.

npm distribution

Releases publish @baldaworks/promptkitty with statically linked native executables for macOS and Linux on amd64/arm64 and Windows on amd64. The CLI quick start runs this package through npx or installs it globally with npm. Omnidist builds every target with CGO_ENABLED=0. The npm launcher selects the matching binary, so users need neither Go nor CGO tooling.

Updating the PromptKit snapshot

Change only the ref field in content/upstream.json, then run:

go generate ./...

The generator resolves that ref through GitHub, downloads the archive, copies supported components and the upstream license, and rewrites the resolved commit and SHA-256 inventory. Review content, license, commit, and inventory changes together. Do not hand-edit pinned component files.

About PromptKit

Microsoft PromptKit is a composable prompt engineering library organized around personas, protocols, taxonomies, formats, templates, and pipelines. Its bootstrap workflow inspired PromptKitty's output chooser and agent-instruction authoring. PromptKitty adapts discovery, interactive intake, and parameter gathering to the stable search, show, and assemble CLI instead of reading or rewriting upstream files.

License

PromptKitty's original Go code and documentation are available under the root MIT License, copyright Alexey Samoylov.

The embedded Microsoft PromptKit content remains under Microsoft's MIT license and attribution. Its exact license copy is stored at third_party/promptkit/LICENSE; see THIRD_PARTY_NOTICES.md for provenance and third-party terms.

PromptKitty uses vecgo's Apache-2.0-licensed BM25 implementation. The exact license is stored at third_party/vecgo/LICENSE and included with statically linked npm artifacts.

Documentation

Overview

Package promptkitty provides PromptKitty's embedded PromptKit component catalog and a deterministic prompt assembler.

Index

• type AmbiguousError
  • func (e *AmbiguousError) Error() string
• type AssembleRequest
• type AssembleResult
• type Component
• type ComponentDetail
• type ComponentRef
• type ComponentType
• type Filter
• type Library
  • func New() (*Library, error)
  • func NewFromFS(fsys fs.FS, root string) (*Library, error)
  • func (l *Library) Assemble(request AssembleRequest) (AssembleResult, error)
  • func (l *Library) List(filter Filter) []Component
  • func (l *Library) Pipelines() []Pipeline
  • func (l *Library) Search(query string, filter Filter) []Component
  • func (l *Library) Show(name string) (ComponentDetail, error)
  • func (l *Library) Version() string
• type NotFoundError
  • func (e *NotFoundError) Error() string
• type ParametersError
  • func (e *ParametersError) Error() string
• type Pipeline
• type PipelineStage

Types

type AmbiguousError

type AmbiguousError struct {
	Name  string
	Types []ComponentType
}

AmbiguousError reports a name shared by more than one component type.

func (*AmbiguousError) Error

func (e *AmbiguousError) Error() string

type AssembleRequest

type AssembleRequest struct {
	Template             string
	Params               map[string]string
	Persona              string
	AdditionalProtocols  []string
	AdditionalTaxonomies []string
	// Format leaves the template default when nil, omits the format when it
	// points to an empty string, and otherwise replaces the default.
	Format *string
}

AssembleRequest selects a template, supplies every declared parameter, and optionally adjusts its component composition.

type AssembleResult

type AssembleResult struct {
	Markdown   string         `json:"markdown"`
	Template   Component      `json:"template"`
	Components []ComponentRef `json:"components"`
}

AssembleResult is a completely rendered PromptKit prompt. All declared template parameters have been substituted.

type Component

type Component struct {
	Name        string         `json:"name"`
	Type        ComponentType  `json:"type"`
	Category    string         `json:"category,omitempty"`
	Path        string         `json:"path,omitempty"`
	Description string         `json:"description,omitempty"`
	Language    string         `json:"language,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

Component is a catalog entry enriched with its Markdown frontmatter. Metadata is a defensive copy and may be inspected by future transports.

type ComponentDetail

type ComponentDetail struct {
	Component

	UsedByTemplates []string `json:"usedByTemplates,omitempty"`
}

ComponentDetail adds reverse template references to a component.

type ComponentRef

type ComponentRef struct {
	Name string        `json:"name"`
	Type ComponentType `json:"type"`
	Path string        `json:"path"`
}

ComponentRef records one component included in an assembled prompt.

type ComponentType

type ComponentType string

ComponentType identifies one PromptKit component layer.

const (
	ComponentPersona  ComponentType = "persona"
	ComponentProtocol ComponentType = "protocol"
	ComponentFormat   ComponentType = "format"
	ComponentTaxonomy ComponentType = "taxonomy"
	ComponentTemplate ComponentType = "template"
)

type Filter

type Filter struct {
	Type     ComponentType
	Category string
	Language string
}

Filter selects catalog components. Empty fields match every component.

type Library

type Library struct {
	// contains filtered or unexported fields
}

Library is an immutable PromptKit catalog and assembler.

func New

func New() (*Library, error)

New loads the pinned embedded PromptKit component library.

func NewFromFS

func NewFromFS(fsys fs.FS, root string) (*Library, error)

NewFromFS loads a PromptKit library rooted at root within fsys. It is useful for tests and callers that maintain a compatible private catalog.

func (*Library) Assemble

func (l *Library) Assemble(request AssembleRequest) (AssembleResult, error)

Assemble resolves a template and returns a fully rendered prompt. Mustache examples that are not declared template parameters are ordinary Markdown literals and are preserved verbatim.

func (*Library) List

func (l *Library) List(filter Filter) []Component

List returns matching components in stable type/category/name order.

func (*Library) Pipelines

func (l *Library) Pipelines() []Pipeline

Pipelines returns the manifest's artifact pipelines in stable name order.

func (*Library) Search

func (l *Library) Search(query string, filter Filter) []Component

Search ranks catalog components by their relevance to query, then applies filter. Search is deterministic and uses only the loaded catalog.

func (*Library) Show

func (l *Library) Show(name string) (ComponentDetail, error)

Show returns one component and the templates that reference it.

func (*Library) Version

func (l *Library) Version() string

Version returns the version declared by the embedded PromptKit manifest.

type NotFoundError

type NotFoundError struct {
	Type ComponentType
	Name string
}

NotFoundError reports a requested component that is absent from the catalog.

func (*NotFoundError) Error

func (e *NotFoundError) Error() string

type ParametersError

type ParametersError struct {
	Template string
	Missing  []string
	Unknown  []string
}

ParametersError reports missing or unknown template parameters.

func (*ParametersError) Error

func (e *ParametersError) Error() string

type Pipeline

type Pipeline struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Stages      []PipelineStage `json:"stages"`
}

Pipeline is one named sequence from the embedded PromptKit manifest.

type PipelineStage

type PipelineStage struct {
	Template string `json:"template"`
	Consumes any    `json:"consumes,omitempty"`
	Produces any    `json:"produces,omitempty"`
}

PipelineStage describes one template and its artifact contract.