AI Migration Best Practices
This guide provides best practices for AI models performing automated migration from existing AI instruction files (CLAUDE.md, .cursorrules, copilot-instructions.md) to PromptScript format.
Content Analysis Principles
Recognizing Block Types
When analyzing source content, use these patterns to classify into PromptScript blocks:
| Pattern | Indicators | PromptScript Block |
|---|---|---|
| Identity | “You are”, “Act as”, role descriptions | @identity |
| Context | Tech stack, languages, “uses”, “built with” | @context |
| Standards | “Always”, “Should”, “Best practice”, coding rules | @standards |
| Restrictions | “Don’t”, “Never”, “Avoid”, “Must not” | @restrictions |
| Commands | /command, “Shortcut:”, command definitions | @shortcuts |
| Knowledge | API docs, references, “Documentation:” | @knowledge |
| Parameters | Config values, settings, variables | @params |
| Guards | File globs, “applyTo:”, path patterns | @guards |
Handling Ambiguous Content
When content could belong to multiple blocks:
- Prioritize by specificity - More specific blocks over general ones
- Consider the “why” - Standards explain how, restrictions explain what not to do
- Look at surrounding context - Headers and sections provide hints
- Preserve intent - Keep the original meaning, even if restructured
Content Classification Priority
When content is unclear, use this priority order:
@restrictions- If it says “don’t” or “never”@standards- If it’s a positive rule or guideline@context- If it’s factual project information@knowledge- If it’s reference documentation@identity- If it describes the AI’s role or behavior
Syntax Patterns
Multi-line Strings
Use triple quotes for any content with:
- Line breaks
- Markdown formatting
- Code examples
- Multiple paragraphs
@identity { """ You are a senior TypeScript developer.
Your focus areas: - Clean code - Type safety - Testing """}Standards Organization
Group standards by category for clarity:
@standards { code: [ "Use functional programming patterns", "Write pure functions when possible" ] testing: [ "Write tests for all public functions", "Use AAA pattern (Arrange, Act, Assert)" ] documentation: [ "Document public APIs with JSDoc", "Keep README up to date" ]}Restrictions Format
Always use dash prefix for restrictions:
@restrictions { - "Never commit secrets or credentials" - "Don't use any type in TypeScript" - "Avoid default exports"}Shortcuts Complexity Levels
Simple shortcuts - Single action or description:
@shortcuts { "/test": "Run the test suite" "/build": "Build for production"}Complex shortcuts - With detailed instructions:
@shortcuts { "/review": { prompt: true description: "Perform code review" content: """ Review the code for: 1. Type safety issues 2. Error handling gaps 3. Security vulnerabilities 4. Performance concerns """ }}Migration Workflow
Recommended Sequence
Discovery → Analysis → Mapping → Generation → Validation → Comparison → Iteration- Discovery - Find all existing instruction files
- Analysis - Read and categorize content in each file
- Mapping - Map content to PromptScript blocks
- Generation - Generate PromptScript files
- Validation - Run
prs validate - Comparison - Compare compiled output with original
- Iteration - Refine until output matches expectations
File Discovery Order
Check files in this priority order:
CLAUDE.md/CLAUDE.local.md- Often most comprehensive.cursorrules- Usually has coding standards.github/copilot-instructions.md- Project contextAGENTS.md- Agent definitions.github/instructions/*.md- File-specific rules.cursor/rules/*.md- Additional Cursor rules
Merging Strategy
When combining multiple source files:
- Identity: Use the most detailed and specific description
- Context: Union of all technical context, deduplicate
- Standards: Merge by category, remove exact duplicates
- Restrictions: Include all restrictions (union)
- Shortcuts: Merge, use longer description for conflicts
Common Mistakes to Avoid
Missing @meta Block
Wrong:
@identity { """ You are a developer... """}Correct:
@meta { id: "project-name" syntax: "1.0.0"}
@identity { """ You are a developer... """}Loose Multi-line Strings in Objects
Wrong:
@standards { code: { style: "functional" """ Additional notes about the style... """ }}Correct:
@standards { code: { style: "functional" notes: """ Additional notes about the style... """ }}Mixing Block Concerns
Avoid:
This compiles, but it mixes a restriction into the standards block. Keep
restrictions in @restrictions so migrations preserve intent across targets.
@standards { code: [ "Use TypeScript", "Never use any" # This is a restriction ]}Preferred:
@standards { code: [ "Use TypeScript" ]}
@restrictions { - "Never use any type"}Forgetting Commas in Arrays
Wrong:
@context { languages: [typescript python ruby]}Correct:
@context { languages: [typescript, python, ruby]}Quality Checklist
Before completing a migration, verify:
Structure
-
@metablock exists withidandsyntax - Blocks are in logical order (meta, inherit, use, identity, context, …)
- No duplicate blocks of the same type
Content
- Identity clearly describes the AI’s role
- Standards are organized by category
- All restrictions from source are preserved
- Commands/shortcuts work as expected
- No content was lost in migration
Syntax
- All strings properly quoted
- Multi-line strings use
""" - Arrays use proper syntax
- No loose multi-line strings in objects
Validation
-
prs validatepasses without errors -
prs compile --dry-runproduces expected output - Compiled output matches original intent
- Each target (Claude, GitHub, Cursor) looks correct
Tool-Specific Considerations
Claude Code
- Agents should use
@agentsblock - Local development settings go in
@local - Use
CLAUDE.local.mdcontent for@localblock
GitHub Copilot
- Prompts with
prompt: truegenerate to.github/prompts/ - File-specific instructions use
@guardswith globs - Instructions in
.github/instructions/map to@guards
Migrating .github/instructions/*.instructions.md Files
Files in .github/instructions/ with applyTo frontmatter should be migrated using @guards named entries, not @standards or @context. Each instruction file becomes a named entry under @guards:
@meta { id: "copilot-instructions-migration" syntax: "1.0.0" }
@guards { angular-components: { applyTo: ["apps/admin/**/*.ts", "apps/webview/**/*.ts"] description: "Angular component coding standards" content: """ Use OnPush change detection for all components. Always implement OnDestroy for cleanup. """ }}prs migrate --static discovers project instruction files and converts
.github/instructions/*.instructions.md files with applyTo frontmatter to named @guards
entries. Review the generated files before compilation.
Cursor
- Rules map to
@standardsand@restrictions .cursor/rules/*.mdcfiles have frontmatter with globs → use@guards- Model preferences are configuration, not instructions
Iteration Tips
When Validation Fails
- Check the error message for line numbers
- Look for common syntax issues (missing quotes, colons, brackets)
- Simplify the problematic section
- Add content back incrementally
When Output Differs
- Run
prs compile --verboseto see processing steps - Check if content is in the correct block type
- Verify block names match expected patterns
- Look for content being filtered by guards
When Content is Missing
- Verify the source content was included in a block
- Check if the block type is supported by the target
- Look for syntax errors that might cause parsing to stop
- Use
--dry-runto see what would be generated
Example Migration
Source: CLAUDE.md
# Project
You are a senior engineer working on the API service.
## Stack
- Python 3.11- FastAPI- PostgreSQL
## Rules
- Write type hints for all functions- Use async/await for I/O
## Don'ts
- Don't commit .env files- Never store passwords in plain text
## Commands
/test - Run pytest/deploy - Deploy to stagingResult: project.prs
@meta { id: "api-service" syntax: "1.0.0"}
@identity { """ You are a senior engineer working on the API service. """}
@context { languages: [python] runtime: "Python 3.11" frameworks: [fastapi] database: "PostgreSQL"}
@standards { code: [ "Write type hints for all functions", "Use async/await for I/O operations" ]}
@restrictions { - "Don't commit .env files" - "Never store passwords in plain text"}
@shortcuts { "/test": "Run pytest test suite" "/deploy": "Deploy to staging environment"}See Also
- Migration Guide - Step-by-step migration instructions
- Language Reference - Complete syntax reference
- Multi-File Organization - Organizing complex projects