AWS amazonq documentation change
Summary
Expanded documentation on prompt arguments including syntax, validation, error handling, and examples. Added sections for working with arguments, creating parameterized prompts, and server-specific implementations.
Security assessment
The changes primarily focus on improving documentation for prompt argument handling and usage patterns. While there are examples mentioning security contexts (e.g., '@code-review "security focus"'), these demonstrate existing functionality rather than addressing specific vulnerabilities. No concrete evidence of security fixes or vulnerability mitigations is present in the diff.
Diff
diff --git a/amazonq/latest/qdeveloper-ug/command-line-prompts.md b/amazonq/latest/qdeveloper-ug/command-line-prompts.md index 48fe36eb9..5e0a2d0d8 100644 --- a//amazonq/latest/qdeveloper-ug/command-line-prompts.md +++ b//amazonq/latest/qdeveloper-ug/command-line-prompts.md @@ -5 +5 @@ -OverviewCommandsUsing promptsStorage locationsPriority systemEnhanced featuresMCP integrationExamples +About prompt typesCommandsUsing promptsWorking with prompt argumentsCreating prompts with argumentsStorage locationsPriority systemEnhanced featuresMCP integrationComprehensive examples @@ -7 +7 @@ OverviewCommandsUsing promptsStorage locationsPriority systemEnhanced featuresMC -# Prompt management +# Manage prompts @@ -11 +11 @@ The Amazon Q Developer CLI provides comprehensive prompt management capabilities -## Overview +## About prompt types @@ -38 +38 @@ Displays all available prompts in a three-column layout showing names, descripti - /prompts create name [--content content] + /prompts create --name name [--content content] @@ -122,0 +123,191 @@ For prompts that accept arguments: +## Working with prompt arguments + +Many prompts accept arguments to customize their behavior. Understanding how to discover, provide, and troubleshoot prompt arguments is essential for effective prompt usage. + +### Argument syntax + +Prompt arguments follow a simple positional syntax: + + + @prompt-name <required-arg> [optional-arg] + +###### Argument conventions + +`<required-arg>` + + +Arguments that must be provided + +`[optional-arg]` + + +Arguments that can be omitted + +`"quoted arguments"` + + +Use quotes for arguments containing spaces + +#### Quoting and special characters + + + # Arguments with spaces require quotes + @debug-help "connection timeout error" + + # Multiple word arguments + @code-review "src/main.py" "security review" + + # Single quotes also work + @generate-docs 'API Reference' 'markdown' + + # Mix quoted and unquoted arguments + @analyze-logs error "last 24 hours" --verbose + +### Discovering prompt arguments + +Use the `/prompts details` command to see what arguments a prompt accepts: + + + /prompts details prompt-name + +This shows: + + * Required and optional arguments + + * Argument descriptions and purposes + + * Usage examples with proper syntax + + * Validation requirements + + + + +#### Example: Discovering arguments + + + /prompts details code-review + + # Output: + # Name: code-review + # Server: development-tools + # + # Usage: @code-review <file-path> [review-type] + # + # Arguments: + # (required) file-path - Path to the file to review + # (optional) review-type - Type of review (security, performance, style) + +### Argument validation and errors + +The CLI validates prompt arguments and provides helpful error messages: + +#### Missing required arguments + + + # Calling prompt without required arguments + @code-review + + # Error output: + # Error: Missing required arguments for prompt code-review + # Usage: @code-review <file-path> [review-type] + # Arguments: + # (required) file-path - Path to the file to review + # (optional) review-type - Type of review (security, performance, style) + +#### Invalid argument values + + + # Providing invalid argument values + @validate-email "not-an-email" + + # Error output: + # Error: Invalid arguments for prompt validate-email: + # - email: Must be a valid email ending in .com + # Use '/prompts details validate-email' for usage information. + +### Server-specific prompts + +When multiple MCP servers provide prompts with the same name, specify the server: + + + # Ambiguous prompt error + @analyze + + # Error: Prompt analyze is ambiguous. Use one of the following: + # - @dev-tools/analyze + # - @security-tools/analyze + + # Use server-specific syntax + @dev-tools/analyze "performance issues" + @security-tools/analyze "vulnerability scan" + +## Creating prompts with arguments + +You can create both file-based and MCP prompts that accept arguments for dynamic content generation. + +### File-based prompts with arguments + +File-based prompts (local and global) receive arguments as contextual information when invoked. The arguments are provided to the AI model along with the prompt content, but file-based prompts do not have built-in templating or argument substitution. + +#### Example: Creating a parameterized prompt + + + # Create a code review prompt + /prompts create --name code-review --content "Please review this code for best practices, security issues, and potential improvements. Pay special attention to the specific aspects mentioned in the arguments." + + # Usage with arguments + @code-review "src/auth.py" "security focus" + # The AI receives both the prompt content and the arguments as context + +**Note:** File-based prompts pass arguments as additional context to the AI model. The model interprets how to use the arguments based on the prompt content and the provided argument values. + +### MCP prompt arguments + +MCP servers can define structured argument schemas with validation, descriptions, and type information. These provide the richest argument experience with automatic validation and help text. + +#### Understanding MCP argument schemas + +MCP prompts define arguments with: + + * **Name** : The argument identifier + + * **Description** : What the argument is for + + * **Required** : Whether the argument is mandatory + + * **Validation** : Rules for valid values + + + + + + # Example MCP prompt schema (shown via /prompts details) + /prompts details aws-troubleshoot + + # Output: + # Name: aws-troubleshoot + # Server: aws-tools + # + # Usage: @aws-troubleshoot <service> <error-message> [region] + # + # Arguments: + # (required) service - AWS service name (e.g., ec2, s3, lambda) + # (required) error-message - The error message you're seeing + # (optional) region - AWS region (defaults to us-east-1) + +### Best practices for prompt arguments + + * **Use descriptive names** : `file-path` instead of `f` + + * **Provide clear descriptions** : Explain what each argument does + + * **Make optional arguments truly optional** : Provide sensible defaults