Complete guide to creating, using, and contributing PAI packs
Version: 1.0.0 Last updated: 2025-12-22
- What Are PAI Packs?
- Pack Format Specification
- Creating a Pack
- Installing Packs
- Pack Lifecycle
- Quality Standards
- Security Guidelines
- Contribution Process
- FAQs
PAI Packs are self-contained functionality bundles that contain everything your AI needs to implement a specific capability in your personal AI system.
Traditional approach:
"Here's our codebase, go figure out how to integrate it"
❌ Requires deep understanding of host system
❌ Prone to breaking changes
❌ All-or-nothing integration
PAI Pack approach:
"Here's a complete solution with full context for your AI to integrate"
✅ AI reads the pack and adapts it to YOUR system
✅ Self-contained with all dependencies documented
✅ Pick only what you need
Every PAI pack contains:
- Problem Statement - What's broken or missing?
- Solution Overview - How this pack addresses it
- Complete Source Code - All tools, scripts, CLIs embedded in the markdown
- Workflows - Step-by-step processes and decision trees
- Context Files - Guidelines, specifications, aesthetic rules
- Examples - Real usage scenarios with expected outputs
- Installation Instructions - Both AI-assisted and manual
- Testing Procedures - How to verify it works
- Troubleshooting - Common issues and fixes
- Credits & Resources - Attribution and further reading
Portability - Email it, version control it, share it as one file
AI-Optimized - Your AI can read the entire context at once without navigation
Human-Readable - Open in any text editor, searchable, transparent
Self-Contained - No external dependencies for the pack itself (though it may call external tools)
Easy Review - See exactly what you're installing before you install it
PackName-Pack.md
Examples:
Art-Pack.mdResearch-Pack.mdOSINT-Pack.md
Rules:
- Title Case for pack name
- Always ends with
-Pack.md - No spaces (use hyphens)
- Descriptive, not generic
# PackName Pack vX.Y.Z
**One-line description**
---
## Pack Metadata
\```yaml
pack:
name: PackName
version: X.Y.Z (semantic versioning)
category: visual-content | automation | research | security | etc
author: Your Name
license: MIT (or other open source license)
requires:
- CORE >= 1.0.0 (optional dependency on other packs)
- OtherPack >= 2.0.0
platforms:
- macos
- linux
- windows (note any platform-specific limitations)
dependencies:
tools:
- bun
- ImageMagick
- jq
api_keys:
- PROVIDER_API_KEY
- ANOTHER_SERVICE_KEY
\```
---
## The Problem
[2-4 paragraphs describing the problem this pack solves]
What's broken? What's inefficient? What gap exists?
---
## The Solution
[2-4 paragraphs describing how this pack addresses the problem]
What's the approach? What makes it better? What's the key insight?
---
## Quick Start
### 1. Install Dependencies
\```bash
[Installation commands for required tools]
\```
### 2. Set Up API Keys
\```bash
[How to configure environment variables]
\```
### 3. Create Your First [Thing]
\```bash
[Minimal working example that proves it works]
\```
---
## Pack Contents
### Skill Definition (if applicable)
\```yaml
name: SkillName
description: When to use this skill
trigger_phrases: ["phrase1", "phrase2"]
routing:
- pattern: "regex or keyword"
workflow: WorkflowName
\```
### Workflows
#### WorkflowName
**Purpose:** [What this workflow does]
**When to use:** [Trigger conditions]
**Process:**
\```markdown
[Complete step-by-step workflow]
[Can be multi-page if needed]
\```
### Tools
#### ToolName.ts (or .py, .sh)
**Purpose:** [What this tool does]
**Usage:**
\```bash
[Command-line usage examples]
\```
**Full Source Code:**
\```typescript
[Complete, working, tested code]
[No placeholders, no TODOs]
\```
### Context Files
#### ContextFileName.md
**Purpose:** [What context this provides]
\```markdown
[Full context file content]
\```
### Hooks (if applicable)
#### hook-name.ts
**Event:** [When this hook fires]
**Purpose:** [What it does]
\```typescript
[Complete hook code]
\```
---
## Examples
### Example 1: [Common Use Case]
**Scenario:** [Description of the situation]
**Command:**
\```bash
[Actual command to run]
\```
**Expected Output:**
[What should happen]
### Example 2: [Another Use Case]
[Repeat pattern]
---
## Installation
### Option A: AI-Assisted Installation (Recommended)
Give this pack to your AI and ask:
> "Install the PackName pack into my system. Verify dependencies, save the tools, and test it works."
Your AI will:
1. [Step 1]
2. [Step 2]
3. [etc]
### Option B: Manual Installation
**1. Install dependencies:**
\```bash
[Commands]
\```
**2. Save the tools:**
\```bash
[Where to save each tool]
\```
**3. Configure environment:**
\```bash
[Environment setup]
\```
**4. Test installation:**
\```bash
[Smoke test command]
\```
---
## Configuration
### Required Settings
[List of environment variables, config files, etc.]
### Optional Settings
[Additional configuration options]
### Recommended Defaults
[What settings work best]
---
## Testing
### Smoke Test
\```bash
[Quick test to verify basic functionality]
\```
**Success criteria:**
- ✅ [Criterion 1]
- ✅ [Criterion 2]
### Validation Checklist
For production use, verify:
- [ ] [Thing 1]
- [ ] [Thing 2]
- [ ] [etc]
---
## Troubleshooting
### Issue: [Common Problem]
**Cause:** [Why it happens]
**Fix:**
\```bash
[Solution]
\```
### Issue: [Another Problem]
[Repeat pattern for all common issues]
---
## Credits
**Original concept:** [Attribution]
**Influences:**
- [Person/Project 1]
- [Person/Project 2]
**Technical implementation:**
- [Tool/Service 1]
- [Tool/Service 2]
**Community contributions:**
- [Contributor 1]: [What they added]
- [Contributor 2]: [What they added]
---
## Resources
### Further Reading
- [Link 1] - [Description]
- [Link 2] - [Description]
### Related Packs
- **PackName** - [How it relates]
- **AnotherPack** - [How it relates]
### External Documentation
- [API docs]
- [Tool documentation]
---
## Version History
### vX.Y.Z (YYYY-MM-DD)
- [Change 1]
- [Change 2]
### vX.Y.Z (YYYY-MM-DD)
- Initial release
---
## License
[License text - typically MIT for PAI packs]
---
**End of PackName Pack vX.Y.Z**
For support, issues, or contributions, visit: [Repository URL]Good packs solve real problems:
- ✅ "I kept manually doing X, so I automated it"
- ✅ "I needed Y capability and built a workflow"
- ✅ "Existing tools don't handle Z well"
- ❌ "I wrote some code once and thought I'd share"
- ❌ "Here's a wrapper around an existing tool with no added value"
Ask yourself:
- Does this solve a real problem I've experienced?
- Would others benefit from this solution?
- Is this self-contained enough to be a pack?
If extracting from an existing system:
- Identify all dependencies - What files, tools, APIs does it need?
- Document the workflows - How do you actually use this?
- Create examples - What are real usage scenarios?
- Write tests - How do you know it works?
If building from scratch:
- Start with the problem statement - Be specific
- Design the solution - How will it work?
- Build incrementally - Start simple, add features
- Test thoroughly - On fresh systems if possible
Use the template above. Fill in every section:
- Don't skip sections - Even if brief, include them
- Real examples, not placeholders -
example.com→ actual URLs - Complete code - No TODOs, no "implement this later"
- Test your instructions - Can someone actually follow them?
Before submitting:
- Give the pack to YOUR AI
- Ask it to install the pack
- See if it works without your help
- Fix any issues the AI encounters
- Repeat until installation is smooth
See Contribution Process below.
For Claude Code users:
- Open the pack markdown file
- Copy the entire content
- Paste into Claude Code and say:
Install this pack into my system. Verify all dependencies,
save the tools to appropriate directories, set up any routing
or hooks needed, and test that it works.
Claude will:
- Parse the pack
- Check for required tools/APIs
- Create necessary directories
- Save code to appropriate locations
- Configure any integrations
- Run tests to verify functionality
For other AI platforms:
The process is similar - give your AI the pack and ask it to install. The AI should be able to read the pack format and adapt it to your system structure.
If you prefer manual control or don't have AI assistance:
- Read the pack - Understand what it does
- Check dependencies - Install required tools
- Set up environment - Configure API keys, env vars
- Save the code - Copy tools to your directories
- Follow integration steps - Skills, hooks, etc
- Run tests - Verify it works
Recommended directory structure:
~/.your-ai-system/
├── Skills/
│ └── PackName/
│ ├── Tools/
│ │ ├── tool1.ts
│ │ └── tool2.ts
│ ├── Workflows/
│ │ └── workflow.md
│ └── SKILL.md
├── .env (for API keys)
└── settings.json
You don't have to install the whole pack:
- Copy just the code you need
- Adapt the workflow to your process
- Use as reference documentation
- Extract the concept and implement differently
Packs are not prescriptive. They're building blocks.
PAI packs use Semantic Versioning:
MAJOR.MINOR.PATCH
1.0.0 → 1.0.1 (bug fix, backwards compatible)
1.0.1 → 1.1.0 (new feature, backwards compatible)
1.1.0 → 2.0.0 (breaking change)
When to bump versions:
-
PATCH (1.0.0 → 1.0.1)
- Bug fixes
- Documentation improvements
- Typo corrections
-
MINOR (1.0.0 → 1.1.0)
- New features (backwards compatible)
- New workflows added
- New optional parameters
-
MAJOR (1.0.0 → 2.0.0)
- Breaking changes to APIs
- Removed features
- Changed workflows that break existing usage
Pack authors are responsible for:
- Responding to issues about their pack
- Fixing reported bugs
- Considering feature requests
- Updating for dependency changes
- Marking pack as deprecated if abandoned
If a pack becomes unmaintained:
- Community can fork and maintain separately
- Can be marked as "community maintained"
- Original author retains credit
If a pack becomes obsolete:
- Mark it as
[DEPRECATED]in the README - Explain why (replaced by X, no longer relevant, etc.)
- Provide migration path if applicable
- Keep the pack available for reference
- ✅ Clear problem statement - What does this solve?
- ✅ Complete working code - Tested, no placeholders
- ✅ Real examples - Actual usage, not hypothetical
- ✅ Installation instructions - Both AI and manual
- ✅ Testing procedure - How to verify it works
- ✅ Troubleshooting section - Common issues
- ✅ No hardcoded secrets - Use environment variables
- ✅ License specified - MIT preferred for PAI
- Screenshots of output (for visual packs)
- Video demo or walkthrough
- Multiple examples for different use cases
- Integration notes for popular platforms
- Performance characteristics (if relevant)
- Known limitations documented
- Diagram of architecture/flow
- Comparison with alternatives
- Advanced usage patterns
- Customization options
- Related packs integration
All code in packs must:
- Work as described (test it!)
- Follow reasonable conventions for the language
- Include error handling
- Have clear variable names
- Be reasonably efficient
- Be secure (no SQL injection, XSS, etc.)
Code doesn't need to be:
- Perfect
- Over-engineered
- Production-grade enterprise quality
- Optimized to death
The standard: Would you use this yourself? If yes, it's probably good enough.
NEVER include in packs:
- ❌ Actual API keys
- ❌ Passwords or tokens
- ❌ Private URLs or endpoints
- ❌ Personal data
- ❌ Internal system details
Instead:
- ✅ Use environment variable references (
$API_KEY) - ✅ Provide
.env.exampletemplates - ✅ Document which keys are needed
- ✅ Link to where to get keys
Check for:
- SQL injection vulnerabilities
- Command injection risks
- XSS in generated output
- Path traversal issues
- Insecure deserial ization
Best practices:
- Validate all inputs
- Sanitize user data
- Use parameterized queries
- Escape shell commands
- Limit file system access
For external dependencies:
- Document what they are and why needed
- Check for known vulnerabilities
- Pin versions when possible
- Provide alternatives if available
git clone https://github.com/yourusername/PAI
cd PAIgit checkout -b add-pack-yourpacknameSave your pack to Packs/YourPack-Pack.md
- Install in a fresh system using the instructions
- Have your AI try to install it
- Fix any issues that come up
- Document troubleshooting steps
git add Packs/YourPack-Pack.md
git commit -m "Add YourPack - one-line description"
git push origin add-pack-yourpacknameThen open a PR on GitHub with:
Title: Add [PackName] Pack - [One-line description]
Description:
## Pack: [PackName]
### What It Does
[Brief description]
### Problem It Solves
[The problem statement]
### Testing Done
- [ ] Tested manual installation
- [ ] Tested AI-assisted installation
- [ ] All examples work as described
- [ ] Tested on [platforms]
### Screenshots/Demos
[If applicable]
### Checklist
- [ ] Pack follows format specification
- [ ] All code is complete and tested
- [ ] No hardcoded secrets
- [ ] Real examples included
- [ ] Installation instructions work
- [ ] Troubleshooting section complete
- [ ] Credits and attribution includedMaintainers will review for:
- Completeness - All sections present
- Quality - Code works, examples are real
- Security - No secrets, no vulnerabilities
- Usefulness - Solves a real problem
Timeline: Most PRs reviewed within 7 days
Feedback: Reviewers may request changes. This is normal and expected.
Once approved:
- PR is merged
- Pack appears in catalog
- You're listed as a contributor
- You maintain the pack going forward
Yes! Many useful packs require paid services (AI models, specialized APIs, etc.).
Just ensure:
- Clearly document the cost (approximate pricing)
- Provide free alternatives if they exist
- Make it clear it's not free to run
Yes! Specify dependencies in the metadata:
requires:
- CORE >= 1.0.0
- Research >= 2.1.0Absolutely! Pack authors maintain their packs:
- Make changes
- Update version number
- Add to version history
- Submit PR
That's fine! Competition is healthy:
- Different approaches to same problem
- Different trade-offs (speed vs quality, cost vs features)
- Personal preference
Users can choose what works best for them.
Yes, but the version in PAI must be:
- Functional and useful on its own
- MIT licensed
- Free and open-source
You can offer:
- Premium support
- Extended features
- Hosted versions
- Consulting
Just be transparent about what's free vs paid.
You're responsible for maintaining it:
- Update the code to work with new dependency
- Or pin to older version and document limitation
- Or mark as deprecated and provide migration path
This is part of being a pack maintainer.
Absolutely! PAI packs should work across platforms:
- OpenCode
- Custom AI systems
- Gemini Code
- GPT-Codex
- Homebrew setups
Just note any platform-specific quirks in the documentation.
Before submitting, verify:
- File named
PackName-Pack.md - Metadata section complete
- All required sections present
- Follows template structure
- Problem clearly stated
- Solution explained
- Quick start works
- All code complete (no TODOs)
- Real examples (not placeholders)
- Installation instructions tested
- Troubleshooting section complete
- Code tested and works
- No hardcoded secrets
- No personal data
- Dependencies documented
- Security considerations addressed
- Manual installation tested
- AI-assisted installation tested (if possible)
- All examples run successfully
- Tested on claimed platforms
- Credits and attribution included
- License specified
- Resources and links provided
- Version history started
- PACKAGE_TEMPLATE.md - Start here for new packs
- Art-Pack.md - Complete visual content system (good reference)
- README.md - PAI overview
- SECURITY.md - Security policies
- LICENSE - MIT license details
- GitHub Discussions - Ask questions
- Issue Tracker - Report problems
Questions? Open a discussion or issue on GitHub.
Ready to contribute? We can't wait to see what you build!