YAML Front Matter
YAML front matter is the metadata section at the beginning of each prompt file. It defines the prompt’s properties, arguments, and other configuration details.
Structure
Front matter appears between triple dashes (---
) at the start of your markdown file:
---
name: my-prompt
title: My Prompt
description: What this prompt does
---
# Prompt content starts here
Required Fields
Every prompt must have these fields:
name
- Type: String
- Description: Unique identifier for the prompt
- Format: kebab-case recommended
- Example:
code-review
,debug-helper
,api-docs
name: code-review
title
- Type: String
- Description: Human-readable name displayed in UIs
- Format: Title Case
- Example:
Code Review Assistant
,Debug Helper
title: Code Review Assistant
description
- Type: String
- Description: Brief explanation of what the prompt does
- Format: Sentence or short paragraph
- Example: Clear, actionable description
description: Reviews code for best practices, bugs, and potential improvements
Optional Fields
category
- Type: String
- Description: Groups related prompts together
- Common Values:
development
,writing
,analysis
,productivity
category: development
tags
- Type: Array of strings
- Description: Keywords for discovery and filtering
- Format: Lowercase, descriptive terms
tags: ["python", "debugging", "error-handling"]
arguments
- Type: Array of argument objects
- Description: Input parameters the prompt accepts
- See: Arguments section below
arguments:
- name: code
description: Code to review
required: true
author
- Type: String
- Description: Creator of the prompt
- Format: Name or organization
author: SwissArmyHammer Team
version
- Type: String
- Description: Version number for tracking changes
- Format: Semantic versioning recommended
version: 1.2.0
license
- Type: String
- Description: License for the prompt
- Common Values:
MIT
,Apache-2.0
,GPL-3.0
license: MIT
created
- Type: Date string
- Description: When the prompt was created
- Format: ISO 8601 date
created: 2024-01-15
updated
- Type: Date string
- Description: Last modification date
- Format: ISO 8601 date
updated: 2024-03-20
keywords
- Type: Array of strings
- Description: Alternative to tags for SEO/discovery
- Note: Similar to tags but more formal
keywords: ["code quality", "static analysis", "best practices"]
Arguments
Arguments define the inputs your prompt can accept. Each argument is an object with these properties:
Argument Properties
name
(required)
- Type: String
- Description: Parameter name used in template
- Format: snake_case or kebab-case
- Usage: Referenced as
{{name}}
in template
arguments:
- name: source_code
# Used as {{source_code}} in template
description
(required)
- Type: String
- Description: What this argument is for
- Format: Clear, helpful explanation
arguments:
- name: language
description: Programming language of the code
required
(optional, default: false)
- Type: Boolean
- Description: Whether this argument must be provided
- Default:
false
arguments:
- name: code
description: Code to analyze
required: true # Must be provided
- name: style_guide
description: Coding style to follow
required: false # Optional
default
(optional)
- Type: String
- Description: Default value if not provided
- Note: Only used when
required: false
arguments:
- name: format
description: Output format
required: false
default: markdown
type_hint
(optional)
- Type: String
- Description: Expected data type (documentation only)
- Common Values:
string
,integer
,boolean
,array
,object
arguments:
- name: max_length
description: Maximum output length
required: false
default: 500
type_hint: integer
Argument Examples
Simple Text Input
arguments:
- name: text
description: Text to process
required: true
type_hint: string
Optional with Default
arguments:
- name: format
description: Output format (markdown, json, html)
required: false
default: markdown
type_hint: string
Boolean Flag
arguments:
- name: include_examples
description: Include code examples in output
required: false
default: true
type_hint: boolean
Multiple Arguments
arguments:
- name: code
description: Source code to review
required: true
type_hint: string
- name: language
description: Programming language
required: false
default: auto-detect
type_hint: string
- name: severity
description: Minimum issue severity to report
required: false
default: medium
type_hint: string
- name: include_suggestions
description: Include improvement suggestions
required: false
default: true
type_hint: boolean
Complete Example
Here’s a comprehensive example showing all available fields:
---
name: comprehensive-code-review
title: Comprehensive Code Review Assistant
description: Performs detailed code review focusing on best practices, security, and performance
category: development
tags: ["code-review", "security", "performance", "best-practices"]
author: SwissArmyHammer Team
version: 2.1.0
license: MIT
created: 2024-01-15
updated: 2024-03-20
keywords: ["static analysis", "code quality", "security audit"]
arguments:
- name: code
description: Source code to review
required: true
type_hint: string
- name: language
description: Programming language (python, javascript, rust, etc.)
required: false
default: auto-detect
type_hint: string
- name: focus_areas
description: Specific areas to focus on (security, performance, style)
required: false
default: all
type_hint: string
- name: severity_threshold
description: Minimum severity level to report (low, medium, high)
required: false
default: medium
type_hint: string
- name: include_examples
description: Include code examples in suggestions
required: false
default: true
type_hint: boolean
- name: max_suggestions
description: Maximum number of suggestions to provide
required: false
default: 10
type_hint: integer
---
# Comprehensive Code Review
I'll perform a detailed review of your {{language}} code, focusing on {{focus_areas}}.
## Code Analysis
```{{code}}```
## Review Criteria
I'll evaluate the code for:
{% if focus_areas contains "security" or focus_areas == "all" %}
- **Security vulnerabilities** and best practices
{% endif %}
{% if focus_areas contains "performance" or focus_areas == "all" %}
- **Performance optimizations** and efficiency
{% endif %}
{% if focus_areas contains "style" or focus_areas == "all" %}
- **Code style** and formatting consistency
{% endif %}
{% if language != "auto-detect" %}
- **{{language | capitalize}}-specific** best practices and idioms
{% endif %}
## Reporting
- Minimum severity: {{severity_threshold}}
- Maximum suggestions: {{max_suggestions}}
{% if include_examples %}
- Including code examples and fixes
{% endif %}
Please provide detailed feedback with specific line references where applicable.
Validation Rules
SwissArmyHammer validates your YAML front matter:
Required Field Validation
name
,title
, anddescription
must be presentname
must be unique within the prompt libraryname
must not contain spaces or special characters
Argument Validation
- Each argument must have
name
anddescription
- Argument names must be valid template variables
- Required arguments cannot have default values
- Argument names must be unique within the prompt
Type Validation
- Arrays must contain valid elements
- Dates must be in ISO format
- Booleans must be
true
orfalse
Best Practices
1. Use Descriptive Names
# Good
name: python-code-review
title: Python Code Review Assistant
# Bad
name: review
title: Review
2. Write Clear Descriptions
# Good
description: Analyzes Python code for PEP 8 compliance, type hints, security issues, and performance optimizations
# Bad
description: Reviews code
3. Organize with Categories and Tags
category: development
tags: ["python", "pep8", "security", "performance", "code-quality"]
4. Provide Sensible Defaults
arguments:
- name: style_guide
description: Python style guide to follow
required: false
default: PEP 8 # Most common choice
5. Use Type Hints
arguments:
- name: max_issues
description: Maximum number of issues to report
required: false
default: 20
type_hint: integer # Helps users understand expected format
6. Keep Versions Updated
version: 1.2.0 # Update when you make changes
updated: 2024-03-20 # Track modification date
Common Patterns
Code Processing Prompt
---
name: code-processor
title: Code Processor
description: Processes and transforms code
category: development
arguments:
- name: code
description: Source code to process
required: true
- name: language
description: Programming language
required: false
default: auto-detect
- name: output_format
description: Desired output format
required: false
default: markdown
---
Text Analysis Prompt
---
name: text-analyzer
title: Text Analyzer
description: Analyzes text for various metrics
category: analysis
arguments:
- name: text
description: Text to analyze
required: true
- name: analysis_type
description: Type of analysis to perform
required: false
default: comprehensive
- name: include_stats
description: Include statistical analysis
required: false
default: true
type_hint: boolean
---
Document Generator
---
name: doc-generator
title: Document Generator
description: Generates documentation from code or specifications
category: documentation
arguments:
- name: source
description: Source material to document
required: true
- name: format
description: Output format
required: false
default: markdown
- name: include_examples
description: Include usage examples
required: false
default: true
type_hint: boolean
---
Troubleshooting
Common Errors
Invalid YAML Syntax
# Error: Missing quotes around string with special characters
description: This won't work: because of the colon
# Fixed: Quote strings with special characters
description: "This works: because it's quoted"
Missing Required Fields
# Error: Missing required fields
title: My Prompt
# Fixed: Include all required fields
name: my-prompt
title: My Prompt
description: What this prompt does
Invalid Argument Structure
# Error: Missing required argument properties
arguments:
- name: code
# Fixed: Include required properties
arguments:
- name: code
description: Code to process
required: true
Validation Tips
- Use a YAML validator - Many online tools can check syntax
- Test with CLI - Use
swissarmyhammer test
to validate prompts - Check the logs - SwissArmyHammer provides detailed error messages
- Start simple - Begin with minimal front matter and add complexity
Next Steps
- Learn about Template Variables to use your arguments
- Explore Custom Filters for advanced text processing
- See Creating Prompts for the complete workflow
- Check Examples for real-world YAML configurations