Introduction

Prompt Deck helps you organise your AI Agents instructions as structured, version-controlled files, making it easy to iterate, compare, and activate prompt versions across your Laravel / PHP application. It provides variable interpolation, performance tracking, A/B testing, and optional seamless integration with the Laravel AI SDK.

Quick Start

Installation

composer require veeqtoh/prompt-deck

Publish the config and migrations

php artisan vendor:publish --provider="Veeqtoh\PromptDeck\Providers\PromptDeckServiceProvider"

# Run migrations.
php artisan migrate

Creating a Prompt

Use the Artisan command to create a versioned prompt

php artisan make:prompt order-summary

This creates the following structure

resources/prompts/
└── order-summary/
    ├── v1/
    │   └── system.md
    └── metadata.json

Edit resources/prompts/order-summary/v1/system.md with your prompt content. Use {{ $variable }} syntax for dynamic values:

You are a {{ $tone }} customer service agent.
Summarise the following order for the customer: {{ $order }}.

Using a Prompt

Load and render prompts with the PromptDeck facade

use Veeqtoh\PromptDeck\Facades\PromptDeck;

// Load the active version of a prompt
$prompt = PromptDeck::get('order-summary');

// Render a role with variables
$prompt->system(['tone' => 'friendly', 'order' => $orderDetails]);
// "You are a friendly customer service agent. Summarise the following order..."

// Build a messages array ready for any chat-completion API
$messages = $prompt->toMessages(['tone' => 'friendly', 'order' => $orderDetails]);
// [['role' => 'system', 'content' => '...']]

Versioning

Create a new version of an existing prompt

php artisan make:prompt order-summary
# Automatically creates v2, v3, etc.

Activate a specific version

php artisan prompt:activate order-summary v2

Or load a specific version programmatically

$prompt = PromptDeck::get('order-summary', 'v2');

Laravel AI SDK Integration

If you use the Laravel AI SDK, add the HasPromptTemplate trait to your agents. This way, you do not need to define the instructions() method as it is provided automatically.

use Veeqtoh\PromptDeck\Concerns\HasPromptTemplate;

class OrderAgent extends Agent
{
    use HasPromptTemplate;

    // instructions() and promptMessages() are provided automatically
}

Running make:agent will also auto-scaffold a matching prompt directory.

For the complete guide, see the full documentation below.

---

Documentation

Full documentation can be found on the Prompt Deck website or the docs directory on GitHub.

Contributing

Thank you for considering contributing to Prompt Deck! Please open an issue or submit a pull request on GitHub.

Code of Conduct

While we aren't affiliated with Laravel, we follow the Laravel Code of Conduct. We expect you to abide by these guidelines as well.

Security Vulnerabilities

If you discover a security vulnerability within Prompt Deck, please email Victor Ukam at victorjohnukam@gmail.com. All security vulnerabilities will be addressed promptly.

License

Prompt Deck is open-sourced software licensed under the MIT license.

Support

This library is created by Victor Ukam with contributions from the Open Source Community. If you've found this package useful, please consider sponsoring this project. It will go along way to help with maintenance.