One config. Five AI tools. Zero drift.

Define once.
Deploy everywhere.

Stop maintaining five separate agent configs. Run promptosaurus init once — Promptosaurus generates production-ready configurations for Kilo, Cline, Claude, Cursor, and GitHub Copilot automatically. Switch tools or swap personas any time without starting over.

Get Started View on GitHub
5 AI Tools Kilo, Cline, Claude, Cursor, Copilot
Zero Config Auto-discovery registry
Persona Filtering Team-role aware generation
Token Efficient Minimal/verbose variants
Install: pip install promptosaurus
Core Capabilities

Everything your team needs.
Nothing you don't.

Built for engineering teams that take AI tooling seriously. Promptosaurus eliminates configuration drift and boilerplate sprawl across your AI assistant ecosystem.

Configure Once, Deploy Anywhere

A tool-agnostic configuration layer for all your agent definitions. Define Agent, Skill, Workflow, Tool, Rules, and Project models once — your setup handles translation to each tool's native format.

Unified Config Tool-Agnostic Single Source of Truth

Persona-Based Filtering

Select your team's roles — Frontend Software Engineer, Backend Software Engineer, DevOps, QA/Tester, and more — and get only the agents relevant to those personas. Universal agents (ask, debug, explain, plan, orchestrator) are always included.

Persona Filtering Role-Aware

Minimal / Verbose Variants

Every builder supports output verbosity selection at build time. Choose minimal to save tokens in context windows, or verbose for rich, self-documenting configurations. Same config — two flavors.

Token Efficiency Build Options

Auto-Discovery Registry

Zero-config agent registration. The BuilderFactory and Registry automatically discover and register builders. Configurations are stored in .promptosaurus.yaml — edit directly or use promptosaurus update for guided changes.

Zero Config Auto-Discovery

Jinja2 Template Engine

A full Jinja2-powered rendering pipeline with custom filters, resolvers, and template handlers. Builders compose templates from your config into final text — deterministic, testable, extensible output generation.

Jinja2 Custom Filters Template Handlers

Backwards Compatible

Existing configurations continue to work without modification. The Loader and Parser subsystems handle both legacy Markdown/YAML formats and the new config format — upgrade at your own pace.

Non-Breaking Markdown/YAML

CLI First

A rich CLI covers the full lifecycle: init, list, switch, swap, update, and validate. Integrate into your team's onboarding scripts or CI pipeline.

CLI Tool CI-Friendly

Validate Before You Ship

Built-in validation with promptosaurus validate checks your configuration for correctness, missing references, and schema compliance before any output is generated.

Schema Validation Pre-flight Checks
Architecture

Under the hood.
Elegantly simple.

A clean pipeline from your configuration to tool-specific output. No magic — just a well-structured transformation layer.

01

Configure Your Agents

Run promptosaurus init or edit .promptosaurus.yaml to define your agents, skills, and workflows. Store in YAML or Markdown — the loader handles both.

02

Registry Lookup

The CLI queries the central Registry for available modes, output ordering, and builder configuration. BuilderFactory instantiates the correct builder.

03

Persona Filter

If a persona is active, PersonaFilter selects only the agents relevant to that team role. Irrelevant agents are excluded from the build pass.

04

Template Render

Each Builder passes your config through Jinja2 template handlers. Custom filters and resolvers produce tool-specific syntax — YAML frontmatter, pure Markdown, or structured files.

05

Write to Disk

Builders write their outputs to the correct target locations: .kilo/agents/, .clinerules, .claude/, .github/instructions/, .cursor/rules/.

Data Flow

Live Diagram
flowchart LR A([".promptosaurus.yaml"]) --> B["Loader / Parser"] B --> C["Config loaded\n(Agent, Skill, Workflow)"] C --> D{"PersonaFilter"} D -->|active persona| E["Filtered Agent Set"] D -->|no filter| C E --> F["BuilderFactory"] C --> F F --> G1["KiloBuilder"] F --> G2["ClineBuilder"] F --> G3["ClaudeBuilder"] F --> G4["CopilotBuilder"] F --> G5["CursorBuilder"] G1 --> H1[".kilo/agents/"] G2 --> H2[".clinerules"] G3 --> H3[".claude/"] G4 --> H4[".github/instructions/"] G5 --> H5[".cursor/rules/ + .cursorrules"]

Builder Pipeline

Live Diagram
sequenceDiagram actor User participant CLI participant Registry participant Factory as BuilderFactory participant Builder participant Template as TemplateHandler participant FS as FileSystem User->>CLI: promptosaurus init CLI->>Registry: query modes & config Registry-->>CLI: builder config CLI->>Factory: create_builder(mode) Factory-->>CLI: builder instance CLI->>Builder: build(agent, BuildOptions) Builder->>Template: render(ir_model, variant) Template-->>Builder: rendered content Builder->>FS: write output files FS-->>User: tool-specific configs

