Prompt Organization
Effective prompt organization is crucial for maintaining a scalable and manageable prompt library. This guide covers best practices for organizing your SwissArmyHammer prompts.
Directory Structure
Recommended Hierarchy
~/.swissarmyhammer/prompts/
├── development/
│ ├── languages/
│ │ ├── python/
│ │ ├── javascript/
│ │ └── rust/
│ ├── frameworks/
│ │ ├── react/
│ │ ├── django/
│ │ └── fastapi/
│ └── tools/
│ ├── git/
│ ├── docker/
│ └── ci-cd/
├── writing/
│ ├── technical/
│ ├── business/
│ └── creative/
├── data/
│ ├── analysis/
│ ├── transformation/
│ └── visualization/
├── productivity/
│ ├── planning/
│ ├── automation/
│ └── workflows/
└── _shared/
├── components/
├── templates/
└── utilities/
Directory Purposes
- development/ - Programming and technical prompts
- writing/ - Content creation and documentation
- data/ - Data processing and analysis
- productivity/ - Task management and workflows
- _shared/ - Reusable components and utilities
Naming Conventions
File Names
Use consistent, descriptive file names:
# Good examples
code-review-python.md
api-documentation-generator.md
git-commit-message.md
database-migration-planner.md
# Avoid
review.md
doc.md
prompt1.md
temp.md
Naming Rules
- Use kebab-case for file names
- Be descriptive - Include the purpose and context
- Add type suffix when multiple variants exist
- Keep under 40 characters for readability
Prompt Names (in YAML)
# Good - matches file name pattern
name: code-review-python
# Also good - hierarchical naming
name: development/code-review/python
# Avoid - too generic
name: review
Categories and Tags
Using Categories
Categories provide broad groupings:
---
name: api-security-scanner
title: API Security Scanner
category: development
subcategory: security
---
Effective Tagging
Tags enable fine-grained discovery:
---
name: react-component-generator
tags:
- react
- javascript
- frontend
- component
- generator
- boilerplate
---
Category vs Tags
- Categories: Single, broad classification
- Tags: Multiple, specific attributes
# Category for primary classification
category: development
# Tags for detailed attributes
tags:
- python
- testing
- pytest
- unit-tests
- tdd
Modular Design
Base Templates
Create base templates in _shared/templates/
:
<!-- _shared/templates/code-review-base.md -->
---
name: code-review-base
title: Base Code Review Template
abstract: true # Indicates this is a template
---
# Code Review
## Overview
Review the following code for:
- Best practices
- Potential bugs
- Performance issues
- Security concerns
## Code
```{{language}}
{{code}}
Analysis
{{analysis_content}}
### Extending Base Templates
```markdown
<!-- development/languages/python/code-review-python.md -->
---
name: code-review-python
title: Python Code Review
extends: code-review-base
---
{% capture analysis_content %}
### Python-Specific Checks
- PEP 8 compliance
- Type hints usage
- Pythonic idioms
- Import organization
{% endcapture %}
{% include "code-review-base" %}
Shared Components
Store reusable components in _shared/components/
:
<!-- _shared/components/security-checks.md -->
---
name: security-checks-component
component: true
---
### Security Analysis
- Input validation
- SQL injection risks
- XSS vulnerabilities
- Authentication flaws
- Data exposure
Use in prompts:
---
name: web-app-review
---
# Web Application Review
{{code}}
{% include "_shared/components/security-checks.md" %}
## Additional Checks
...
Versioning
Version in Metadata
Track prompt versions:
---
name: api-generator
version: 2.1.0
updated: 2024-03-20
changelog:
- 2.1.0: Added GraphQL support
- 2.0.0: Breaking change - new argument structure
- 1.0.0: Initial release
---
Version Directories
For major versions with breaking changes:
prompts/
├── development/
│ ├── api-generator/
│ │ ├── v1/
│ │ │ └── api-generator.md
│ │ ├── v2/
│ │ │ └── api-generator.md
│ │ └── latest -> v2/api-generator.md
Migration Guides
Document version changes:
<!-- development/api-generator/MIGRATION.md -->
# API Generator Migration Guide
## v1 to v2
### Breaking Changes
- `endpoint_list` argument renamed to `endpoints`
- `auth_method` now requires specific values
### Migration Steps
1. Update argument names in your scripts
2. Validate auth_method values
3. Test with new version
Collections
Prompt Collections
Group related prompts:
<!-- collections/fullstack-development.md -->
---
name: fullstack-collection
title: Full-Stack Development Collection
type: collection
---
# Full-Stack Development Prompts
## Frontend
- `frontend/react-component` - React component generator
- `frontend/vue-template` - Vue.js templates
- `frontend/css-optimizer` - CSS optimization
## Backend
- `backend/api-design` - API design assistant
- `backend/database-schema` - Schema designer
- `backend/auth-implementation` - Authentication setup
## DevOps
- `devops/docker-config` - Docker configuration
- `devops/ci-pipeline` - CI/CD pipeline setup
- `devops/deployment-guide` - Deployment strategies
Collection Metadata
---
name: data-science-toolkit
type: collection
prompts:
- data/eda-assistant
- data/feature-engineering
- data/model-evaluation
- data/visualization-guide
dependencies:
- python
- pandas
- scikit-learn
---
Search and Discovery
Metadata for Search
Optimize prompts for discovery:
---
name: code-documenter
title: Intelligent Code Documentation Generator
description: |
Generates comprehensive documentation for code including:
- Function/method documentation
- Class documentation
- Module overview
- Usage examples
- API references
keywords:
- documentation
- docstring
- comments
- api docs
- code docs
- jsdoc
- sphinx
- rustdoc
search_terms:
- "generate documentation"
- "add comments to code"
- "create api docs"
- "document functions"
---
Aliases
Support multiple names:
---
name: git-commit-message
aliases:
- commit-message
- git-message
- commit-generator
---
Related Prompts
Link related prompts:
---
name: code-review-security
related:
- code-review-general
- security-audit
- vulnerability-scanner
- penetration-test-guide
---
Team Collaboration
Shared Conventions
Document team conventions in CONVENTIONS.md
:
# Prompt Conventions
## Naming
- Use `project-` prefix for project-specific prompts
- Use `team-` prefix for team-wide prompts
- Use `personal-` prefix for individual prompts
## Categories
- `project` - Project-specific
- `team` - Team standards
- `experimental` - Under development
## Required Metadata
All prompts must include:
- name
- title
- description
- author
- created date
- category
Ownership
Track prompt ownership:
---
name: deployment-checklist
author: jane.doe@company.com
team: platform-engineering
maintainers:
- jane.doe@company.com
- john.smith@company.com
review_required: true
last_reviewed: 2024-03-15
---
Review Process
Implement prompt review:
---
name: api-contract-generator
status: draft # draft, review, approved, deprecated
reviewers:
- senior-dev-team
approved_by: tech-lead@company.com
approval_date: 2024-03-10
---
Import/Export Strategies
Partial Exports
Export specific categories:
# Export only development prompts
swissarmyhammer export dev-prompts.tar.gz --filter "category:development"
# Export by tags
swissarmyhammer export python-prompts.tar.gz --filter "tag:python"
# Export by date
swissarmyhammer export recent-prompts.tar.gz --filter "updated:>2024-01-01"
Collection Bundles
Create installable bundles:
# bundle.yaml
name: web-development-bundle
version: 1.0.0
description: Complete web development prompt collection
prompts:
include:
- category: frontend
- category: backend
- tag: web
exclude:
- tag: experimental
dependencies:
- swissarmyhammer: ">=0.1.0"
install_to: ~/.swissarmyhammer/prompts/bundles/web-dev/
Sync Strategies
Keep prompts synchronized:
#!/bin/bash
# sync-prompts.sh
# Backup local changes
swissarmyhammer export local-backup-$(date +%Y%m%d).tar.gz
# Pull team prompts
git pull origin main
# Import team updates
swissarmyhammer import team-prompts.tar.gz --merge
# Export for distribution
swissarmyhammer export team-bundle.tar.gz --filter "team:approved"
Best Practices
1. Start Simple
Begin with basic organization:
prompts/
├── work/
├── personal/
└── learning/
Then evolve as needed.
2. Use Meaningful Hierarchies
# Good - clear hierarchy
development/testing/unit-test-generator.md
development/testing/integration-test-builder.md
# Avoid - flat structure
unit-test-generator.md
integration-test-builder.md
3. Document Your System
Create prompts/README.md
:
# Prompt Library Organization
## Structure
- `development/` - Programming prompts
- `data/` - Data analysis prompts
- `writing/` - Content creation
- `_shared/` - Reusable components
## Naming Convention
- Files: `purpose-context-type.md`
- Prompts: Match file names
## How to Contribute
1. Choose appropriate category
2. Follow naming conventions
3. Include all required metadata
4. Test before committing
4. Regular Maintenance
# Find unused prompts
swissarmyhammer list --unused --days 90
# Find duplicates
swissarmyhammer list --duplicates
# Validate all prompts
swissarmyhammer doctor --check prompts
5. Progressive Enhancement
Start with basic prompts and enhance:
# Version 1 - Basic
name: code-review
description: Reviews code
# Version 2 - Enhanced
name: code-review
description: Reviews code for quality, security, and performance
category: development
tags: [review, quality, security]
version: 2.0.0
Examples
Enterprise Setup
company-prompts/
├── departments/
│ ├── engineering/
│ │ ├── standards/
│ │ ├── templates/
│ │ └── tools/
│ ├── product/
│ │ ├── specs/
│ │ ├── research/
│ │ └── documentation/
│ └── data-science/
│ ├── analysis/
│ ├── models/
│ └── reporting/
├── projects/
│ ├── project-alpha/
│ ├── project-beta/
│ └── _archived/
├── shared/
│ ├── components/
│ ├── templates/
│ └── utilities/
└── personal/
└── [username]/
Open Source Project
oss-prompts/
├── contribution/
│ ├── issue-templates/
│ ├── pr-templates/
│ └── code-review/
├── documentation/
│ ├── api-docs/
│ ├── user-guide/
│ └── examples/
├── maintenance/
│ ├── release/
│ ├── changelog/
│ └── security/
└── community/
├── support/
└── onboarding/
Automation
Auto-Organization Script
#!/usr/bin/env python3
# organize-prompts.py
import os
import yaml
from pathlib import Path
def organize_prompts(source_dir, target_dir):
"""Auto-organize prompts based on metadata."""
for prompt_file in Path(source_dir).glob("**/*.md"):
with open(prompt_file) as f:
content = f.read()
# Extract front matter
if content.startswith("---"):
_, fm, _ = content.split("---", 2)
metadata = yaml.safe_load(fm)
# Determine target path
category = metadata.get("category", "uncategorized")
subcategory = metadata.get("subcategory", "")
target_path = Path(target_dir) / category
if subcategory:
target_path = target_path / subcategory
# Move file
target_path.mkdir(parents=True, exist_ok=True)
target_file = target_path / prompt_file.name
prompt_file.rename(target_file)
print(f"Moved {prompt_file} -> {target_file}")
Validation Script
#!/bin/bash
# validate-organization.sh
echo "Validating prompt organization..."
# Check for prompts without categories
echo "Prompts without categories:"
grep -L "category:" prompts/**/*.md
# Check for duplicate names
echo "Duplicate prompt names:"
swissarmyhammer list --format json | jq -r '.[] | .name' | sort | uniq -d
# Check naming conventions
echo "Files not following naming convention:"
find prompts -name "*.md" | grep -v "[a-z0-9-]*.md"
Next Steps
- See Creating Prompts for prompt creation guidelines
- Learn about Advanced Prompts for complex scenarios
- Explore Examples for organization patterns
- Read Configuration for system-wide settings