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:

Handling Ambiguous Content¶

When content could belong to multiple blocks:

1. Prioritize by specificity - More specific blocks over general ones
2. Consider the "why" - Standards explain how, restrictions explain what not to do
3. Look at surrounding context - Headers and sections provide hints
4. Preserve intent - Keep the original meaning, even if restructured

Content Classification Priority¶

When content is unclear, use this priority order:

1. @restrictions - If it says "don't" or "never"
2. @standards - If it's a positive rule or guideline
3. @context - If it's factual project information
4. @knowledge - If it's reference documentation
5. @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

1. Discovery - Find all existing instruction files
2. Analysis - Read and categorize content in each file
3. Mapping - Map content to PromptScript blocks
4. Generation - Generate PromptScript files
5. Validation - Run prs validate
6. Comparison - Compare compiled output with original
7. Iteration - Refine until output matches expectations

File Discovery Order¶

Check files in this priority order:

1. CLAUDE.md / CLAUDE.local.md - Often most comprehensive
2. .cursorrules - Usually has coding standards
3. .github/copilot-instructions.md - Project context
4. AGENTS.md - Agent definitions
5. .github/instructions/*.md - File-specific rules
6. .cursor/rules/*.md - Additional Cursor rules

Merging Strategy¶

When combining multiple source files:

1. Identity: Use the most detailed and specific description
2. Context: Union of all technical context, deduplicate
3. Standards: Merge by category, remove exact duplicates
4. Restrictions: Include all restrictions (union)
5. 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¶

Wrong:

@standards {
  code: [
    "Use TypeScript",
    "Never use any"  # This is a restriction
  ]
}

Correct:

@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¶

• @meta block exists with id and syntax
• 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 validate passes without errors
• prs compile --dry-run produces expected output
• Compiled output matches original intent
• Each target (Claude, GitHub, Cursor) looks correct

Tool-Specific Considerations¶

Claude Code¶

• Agents should use @agents block
• Local development settings go in @local
• Use CLAUDE.local.md content for @local block

GitHub Copilot¶

• Prompts with prompt: true generate to .github/prompts/
• File-specific instructions use @guards with globs
• Instructions in .github/instructions/ map to @guards

Cursor¶

• Rules map to @standards and @restrictions
• .cursor/rules/*.mdc files have frontmatter with globs → use @guards
• Model preferences are configuration, not instructions

Iteration Tips¶

When Validation Fails¶

1. Check the error message for line numbers
2. Look for common syntax issues (missing quotes, colons, brackets)
3. Simplify the problematic section
4. Add content back incrementally

When Output Differs¶

1. Run prs compile --verbose to see processing steps
2. Check if content is in the correct block type
3. Verify block names match expected patterns
4. Look for content being filtered by guards

When Content is Missing¶

1. Verify the source content was included in a block
2. Check if the block type is supported by the target
3. Look for syntax errors that might cause parsing to stop
4. Use --dry-run to 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 staging

Result: 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