Component Dependency Graph

Interactive · Drag nodes
Core Builders Unified Config CLI

Execution Lifecycle State Machine

Live Diagram
stateDiagram-v2 [*] --> Idle Idle --> Loading : promptosaurus init Loading --> Validating : Config loaded Validating --> Error : schema violation Validating --> Filtering : valid Error --> Idle : user fixes config Filtering --> Building : persona applied Building --> Writing : build() complete Writing --> Done : files written Done --> Idle : next run Building --> Error : builder exception
Supported AI Tools

One config.
Five native outputs.

Pick your AI coding assistant and Promptosaurus generates the right config files in the right format. No lowest-common-denominator compromises — each output is idiomatic to the tool it serves.

01

Kilo IDE

kilo
Supported

Generates YAML frontmatter + Markdown agent files for Kilo IDE. Run promptosaurus init and select Kilo as your target tool — files are written to the .kilo/agents/ directory automatically.

Output target:
.kilo/agents/{agent_name}.md
  • YAML frontmatter generation
  • Subagent support
  • Component selection
  • Minimal & verbose variants
Output preview
---
name: code
description: Code implementation expert
subagents:
  - test
  - review
variant: verbose
---

# Code Agent

You are a senior software engineer...
02

Cline

cline
Supported

Generates a pure Markdown .clinerules file. Select Cline during promptosaurus init and your agent configuration is rendered into Cline's natural-language rule format automatically.

Output target:
.clinerules
  • Pure Markdown output
  • use_skill invocation pattern
  • Natural language focused
  • Prose-based rules
Output preview
# Code Agent Rules

You are a code implementation expert.

When writing tests, use_skill: testing-strategies

## Conventions
Follow the project's established patterns...
03

Claude

claude
Supported

Generates the full .claude/ directory with agents, workflows, and skills as Markdown files. Select Claude during promptosaurus init to populate your entire Claude Code configuration tree.

Output target:
.claude/
  • Full .claude/ directory tree
  • Agents, workflows, skills
  • Minimal & verbose variants
  • Persona-filtered output
Output preview
.claude/
  agents/
    code.md
    debug.md
  workflows/
    code.md
  skills/
    testing-strategies.md
04

GitHub Copilot

copilot
Supported

Generates YAML frontmatter + Markdown instruction files for GitHub Copilot. Select Copilot during promptosaurus init and your agent configs are written to .github/instructions/, version-controlled alongside your code.

Output target:
.github/instructions/{agent}.md
  • GitHub-native format
  • Markdown instructions file
  • Version-controlled with repo
  • Minimal & verbose variants
Output preview
---
applyTo: "**/*.py"
---

# Code Agent

Apply these instructions when writing
Python code in this repository...
05

Cursor

cursor
Supported

Generates Markdown rules files for Cursor. Select Cursor during promptosaurus init and your configuration is written to both .cursor/rules/ and .cursorrules, keeping Cursor in sync with your AI toolchain.

Output target:
.cursor/rules/ + .cursorrules
  • Cursor rules format
  • Markdown rules output
  • Cursor-idiomatic structure
  • Minimal & verbose variants
Output preview
---
description: Code implementation
globs: ["**/*.py", "**/*.ts"]
---

# Code Agent

You are a senior software engineer.
Follow project conventions strictly...
Getting Started

Up and running
in minutes.

bash 
pip install promptosaurus

The Init Wizard

Run promptosaurus init in your project root. The interactive wizard guides you through every choice:

bash 
$ promptosaurus init

? Which AI tool do you want to configure?
  > Kilo IDE
    Cline
    Claude
    Cursor
    GitHub Copilot

? Repository type?
  > Single-language
    Multi-language monorepo

? Prompt variant?
  > Minimal (fewer tokens)
    Verbose (full documentation)

? Select personas for your team: (space to select, enter to confirm)
  [x] Backend Software Engineer
  [ ] Frontend Software Engineer
  [x] Fullstack Software Engineer
  [x] DevOps Engineer
  [ ] QA/Tester
  [ ] Data Engineer
  [ ] Security Engineer

? Primary language?
  > Python
    TypeScript
    Go
    (other)

Generating configuration for Kilo IDE...
Written: .kilo/agents/code.md
Written: .kilo/agents/debug.md
Written: .kilo/agents/backend.md
Written: .promptosaurus.yaml

Done! Your Kilo IDE configuration is ready.

