beam-ai-team/prompt-versioning

Prompt Versioning Skill

Standardized prompt management for client projects with version control, rollback, and Linear integration.

Safety Contract

Before initializing prompt storage, creating versions, changing current production prompts, rolling back, or linking Linear tickets, show the project, prompt name, target version, files/records to change, and rollback impact. Require explicit user approval in the current turn before writing files or updating Linear. Listing, reading, and diffing prompt versions do not require approval.

Overview

This skill provides a consistent way to manage AI prompts across client projects. It tracks versions, links changes to Linear tickets, and enables easy rollback when needed.

Commands

| Command | Description | |---------|-------------| | prompt init | Initialize prompt versioning in current project | | prompt create <name> | Create a new prompt | | prompt version <name> | Create new version of existing prompt | | prompt list | List all prompts and their versions | | prompt get <name> [version] | Get prompt content | | prompt diff <name> <v1> <v2> | Compare two versions | | prompt set-current <name> <version> | Set production version | | prompt rollback <name> <version> | Rollback to previous version |

Usage Examples

Initialize in a project

python prompt_init.py --project americana

Create a new prompt

python prompt_create.py --name consolidation --description "Merge email data with Airtable state"

Create a new version

python prompt_version.py --name consolidation --ticket CLI-4442 --change "Fixed dash to minus extraction"

List all prompts

python prompt_list.py

Get current production prompt

python prompt_get.py --name consolidation

Get specific version

python prompt_get.py --name consolidation --version v1

Compare versions

python prompt_diff.py --name consolidation --v1 v1 --v2 v2

Set production version

python prompt_set_current.py --name consolidation --version v2

File Structure

{project}/02-resources/prompts/
├── .prompt-config.yaml      ← Configuration and version tracking
├── REGISTRY.md              ← Auto-generated human-readable index
└── {prompt-name}/
    ├── v1.md                ← Version 1
    ├── v2.md                ← Version 2
    └── ...

Configuration

The .prompt-config.yaml file tracks all prompts and versions:

project: americana
created: 2026-01-12
prompts:
  consolidation:
    description: "Merge email data with Airtable state"
    current: v2
    beam_node_id: null
    versions:
      v1:
        date: 2026-01-05
        ticket: null
        change: "Initial version"
      v2:
        date: 2026-01-12
        ticket: CLI-4442
        change: "Added dash fix"

Integration

• Linear: Link version changes to tickets for traceability
• Beam: Optionally track which Beam node uses which prompt
• Nexus: Works with any Nexus project structure

Best Practices

1. Always create a new version before making changes
2. Link to Linear tickets for audit trail
3. Write clear change descriptions for future reference
4. Test before setting current - use prompt get to review
5. Use diff to compare before rollback