The Kiro CLI provides comprehensive prompt management capabilities for both local prompts and Model Context Protocol (MCP) prompts. This system allows you to create, edit, organize, and use reusable prompts across your development workflow.
The prompt system supports three types of prompts:
- Local prompts: Project-specific prompts stored in your workspace
- Global prompts: User-wide prompts available across all projects
- MCP prompts: Prompts provided by MCP servers with enhanced functionality
All prompt management is accessed through the /prompts command with various subcommands.
/prompts list
Displays all available prompts in a three-column layout showing names, descriptions, and sources. Shows prompt counts and indicates which prompts come from local storage, global storage, or MCP servers.
/prompts create --name name [--content content]
Creates a new local prompt in the current workspace.
name (required)
: Prompt name (maximum 50 characters)
--content content (optional)
: Direct content specification
Behavior:
- If
--contentis provided, creates prompt with specified content - If no content provided, opens your default editor for content creation
- Prompts are saved to
.kiro/prompts/in the current workspace
/prompts edit name
Opens an existing prompt in your default editor for modification.
Supported prompts:
- Local workspace prompts
- Global user prompts
- MCP prompts (where supported by the server)
/prompts details name
Shows comprehensive information about a prompt including:
- Metadata and argument details
- Complete prompt content before AI processing
- Parameter requirements and examples
- Source information (local, global, or MCP server)
In V3, workspace, global, and MCP prompts appear in slash-command completion. Type / and select a prompt, or invoke it directly:
/prompt-name [arguments]
Completion shows the prompt's argument hints. Kiro resolves the file template or requests the MCP prompt content before sending the expanded text to the model. Other CLI engines continue to support the @prompt-name form.
In addition to prompts, you can use the @ syntax to reference files and directories directly in your messages. Kiro will automatically expand these references to include the content or structure in your conversation.
Basic Syntax:
# Include file contents > Review @src/auth.rs for security issues # Include directory tree > What's the structure of @crates/agent/? # Quoted paths for spaces > Check @"my file.txt" for errors # Relative paths > Compare @./v1/api.rs with @./v2/api.rs
Features:
- Tab completion - Press Tab after
@to auto-complete file and directory paths - Syntax highlighting - References highlighted in purple for visibility
- Automatic formatting - Files displayed as code blocks, directories as tree listings
- Smart prioritization - Known prompts take precedence over file paths
Size Limits:
- Files: 250KB maximum (larger files truncated with warning)
- Directories: 3 levels deep, 10 items per level maximum
- Binary files not supported (shows error message)
Priority Rules:
When you use @name, Kiro checks in this order:
- Known prompts - If
@namematches a prompt (local, global, or MCP), it's treated as a prompt - Files - Otherwise checked as a file path
- Directories - If not a file, checked as a directory
This means your prompts always take precedence over files with the same name.
Limitations:
- No glob patterns (
@*.rswon't work) - No line range syntax (
@file.rs:10-20won't work) - No home directory expansion (
@~won't work) - Binary files not supported
- Files without read permission show errors
/code-review # Uses your local code-review prompt in V3 @src/auth.rs # Includes the contents of src/auth.rs file @crates/agent/ # Shows the directory structure of crates/agent/
MCP prompts can declare required and optional arguments. V3 file prompts can interpolate positional arguments with ${1} through ${10}, all arguments with $ARGUMENTS, or the same full argument string with ${@}.
/prompt-name <required-arg> [optional-arg]
Use /prompts details prompt-name to inspect an MCP prompt's declared arguments. Slash-command completion shows the same hints.
# Examples: V3 prompts with arguments /analyze "performance issue" "detailed" /scan "web-app" "high-severity"
- Location:
project/.kiro/prompts/ - Scope: Available only within the current project
- Priority: Highest (overrides global and MCP prompts with same name)
- Location:
~/.kiro/prompts/ - Scope: Available across all projects
- Priority: Medium (overrides MCP prompts with same name)
- Source: Provided by configured MCP servers
- Scope: Depends on server configuration
- Priority: Lowest (overridden by local and global prompts)
When multiple prompts have the same name, the system uses this priority order:
- Local prompts (highest priority)
- Global prompts
- MCP prompts (lowest priority)
This allows you to override MCP or global prompts with project-specific versions when needed.
The system displays the complete prompt content before sending it to the AI model, eliminating confusion about what information was actually processed.
- MCP server errors are converted to user-friendly messages
- Helpful usage examples are generated from prompt metadata
- Clear guidance for invalid parameters or missing requirements
- Consistent terminal styling across all prompt operations
- Proper content display for all prompt message types
- Three-column layout for improved readability in listings
The prompt system seamlessly integrates with MCP servers:
- Automatic discovery: MCP prompts are automatically discovered from configured servers
- Enhanced UX: Improved user experience for MCP prompt management
- Error translation: Raw JSON errors are converted to actionable messages
- Content preview: Full content preview for MCP prompts before execution
These examples demonstrate file-based prompt creation and MCP prompt usage.
# Create a simple prompt without arguments /prompts create --name code-review --content "Please review this code for best practices, security issues, and potential improvements:" # Use the prompt in V3 /code-review
# Using MCP prompts with arguments /analyze "performance bottleneck" "cpu usage" /scan "web-app" "high-severity" /deploy "my-service" "production" "us-west-2"
Manage prompts