Skip to content

Migration Guide

This guide helps you migrate existing AI instructions to PromptScript.

Overview

PromptScript can consolidate instructions from multiple sources:

flowchart LR
    subgraph Sources["Existing Files"]
        A[".github/copilot-instructions.md"]
        B["CLAUDE.md"]
        C[".cursorrules"]
        D["Custom docs"]
    end

    subgraph PS["PromptScript"]
        E["project.prs"]
    end

    subgraph Output["Generated"]
        F[".github/copilot-instructions.md"]
        G["CLAUDE.md"]
        H[".cursorrules"]
    end

    A --> E
    B --> E
    C --> E
    D --> E
    E --> F
    E --> G
    E --> H

Step 1: Analyze Existing Instructions

Gather Current Files

Collect all existing AI instruction files:

# Common locations
cat .github/copilot-instructions.md
cat CLAUDE.md
cat .cursorrules
cat AGENTS.md
cat AI_INSTRUCTIONS.md

Identify Content Categories

Map your content to PromptScript blocks:

Content Type PromptScript Block
Identity/persona @identity
Project context @context
Coding standards @standards
Don'ts/restrictions @restrictions
Custom commands @shortcuts
Reference docs @knowledge
Configuration @params

Example Analysis

Existing CLAUDE.md:

# Project Instructions

You are a senior developer working on the checkout service.

## Tech Stack

- Node.js 20
- TypeScript
- PostgreSQL

## Standards

- Use functional programming
- Write tests for all code
- Document public APIs

## Don'ts

- Never commit secrets
- Don't use var

## Commands

/test - Run tests
/lint - Run linter

Mapped to:

  • Identity: "You are a senior developer..."
  • Context: Tech stack section
  • Standards: Standards section
  • Restrictions: Don'ts section
  • Shortcuts: Commands section

Step 2: Create PromptScript Structure

Initialize Project

prs init

Create Base Structure

# .promptscript/project.prs
@meta {
  id: "checkout-service"
  syntax: "1.0.0"
}

# Content will be added in next steps

Step 3: Migrate Content

Identity Block

You are a senior developer working on the checkout service.
Focus on clean, maintainable code.

@identity {
  """
  You are a senior developer working on the checkout service.
  Focus on clean, maintainable code.
  """
}

Context Block

## Tech Stack

- Node.js 20
- TypeScript
- PostgreSQL
- Redis for caching

@context {
  stack: {
    runtime: "Node.js 20"
    language: "TypeScript"
    database: "PostgreSQL"
    cache: "Redis"
  }

  """
  The checkout service handles payment processing
  and order management for the e-commerce platform.
  """
}

Standards Block

## Coding Standards

- Use functional programming patterns
- Write tests for all code (80% coverage)
- Document public APIs with JSDoc
- Use ESLint and Prettier

@standards {
  code: {
    style: "functional"
    testing: {
      required: true
      coverage: 80
    }
    documentation: {
      publicApi: "JSDoc"
    }
    linting: {
      eslint: true
      prettier: true
    }
  }
}

Restrictions Block

## Don'ts

- Never commit secrets or credentials
- Don't use `var`, use `const` or `let`
- Never bypass code review

@restrictions {
  - "Never commit secrets or credentials"
  - "Don't use var, use const or let"
  - "Never bypass code review"
}

Shortcuts Block

## Commands

- /test - Run the test suite
- /lint - Run ESLint
- /build - Build for production

@shortcuts {
  "/test": "Run the test suite with coverage"
  "/lint": "Run ESLint and fix issues"
  "/build": "Build for production deployment"
}

Knowledge Block

## API Reference

### Authentication

- POST /auth/login
- POST /auth/logout

### Orders

- GET /orders
- POST /orders

@knowledge {
  """
  ## API Reference

  ### Authentication
  - POST /auth/login
  - POST /auth/logout

  ### Orders
  - GET /orders - List orders
  - POST /orders - Create order
  """
}

Step 4: Complete Migration

Full Example

# Checkout Service

You are a senior developer working on the checkout service.

## Tech Stack

- Node.js 20
- TypeScript
- PostgreSQL

## Standards

- Use functional programming
- Write tests (80% coverage)
- Document public APIs

## Don'ts

- Never commit secrets
- Don't use var

## Commands

/test - Run tests
/lint - Run linter

## API Reference

### Orders

- GET /orders
- POST /orders

@meta {
  id: "checkout-service"
  syntax: "1.0.0"
}

@identity {
  """
  You are a senior developer working on the checkout service.
  """
}

@context {
  stack: {
    runtime: "Node.js 20"
    language: "TypeScript"
    database: "PostgreSQL"
  }
}

@standards {
  code: {
    style: "functional"
    testing: {
      required: true
      coverage: 80
    }
    documentation: "JSDoc for public APIs"
  }
}

@restrictions {
  - "Never commit secrets"
  - "Don't use var"
}

@shortcuts {
  "/test": "Run the test suite"
  "/lint": "Run ESLint"
}

@knowledge {
  """
  ## API Reference

  ### Orders
  - GET /orders - List orders
  - POST /orders - Create order
  """
}

Step 5: Configure and Compile

Update Configuration

# promptscript.yaml
input:
  entry: .promptscript/project.prs

targets:
  github:
    enabled: true
    output: .github/copilot-instructions.md
  claude:
    enabled: true
    output: CLAUDE.md
  cursor:
    enabled: true
    output: .cursorrules

