Migration Guide
This guide helps you migrate existing AI instructions to PromptScript.
Upgrading an existing PromptScript project?
This guide converts third-party instruction files into PromptScript. Existing PromptScript 1.15 projects should use Upgrade 1.15 to 1.16.
Choose a Migration Command
| Need | Command |
|---|---|
| Convert all detected project instructions | prs migrate --static --dry-run |
| Generate an AI-assisted migration prompt | prs migrate --llm |
| Convert one known file | prs import <file> --dry-run |
Upgrade existing .prs syntax | prs upgrade --dry-run |
Prefer prs migrate for project adoption. Use prs import as a lower-level
single-file tool.
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 locationscat .github/copilot-instructions.mdcat CLAUDE.mdcat .cursorrulescat AGENTS.mdcat AI_INSTRUCTIONS.mdIdentify 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 linterMapped 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 initCreate Base Structure
@meta { id: "checkout-service" syntax: "1.0.0"}
# Content will be added in next stepsStep 3: Migrate Content
Identity Block
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 cachingStandards Block
## Coding Standards
- Use functional programming patterns- Write tests for all code (80% coverage)- Document public APIs with JSDoc- Use ESLint and PrettierRestrictions Block
## Don'ts
- Never commit secrets or credentials- Don't use `var`, use `const` or `let`- Never bypass code reviewShortcuts Block
## Commands
- /test - Run the test suite- /lint - Run ESLint- /build - Build for productionKnowledge Block
## API Reference
### Authentication
- POST /auth/login- POST /auth/logout
### Orders
- GET /orders- POST /ordersStep 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: [ "Use functional programming style", "Write tests for all code (80% coverage)", "Document public APIs with JSDoc" ]}
@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
id: my-projectsyntax: '1.4.0'
input: entry: .promptscript/project.prs
targets: - github: output: .github/copilot-instructions.md - claude: output: CLAUDE.md - cursor: output: .cursor/rules/project.mdcCompile and Compare
Before PromptScript takes ownership of existing instruction files, create a recoverable baseline. Tracked files are recoverable from the migration branch. Back up any untracked or ignored instruction files outside configured output paths, or copy them into a local migration-backup directory that will not be committed.
# Confirm every planned output and ownership conflict.prs compile --dry-run
# Compare complete planned output with existing files.prs diff --all --fullReview source parity, target-specific omissions, file modes, and every conflict path. Do not delete an existing configured target merely to bypass ownership protection. When all planned outputs and backups are approved, perform one controlled takeover:
prs validate --strictprs compile --forcegit diff -- .prs diff --all --fullThe final PromptScript diff must be empty. The Git diff must contain only approved generated replacements and migration source or configuration. Restore from version control or backup if the result loses user-owned content.
Step 6: Update Git
Keep Generated Files Tracked
git add .promptscript/ promptscript.yamlgit add .github/copilot-instructions.md CLAUDE.md .cursor/rules/project.mdcgit commit -m "chore: migrate AI instructions to PromptScript"This lets CI detect drift between PromptScript sources and generated outputs. If your team prefers to generate outputs locally, adopt one consistent ignored-output workflow only after the controlled compile above has created and verified every configured target:
printf '%s\n' \ '.github/copilot-instructions.md' \ 'CLAUDE.md' \ '.cursor/rules/project.mdc' >> .gitignoregit rm --cached .github/copilot-instructions.md CLAUDE.md .cursor/rules/project.mdcgit add .gitignore .promptscript/ promptscript.yamlgit commit -m "chore: migrate AI instructions to PromptScript"git rm --cached stops tracking these files but keeps the verified working-tree
copies. It is not a workaround for overwrite conflicts and must not run before
the takeover review.
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 safety2. Verify error handling3. Ensure tests exist
### Deployment
Steps to deploy:
1. Build the project2. Run tests3. 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" content: """ Deployment process: 1. Build the project 2. Run tests 3. Deploy to staging """ }}@agents Block
Define specialized AI subagents:
# Code Reviewer
Reviews code for quality.
Tools: Read, Grep, BashModel: claude-sonnet
Instructions:Review code checking for type safety and error handling.@local Block
Private instructions not committed to version control:
# Local Development
- API endpoint: http://localhost:8080- Debug mode enabled- Use staging database@guards Block with Globs
File-specific rules using glob patterns:
---applyTo: src/components/**/*.tsx---
# Component Guidelines
Use functional components with TypeScript.@guards Named Entries
For projects with multiple .github/instructions/*.instructions.md files — each with different applyTo patterns — use named entries in @guards to preserve the one-file-per-rule-set structure:
---applyTo: apps/admin/**/*.ts---
# Angular Component Standards
Use OnPush change detection for all components.Always implement OnDestroy for cleanup.Each named entry generates a separate .github/instructions/<name>.instructions.md file with the corresponding applyTo frontmatter. This is the recommended approach when migrating multiple instruction files — prs import can detect and convert these files automatically.
@params Block
Configurable parameters with types:
## Configuration
- Verbosity: 1-5 (default: 3)- Output format: json | text | markdown- Strict mode: on/off@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"}Choose modification syntax by migration intent:
- Keep
@extendwhen old and new values should merge or append. - Keep
field!as a compatibility form for replacing one direct regular field inside@extend. - Use
@overridewith syntax1.5.0when one complete existing block or nested value must replace the previous value.
@meta { id: "migrated-project" syntax: "1.5.0" }
@standards { testing: ["Use Jest", "Use Mocha"]}
@override standards.testing { ["Use Vitest"]}Unlike field!, @override requires the complete target path to exist. It
cannot bypass sealed skill properties.
Validation Checklist
After migration, verify:
-
prs validatepasses without errors -
prs compilegenerates 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 requiredAdd required @meta block with id and syntax.
Invalid Syntax
Error: Unexpected token at line 15Check 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:
- Check block names are correct
- Verify no syntax errors in blocks
- Use
--verboseflag for debugging
AI-Assisted Migration
For automated migration using AI assistants, PromptScript installs its bundled promptscript
skill, which includes migration guidance.
Using the PromptScript Skill
Claude Code:
# Use the PromptScript skill/promptscript
# Or ask directly"migrate my existing instructions to PromptScript"GitHub Copilot:
Ask Chat to use the promptscript skill and migrate the existing instruction files.
Cursor:
Use Composer with migration context or reference the PromptScript migration documentation.
What the AI Will Do
- Discover existing instruction files (CLAUDE.md, .cursorrules, copilot-instructions.md)
- Analyze content and classify into PromptScript blocks
- Generate properly structured PromptScript files
- Validate the output with
prs validate
Best Practices for AI Migration
For detailed guidelines on AI-assisted migration, including content mapping patterns and common pitfalls, see AI Migration Best Practices.
Next Steps
After migration:
- Set up inheritance if you have multiple projects
- Organize multi-file setup for complex projects
- Configure CI/CD for validation
- Train team on PromptScript workflow