Quick Start Guide

Prerequisites

Installation

Install PrompTrek using pip:

pip install promptrek

Verify the installation:

promptrek --version

Your First Universal Prompt

1. Initialize a New Project

Create a new universal prompt file using one of our templates:

# Basic initialization with pre-commit hooks (creates v3.0 format by default)
promptrek init --setup-hooks --output my-project.promptrek.yaml

# Use a specific template with hooks (v3.0 format)
promptrek init --template react --setup-hooks --output my-react-app.promptrek.yaml
promptrek init --template api --setup-hooks --output my-api.promptrek.yaml

# Create v1 format (legacy)
promptrek init --v1 --output legacy.promptrek.yaml

# Migrate existing v1 or v2.x file to v3.0
promptrek migrate old.promptrek.yaml -o new.promptrek.yaml

💡 Tip: The --setup-hooks flag automatically configures pre-commit hooks to validate your .promptrek.yaml files and prevent accidental commits of generated files. This ensures your team maintains clean version control!

🔐 .gitignore Management: When you run promptrek init, it automatically:

This prevents generated editor files from being committed to version control. You can disable this with ignore_editor_files: false in your config.

Available templates:

Advanced Examples: PrompTrek includes 8 production-ready examples for complex projects:

See examples on GitHub

2. Customize Your Prompt

Edit the generated .promptrek.yaml file to match your project needs.

Using v3.0 Format (Recommended - Default):

schema_version: "3.0.0"

metadata:
  title: "My Project Assistant"
  description: "AI assistant for my project"
  version: "1.0.0"
  author: "Your Name <your.email@example.com>"
  tags: [web, python, react]

content: |
  # {{{ PROJECT_NAME }}} Assistant

  ## Project Details
  **Project Type:** web_application
  **Technologies:** Python, JavaScript, React

  ## Development Guidelines

  ### General Principles
  - Write clean, readable code for {{{ PROJECT_NAME }}}
  - Follow existing patterns
  - Add comprehensive documentation
  - Contact {{{ AUTHOR_EMAIL }}} for questions

  ### Code Style
  - Use meaningful variable names
  - Add appropriate comments for complex logic
  - Follow language-specific best practices

  ## Code Examples

  ### Function Example
  ```python
  def hello_world():
      """Example function with docstring."""
      return "Hello, World!"
  `` `

variables:
  PROJECT_NAME: "my-project"
  AUTHOR_EMAIL: "your.email@example.com"

Benefits of v3.0:

3. Validate Your Configuration

Before generating prompts, validate your configuration:

promptrek validate my-project.promptrek.yaml

Use --strict to treat warnings as errors:

promptrek validate my-project.promptrek.yaml --strict

💡 Editor Integration: Enable schema validation in your editor for instant feedback while editing .promptrek.yaml files. Add this comment at the top of your file:

# yaml-language-server: $schema=https://promptrek.ai/schema/v3.0.0.json
schema_version: 3.0.0
# ... rest of your configuration

This provides autocompletion, inline documentation, and validation in editors like VS Code, IntelliJ IDEA, and others that support YAML language servers. See the Schema Documentation for more details.

4. Configure .gitignore (Optional)

If you have existing editor files already committed to git, you can clean them up:

# Add patterns to .gitignore and remove committed files from git
promptrek config-ignores --remove-cached

# Preview what would be done
promptrek config-ignores --dry-run

# Use specific config file
promptrek config-ignores --config my-project.promptrek.yaml

What this command does:

You can control this behavior in your .promptrek.yaml:

# Set to false to disable automatic .gitignore management
ignore_editor_files: false

5. (Optional) Create Local Variables File

For user-specific variables like names, emails, or API keys that should NOT be committed:

# .promptrek/variables.promptrek.yaml (automatically gitignored via .promptrek/ directory)
AUTHOR_NAME: "Your Name"
AUTHOR_EMAIL: "your.email@example.com"
API_KEY: "your-secret-key"