validation:
  strict: true

Compile and Compare

# Generate new files
prs compile --dry-run

# Review changes
prs diff --all

Validate

prs validate

Step 6: Update Git

Remove Old Files from Source Control

# Keep generated files, but don't edit manually
git rm --cached .github/copilot-instructions.md CLAUDE.md .cursorrules

# Add to .gitignore if you want (optional)
# Or keep them tracked but generated

Commit Migration

git add .promptscript/ promptscript.yaml
git add .github/copilot-instructions.md CLAUDE.md .cursorrules
git commit -m "chore: migrate AI instructions to PromptScript"

Migration Patterns

Merging Multiple Sources

If you have different instructions in different files:

@meta {
  id: "my-project"
  syntax: "1.0.0"
}

# From copilot-instructions.md
@identity {
  """
  Content from GitHub Copilot instructions...
  """
}

# From CLAUDE.md
@context {
  """
  Content from Claude instructions...
  """
}

# From .cursorrules
@standards {
  # Rules from Cursor...
}

Extracting Common Patterns

If you have similar instructions across projects, extract to registry:

# registry/@company/base.prs
@meta {
  id: "@company/base"
  syntax: "1.0.0"
}

@standards {
  # Common standards...
}

@restrictions {
  # Common restrictions...
}

Then inherit:

# Project file
@inherit @company/base

@context {
  # Project-specific context
}

Handling Tool-Specific Content

Some content may be specific to certain tools:

# Most content is shared
@identity {
  """
  Shared identity...
  """
}

# Tool-specific might need adjustment
# Consider using params for variations
@params {
  tool?: enum("copilot", "claude", "cursor")
}

Advanced Block Migration

@skills Block

Skills define reusable capabilities for AI agents:

## Skills

### Code Review

When reviewing code:

1. Check for type safety
2. Verify error handling
3. Ensure tests exist

### Deployment

Steps to deploy:

1. Build the project
2. Run tests
3. Deploy to staging

@skills {
  code-review: {
    description: "Review code for quality and best practices"
    content: """
      When reviewing code:
      1. Check for type safety
      2. Verify error handling
      3. Ensure tests exist
    """
  }

  deployment: {
    description: "Deploy the application"
    steps: ["Build the project", "Run tests", "Deploy to staging"]
  }
}

@agents Block

Define specialized AI subagents:

# Code Reviewer

Reviews code for quality.

Tools: Read, Grep, Bash
Model: claude-sonnet

Instructions:
Review code checking for type safety and error handling.

@agents {
  code-reviewer: {
    description: "Reviews code for quality and best practices"
    tools: ["Read", "Grep", "Bash"]
    model: "sonnet"
    content: """
      Review code checking for:
      - Type safety
      - Error handling
      - Test coverage
    """
  }
}

@local Block

Private instructions not committed to version control:

# Local Development

- API endpoint: http://localhost:8080
- Debug mode enabled
- Use staging database

@local {
  apiEndpoint: "http://localhost:8080"
  debugMode: true

  """
  Local development notes:
  - Use staging database for testing
  - Mock external services
  """
}

@guards Block with Globs

File-specific rules using glob patterns:

---
applyTo: src/components/**/*.tsx
---

# Component Guidelines

Use functional components with TypeScript.

@guards {
  globs: ["src/components/**/*.tsx"]

  """
  Component Guidelines:
  - Use functional components
  - Include TypeScript types
  - Add unit tests
  """
}

@params Block

Configurable parameters with types:

## Configuration

- Verbosity: 1-5 (default: 3)
- Output format: json | text | markdown
- Strict mode: on/off

@params {
  verbosity: range(1..5) = 3
  format?: enum("json", "text", "markdown") = "text"
  strict: boolean = false
}

@extend Block

Modify inherited blocks at specific paths:

@inherit @company/base

# Add to existing identity
@extend identity {
  """
  Additional expertise in React development.
  """
}

# Modify nested standards
@extend standards.code.testing {
  framework: "vitest"
  coverage: 90
}

# Add to restrictions array
@extend restrictions {
  - "Use functional components only"
  - "No class-based components"
}

Validation Checklist

After migration, verify:

  • prs validate passes without errors
  • prs compile generates all targets
  • Generated files match expected content
  • No duplicate or conflicting instructions
  • All custom commands work in each tool
  • Team members can compile locally

Common Issues

Missing Metadata

Error: @meta block is required

Add required @meta block with id and syntax.

Invalid Syntax

Error: Unexpected token at line 15

Check PromptScript syntax, especially:

  • Colons after property names
  • Proper string quoting
  • Array/object brackets

Multiline Strings in Objects

Multiline strings cannot be loose inside objects:

# ❌ Invalid
@standards {
  code: {
    style: "clean"
    """
    Additional notes...
    """
  }
}

# ✅ Valid - assign to a key
@standards {
  code: {
    style: "clean"
    notes: """
      Additional notes...
    """
  }
}

Content Loss

If compiled output is missing content:

  1. Check block names are correct
  2. Verify no syntax errors in blocks
  3. Use --verbose flag for debugging

Next Steps

After migration:

  1. Set up inheritance if you have multiple projects
  2. Organize multi-file setup for complex projects
  3. Configure CI/CD for validation
  4. Train team on PromptScript workflow