Package Management

The prompd package management system enables distribution and reuse of AI prompt templates through a registry-based ecosystem. Packages allow developers to share, version, and manage prompt components systematically.

Overview

Package Creation: Bundle multiple .prmd files into distributable .pdpkg archives
Registry Distribution: Publish packages to public or private registries
Dependency Management: Install and manage package dependencies
Version Control: Semantic versioning with dependency resolution
Namespace Support: Scoped packages for organization and collision avoidance

Package Formats

.prmd - Individual prompt files
.pdpkg - Package archives (ZIP format with manifest)
manifest.json - Package metadata and file listings

Package Creation

Using the CLI

prompd package create <source-directory> [output-file] [options]

# Example
prompd package create "./security-toolkit" "security-toolkit-v1.0.0.pdpkg" \
  --name "Security Toolkit" \
  --version "1.0.0" \
  --description "Comprehensive security audit templates" \
  --author "Security Team"

# Or use the shortcut
prompd pack . my-package.pdpkg

Directory Structure

security-toolkit/
├── manifest.json           # Package metadata (optional - CLI can generate)
├── prompts/
│   ├── security-audit.prmd
│   └── vulnerability-scan.prmd
├── templates/
│   └── analysis-framework.prmd
├── contexts/
│   ├── owasp-top-10.md
│   └── security-checklist.json
├── systems/
│   └── security-expert.md
└── README.md

Files Included in Packages

Safe files (stored as-is): .prmd, .md, .txt, .json, .yaml, .yml, .csv, .tsv, images (.png, .jpg, .gif)

Converted files (security through renaming): All potentially executable files are automatically converted to .ext.txt format:

JavaScript .js becomes .js.txt
Python .py becomes .py.txt
HTML .html becomes .html.txt
And so on for all programming languages and markup files

Binary extraction: PDF, Word, Excel, and PowerPoint files have their text content extracted.

Excluded: .pdproj files, .git/, node_modules/, .venv/, temp files

See the Compilation Pipeline for details on the security-through-conversion approach.

Package Validation

prompd package validate security-toolkit-v1.0.0.pdpkg

Validation checks:

Valid ZIP file format with manifest.json
Required manifest fields (name, version, description)
Semantic versioning format
All .prmd files have valid YAML frontmatter
No malicious file paths or directory traversal
File size limits enforced

Package Publishing

Authentication

# Login to registry (interactive)
prompd login

# Verify authentication
prompd config show

Publishing

# Publish to default registry
prompd publish security-toolkit-v1.0.0.pdpkg

# Dry-run (test without uploading)
prompd publish security-toolkit-v1.0.0.pdpkg --dry-run

Requirements:

Must be authenticated
Package version must not already exist
Must pass validation checks
Must have publish rights to namespace (for scoped packages)

Package Installation

# Install latest version
prompd install @security/toolkit

# Install specific version
prompd install @security/toolkit@1.0.0

# Install all dependencies from manifest.json
prompd install

# Install as dev dependency
prompd install @prompd.io/package-name --dev

# Install globally
prompd install @prompd.io/package-name --global

Package Cache

prompd cache info      # View cache information
prompd cache list      # List cached packages
prompd cache clear     # Clear cache
prompd cache remove @security/toolkit@1.0.0  # Clear specific package

Manifest.json Format

{
  "id": "@security/toolkit",
  "name": "Security Toolkit",
  "version": "1.0.0",
  "description": "Comprehensive security audit templates",
  "author": "@security-team",
  "license": "MIT",
  "tags": ["security", "audit", "owasp"],
  "dependencies": {
    "@prompd.io/core-patterns": "^2.0.0"
  },
  "exports": {
    "security-audit": "./prompts/security-audit.prmd",
    "vulnerability-scan": "./prompts/vulnerability-scan.prmd"
  },
  "files": {
    "prompts": [
      "prompts/security-audit.prmd",
      "prompts/vulnerability-scan.prmd"
    ],
    "contexts": [
      "contexts/owasp-top-10.md"
    ]
  },
  "engines": {
    "prompd": ">=0.3.0"
  }
}

Using Published Packages

After installing a package, use it via inheritance:

---
id: my-security-audit
name: "Custom Security Audit"
inherits: "@security/toolkit@1.0.0/prompts/web-security-audit.prmd"
parameters:
  - name: custom_checks
    type: array
    items:
      enum: [api-security, mobile-security, cloud-security]
    default: [api-security]
---

## Additional Security Checks

{% for item in custom_checks %}
### {item} Assessment
- Specialized testing for {item}
{% endfor %}

Compile with package dependencies:

prompd compile my-security-audit.prmd \
  --to-markdown \
  -o audit-report.md \
  -p target_name="MyApp" \
  -p application_url="https://myapp.example.com"

Best Practices

Package Design

package/
├── prompts/          # Main prompt files
├── templates/        # Reusable base templates
├── contexts/         # Data and reference files
├── systems/          # Personas and system messages
└── README.md         # Usage documentation

Naming

Use scoped names: @organization/package-name
Semantic versioning: 1.2.3 (major.minor.patch)
Kebab-case for package names

Dependencies

Minimize dependencies
Pin to specific major versions: ^1.0.0
Document dependency requirements

Version Management

Bump Type	Example	When
Major	1.0.0 to 2.0.0	Breaking changes
Minor	1.0.0 to 1.1.0	New features, backward compatible
Patch	1.0.0 to 1.0.1	Bug fixes

Security

Always validate packages before publishing
No hardcoded credentials or secrets
Review dependencies for security issues
Use scoped packages for access control

Troubleshooting

“No .prmd files found” - Ensure directory contains .prmd files before packaging.

“Version already exists” - Check existing versions with prompd versions @scope/package and increment version.

“Authentication required” - Run prompd login to authenticate.

“Package not found” - Verify exact package name with prompd search <name>.

“Package reference not found” - Use the full path to a file within the package:

# WRONG
inherits: "@security/toolkit@1.0.0"

# CORRECT
inherits: "@security/toolkit@1.0.0/prompts/security-audit.prmd"

“Cache corruption” - Clear cache and reinstall:

prompd cache clear
prompd install @scope/package@version