Note: The .promptrek/ directory is automatically added to .gitignore when you run promptrek init, so all files in this directory (including variables.promptrek.yaml) will not be committed to version control.

Variables from this file override defaults in your .promptrek.yaml file. See Local Variables for details.

6. Preview Generated Output (Optional)

Preview what will be generated without creating files:

# Preview for a specific editor
promptrek preview my-project.promptrek.yaml --editor copilot

# Preview with variable overrides
promptrek preview my-project.promptrek.yaml --editor cursor \
  -V PROJECT_NAME="MyApp" \
  -V AUTHOR="Team Lead"

The preview shows:

7. Generate Editor-Specific Prompts

Now generate prompts for your preferred editors:

# Generate for a specific editor
promptrek generate --editor copilot --input my-project.promptrek.yaml

# Generate for all configured editors
promptrek generate --all --input my-project.promptrek.yaml

# Generate with custom output directory
promptrek generate --all --input my-project.promptrek.yaml --output ./ai-config

Generated Files Overview

PrompTrek generates sophisticated configuration files for each editor:

GitHub Copilot

Cursor

Continue

Kiro

Cline

Claude Code

Windsurf

Amazon Q

JetBrains AI

Example Workflow

Here’s a typical workflow using PrompTrek:

1. Project Setup

# Create a new React project prompt
promptrek init --template react --output react-app.promptrek.yaml

# Customize for your specific needs
# Edit react-app.promptrek.yaml...

# Validate the configuration
promptrek validate react-app.promptrek.yaml --strict

2. Generate Prompts

# Generate for GitHub Copilot
promptrek generate --editor copilot --input react-app.promptrek.yaml

# Team members can generate for their preferred editors
promptrek generate --editor cursor --input react-app.promptrek.yaml
promptrek generate --editor continue --input react-app.promptrek.yaml

3. Use in Your Editor

PrompTrek includes pre-commit hooks to ensure code quality and prevent accidental commits of generated files.

Setup Options

Option 1: During Initialization (Easiest)

promptrek init --setup-hooks --output project.promptrek.yaml
# ✅ Creates .promptrek.yaml
# ✅ Configures .pre-commit-config.yaml
# ✅ Activates git hooks automatically

Option 2: For Existing Projects

pip install pre-commit
promptrek install-hooks --activate

Option 3: Manual Setup

promptrek install-hooks        # Configure only
pre-commit install            # Activate manually

What the Hooks Do

  1. Validate PrompTrek files - Automatically validates .promptrek.yaml files before commit
  2. Prevent generated files - Blocks accidental commits of AI editor config files (.cursor/, .claude/, etc.)

See the Pre-commit Integration Guide for detailed documentation.

Common Commands Reference

Initialization

promptrek init --output <filename>                          # Basic init
promptrek init --template <template> --output <file>        # From template
promptrek init --setup-hooks --output <file>                # With pre-commit hooks

Pre-commit Hooks

promptrek install-hooks                    # Configure hooks
promptrek install-hooks --activate         # Configure and activate
promptrek check-generated <files>          # Check if files are generated

Validation

promptrek validate <file>           # Basic validation
promptrek validate <file> --strict  # Strict validation

Generation

promptrek generate --editor <editor> --input <file>     # Single editor
promptrek generate --all --input <file>                 # All editors
promptrek generate --all --input <file> --output <dir>  # Custom output

Synchronization

promptrek sync --editor copilot --source-dir . --output <file>  # Sync editor changes back
promptrek sync --editor continue --source-dir . --dry-run       # Preview sync changes

Information

promptrek list-editors              # Show supported editors
promptrek --help                    # General help
promptrek <command> --help          # Command-specific help

Troubleshooting

Common Issues

  1. Import errors: Make sure you installed with pip install promptrek
  2. Command not found: Check that promptrek is in your PATH
  3. Validation errors: Use promptrek validate --help for validation options

Getting Help

Next Steps

Ready to dive deeper? Check out our comprehensive User Guide!