diegosouzapw Migrate to PromptScript
Overview
This skill guides you through migrating existing AI instruction files to PromptScript format, creating a unified source of truth for all AI coding assistants.
Step 1: Discovery
Search for existing instruction files using these patterns:
Claude Code:
- CLAUDE.md, claude.md, CLAUDE.local.md
Cursor:
- .cursorrules
- .cursor/rules/*.md
- .cursor/rules/*.mdc
GitHub Copilot:
- .github/copilot-instructions.md
- .github/instructions/*.md
Other:
- AGENTS.md
- AI_INSTRUCTIONS.md
- AI.md
- .ai/instructions.md
Use Glob tool to find these files.
Step 2: Read and Analyze
For each discovered file:
- Read the full content using the Read tool
- Identify sections by headers (##, ###) and patterns
- Classify content type using the mapping table below
- Note any tool-specific content that may need special handling
Step 3: Content Mapping
Map source content to PromptScript blocks:
| Source Pattern | PromptScript Block |
|---|---|
| You are, persona, identity, role | @identity |
| Tech stack, languages, frameworks | @context |
| Coding standards, conventions, rules | @standards |
| Don't, Never, restrictions | @restrictions |
| Commands, shortcuts | @shortcuts |
| API docs, references, knowledge base | @knowledge |
| Parameters, config values | @params |
| File patterns, globs, applyTo | @guards |
| Skills, capabilities | @skills |
| Agents, subagents | @agents |
| Local-only settings | @local |
Step 4: Generate PromptScript
Required: @meta block
Every PromptScript file needs metadata with id and syntax fields.
Identity (persona)
Convert persona descriptions to @identity block with triple-quote string.
Context (project info)
Convert tech stack to @context block with structured properties like project, languages, frameworks.
Standards (conventions)
Convert coding standards to @standards block organized by category: code, naming, commits, etc.
Restrictions (don'ts)
Convert restrictions to @restrictions block using dash prefix for each item.
Shortcuts (commands)
Convert custom commands to @shortcuts block. Simple shortcuts use key-value format. Complex shortcuts use object format with prompt, description, and content fields.
Knowledge (references)
Convert API docs and reference material to @knowledge block using triple-quote string for rich content.
Guards (file patterns)
Convert file-specific rules to @guards block with globs array specifying file patterns.
Params (configuration)
Convert configuration parameters to @params block with type annotations: range(), enum(), boolean.
Skills (capabilities)
Convert skill definitions to @skills block with description, trigger, and content fields.
Agents (subagents)
Convert agent definitions to @agents block with description, tools, model, and content fields.
Step 5: File Organization
Simple Projects - single file structure:
- .promptscript/project.prs
- promptscript.yaml
Complex Projects - modular file structure:
- .promptscript/project.prs (main with @use imports)
- .promptscript/context.prs
- .promptscript/standards.prs
- .promptscript/restrictions.prs
- .promptscript/commands.prs
- promptscript.yaml
Step 6: Configuration
Create promptscript.yaml with:
- version: '1'
- project.id
- input.entry pointing to main .prs file
- targets for github, claude, cursor
Step 7: Validation
After generating PromptScript files:
- Validate syntax: prs validate
- Test compilation: prs compile --dry-run
- Compare output with original files
- Iterate if content is missing or incorrect
Common Patterns
Merging Multiple Sources
When instructions exist in multiple files:
- Identity: Take from most detailed source
- Standards: Merge all, deduplicate
- Restrictions: Combine all (union)
- Commands: Merge, resolve conflicts
Tool-Specific Content
Handle tool-specific content:
- GitHub prompts: Use @shortcuts with prompt: true
- Claude agents: Use @agents block
- Cursor rules: Map to @standards
- Local content: Use @local block
Preserving Formatting
Use triple-quote multiline strings for:
- Rich markdown content
- Code examples
- Complex instructions
Syntax Rules
Quick reference for PromptScript syntax:
- Strings: quoted or identifier
- Multi-line: triple quotes
- Arrays: [item1, item2] or - item prefix
- Objects: { key: value }
- Comments: # comment
- Required @meta fields: id, syntax
Quality Checklist
Before completing migration:
- @meta block has id and syntax
- Identity is clear and specific
- Standards are organized by category
- Restrictions use dash prefix (-)
- Shortcuts work in target tools
- prs validate passes
- prs compile produces correct output
- No duplicate content across blocks
Troubleshooting
Missing @meta Error
Add required metadata block at the start.
Multiline String in Object Error
Assign multiline strings to named keys, don't leave them loose inside objects.
Content Not Appearing in Output
Check block names match expected patterns and verify syntax with prs validate --verbose.