CLI Command Reference

Command Description
promptosaurus init Interactive initialization — sets up your project with the chosen AI tool
promptosaurus list List all registered modes and available builders in the registry
promptosaurus switch Interactively switch the active AI assistant tool (regenerates configs)
promptosaurus swap Swap the active persona — re-filters agents for the new team role
promptosaurus update Update configuration files after editing .promptosaurus.yaml
promptosaurus validate Validate config — check for errors before committing
Examples

Real patterns.
Copy and run.

Practical CLI workflows for common Promptosaurus scenarios. All examples use the interactive wizard or CLI commands.

01

Set up for Kilo IDE — single backend engineer

Initialize Promptosaurus targeting Kilo IDE for a solo backend engineer. The wizard generates only backend-relevant agents.

bash 
pip install promptosaurus
# or: uv add promptosaurus

promptosaurus init
# ? Which AI tool? → Kilo IDE
# ? Repository type? → Single-language
# ? Prompt variant? → Verbose
# ? Personas? → Backend Software Engineer
# ? Language? → Python

# Output:
# Written: .kilo/agents/code.md
# Written: .kilo/agents/debug.md
# Written: .kilo/agents/backend.md
# Written: .promptosaurus.yaml
02

Full-stack team setup with Claude

Configure Claude for a team with multiple personas. Each selected persona adds its relevant agents to the generated .claude/ directory.

bash 
promptosaurus init
# ? Which AI tool? → Claude
# ? Repository type? → Multi-language monorepo
# ? Prompt variant? → Minimal
# ? Personas? → [x] Frontend Software Engineer
#               [x] Backend Software Engineer
#               [x] DevOps Engineer
#               [x] QA/Tester
# ? Language? → TypeScript

# Output:
# Written: .claude/agents/frontend.md
# Written: .claude/agents/backend.md
# Written: .claude/agents/devops.md
# Written: .claude/agents/qa.md
# Written: .claude/agents/debug.md   ← universal
# Written: .claude/agents/ask.md     ← universal
# Written: .promptosaurus.yaml
03

Switch to a different AI tool

Already initialized? Switch from one AI tool to another. Promptosaurus reads your existing .promptosaurus.yaml and regenerates for the new target.

bash 
# Currently configured for Kilo IDE, switching to Cursor
promptosaurus switch
# ? Which AI tool do you want to switch to?
#   > Cursor
# Regenerating for Cursor...
# Written: .cursor/rules/code.mdc
# Written: .cursor/rules/debug.mdc
# Written: .cursorrules
# Done!
04

Swap personas to regenerate for a different team

Changing team composition? Use swap to update your persona selection and regenerate agent files without re-running the full init wizard.

bash 
# Swap personas — a new team member is a Data Scientist
promptosaurus swap
# ? Update persona selection:
#   [x] Backend Software Engineer
#   [x] Data Scientist        ← newly added
#   [ ] Frontend Software Engineer
# Regenerating with updated personas...
# Done!
05

Validate your configuration

Run validate to check for missing files, unregistered orphans, and config integrity issues. Ideal as a CI gate before merging changes.

bash 
# Validate config integrity
promptosaurus validate
# Checking .promptosaurus.yaml...
# Checking registered agents...
# No issues found. Configuration is valid.

# Use as a CI step (GitHub Actions, etc.)
# - name: Validate Promptosaurus config
#   run: promptosaurus validate
Documentation

Everything documented.
Nothing hidden.

/
Collaborators

Building on
Promptosaurus.

Want to extend Promptosaurus, add a new AI tool target, or integrate it into your own tooling? Here's everything you need to contribute or build on top of the library.

Contribute on GitHub

Browse issues, submit PRs, and read the contribution guide. The codebase is structured around five builders — each one is a self-contained, testable unit.

View on GitHub →

Builder Architecture

Promptosaurus uses five internal builder classes that transform IR models into tool-specific outputs: KiloBuilder, ClineBuilder, ClaudeBuilder, CopilotBuilder, and CursorBuilder. Each implements a common build(agent, options) interface. BuilderFactory handles instantiation.

Python API (Programmatic Usage)

If you're integrating Promptosaurus into scripts or build pipelines, you can call builders directly:

from promptosaurus.builders.kilo_builder import KiloBuilder
from promptosaurus.ir.models import Agent
from promptosaurus.builders.config import BuildOptions

builder = KiloBuilder()
agent = Agent(
    name="code",
    description="Code implementation expert",
    system_prompt="You are a senior software engineer..."
)
output = builder.build(agent, BuildOptions(variant="verbose"))
# Writes to .kilo/agents/code.md

Contribution Resources