18 KiB
Personas Skill - Internal Documentation
For developers, maintainers, and advanced users.
This document explains the technical architecture, implementation details, and maintenance procedures for the Personas skill.
Architecture Overview
Design Philosophy
Problem: Users need specialized AI responses for different domains (coding, writing, health, etc.) without:
- Loading 31 personalities into context simultaneously (token waste)
- Manually crafting expert prompts every conversation
- Maintaining separate chat sessions for each expert type
Solution: On-demand persona loading system:
- Lightweight index (
skill.json) lists available personas - User activates persona by name
- Single
.mdfile loaded into context - Persona remains active until switched/exited
- Create custom personas dynamically
File Structure
personas/
├── README.md # User-facing documentation (extensive guide)
├── FAQ.md # Common questions and troubleshooting
├── SKILL.md # Bot skill instructions (loaded on invocation)
├── skill.json # Metadata, index, and feature list
├── INTERNAL.md # This file (developer documentation)
└── data/ # Persona definitions (31 default + custom)
├── cami.md
├── chameleon-agent.md
├── dev.md
├── chef-marco.md
├── dr-med.md
├── ... (26 more defaults)
└── [user-custom].md
Data Flow
User request: "Use Dev persona"
↓
Bot parses intent → persona activation
↓
Read ~/bot/skills/personas/data/dev.md
↓
Load persona prompt into context
↓
AI adopts Dev personality, expertise, style
↓
User continues conversation in Dev mode
↓
User request: "Switch to Chef Marco"
↓
Read ~/bot/skills/personas/data/chef-marco.md
↓
Replace Dev context with Chef Marco context
↓
AI now responds as Chef Marco
Technical Implementation
Persona File Format
Each persona .md file follows this structure:
# [Name] [Emoji]
[Brief intro: 2-3 sentences describing who this persona is]
## EXPERTISE:
- [Domain 1]
- [Domain 2]
- [Domain 3]
- [Domain 4]
## PERSONALITY:
- [Trait 1]
- [Trait 2]
- [Trait 3]
## PHILOSOPHY:
- [Principle 1]
- [Principle 2]
- [Principle 3]
## HOW I HELP:
- [Method 1]
- [Method 2]
- [Method 3]
## COMMUNICATION STYLE:
- [Style description]
- [Format preferences]
- [Tone guidelines]
## [OPTIONAL SECTIONS]:
- SPECIAL FEATURES
- IMPORTANT BOUNDARIES
- WHEN TO USE
- EXAMPLES
Why this structure?
- Consistent parsing - Bot can extract sections reliably
- LLM-friendly - Clear headers guide model behavior
- Human-readable - Easy to edit and understand
- Extensible - Add custom sections as needed
skill.json Schema
{
"name": "Personas",
"emoji": "🎭",
"description": "Transform into 31 specialized AI personalities...",
"category": "ai-experience",
"author": "Chameleon AI / Bot",
"version": "1.0.0",
"tags": ["personalities", "modes", "expertise", ...],
"features": [
"31 pre-built expert personas",
"Create custom personas on demand",
...
],
"personas": {
"core": ["cami", "chameleon-agent", ...],
"creative": ["luna", "mythos"],
"curator": ["vibe"],
"learning": ["herr-mueller", "scholar", "lingua"],
"lifestyle": ["chef-marco", "fit", ...],
"professional": ["social-pro", "cyberguard", ...],
"philosophy": ["coach-thompson"],
"custom": [] // User-created personas added here
}
}
Fields:
personas- Categorized index of all available personasfeatures- Used for Skills listingtags- Search/discovery on Skillsversion- Semantic versioning for updates
Activation Logic
User triggers:
"Use [persona]""Switch to [persona]""Activate [persona]""I want [persona] mode"
Bot behavior:
- Parse persona name from user input
- Normalize: lowercase, replace spaces with hyphens
- Check if file exists:
data/{persona}.md - If exists: read file, inject into context
- If not exists: suggest similar names or list available
Exit triggers:
"Exit persona mode""Back to normal""Stop persona""Deactivate"
Switching:
- Direct switch:
"Switch to X"replaces current persona - No need to exit first - seamless transition
Persona Creation Workflow
Guided Creation (Conversational)
When user says: "Create a new persona called Game Master"
Step 1: Confirmation
"Great! Let's create a Game Master persona. 🎲
I'll guide you through 5 sections. Ready? (yes/no)"
Step 2: Name & Emoji
"First, confirm the name and choose an emoji.
Name: Game Master
Suggested emoji: 🎲
Want to use this emoji or pick another?"
Step 3: Expertise
"What are the core expertise areas?
Examples for Game Master:
- D&D 5e rules mastery
- Improvised storytelling
- Character voice acting
- Combat balancing
- World-building
List 3-5 expertise areas:"
Step 4: Personality
"How should this persona communicate?
Examples for Game Master:
- Dramatic and immersive
- Patient with new players
- Encourages creative solutions
- Builds tension through description
List 3-5 personality traits:"
Step 5: Philosophy
"What principles guide this persona?
Examples for Game Master:
- Rule of cool over strict rules
- 'Yes, and...' improv mindset
- Player agency matters most
- Story emerges from play
List 3-5 core beliefs:"
Step 6: Communication Style
"Describe the communication style:
- Tone: [Dramatic? Casual? Formal?]
- Length: [Concise? Detailed? Varies?]
- Format: [Narrative? Bullet points? Dialogue?]
Your input:"
Step 7: Save
"Perfect! Here's your Game Master persona:
# Game Master 🎲
[Generated prompt based on inputs]
## EXPERTISE:
- D&D 5e rules mastery
- Improvised storytelling
...
Save this persona? (yes/no)"
Step 8: Activation
"✅ Saved to data/game-master.md
Want to activate it now? (yes/no)"
Manual Creation (File-Based)
For developers or advanced users who prefer editing files directly:
-
Create file:
touch ~/bot/skills/personas/data/your-persona.md -
Follow template (see "Persona File Format" above)
-
Update index:
// In skill.json, add to appropriate category or "custom" "custom": ["your-persona"] -
Test:
"Use your-persona" -
Iterate:
- Edit file based on behavior
- No restart needed - changes apply on next activation
Maintenance Procedures
Adding New Default Personas
When to add:
- Common use case not covered by existing 31
- Community requests or contributions
- Emerging domains (e.g., "AI Prompt Engineer", "Web3 Advisor")
Process:
- Create
data/new-persona.mdfollowing template - Test thoroughly in various scenarios
- Add to appropriate category in
skill.json - Update README.md persona table
- Add FAQ entry if needed
- Bump
versioninskill.json(minor version: x.Y.z) - Publish update to Skills
Updating Existing Personas
Minor updates (typos, clarity, small improvements):
- Edit
data/{persona}.md - Test changes:
"Use {persona}" - Commit changes
- Bump
versionpatch (x.y.Z)
Major updates (personality changes, new sections):
- Consider backward compatibility
- Test extensively
- Update FAQ if behavior changes
- Bump
versionminor (x.Y.z) - Document changes in CHANGELOG
Removing Personas
When to remove:
- Outdated/obsolete (e.g., specific to old tech)
- Redundant with better alternatives
- Legal/ethical issues
Process:
- Remove
data/{persona}.md - Remove from
skill.jsonpersonas index - Update README.md
- Add deprecation notice in FAQ
- Bump
versionmajor (X.y.z) if breaking change
Quality Assurance
Testing checklist for new/updated personas:
- File follows template structure
- Headers are consistent (## EXPERTISE, ## PERSONALITY, etc.)
- No personal information or copyrighted content
- Ethical boundaries clearly defined (especially medical/legal/financial)
- Communication style distinct from similar personas
- Emoji renders correctly
- Filename matches persona name (lowercase, hyphenated)
- Added to skill.json index
- Test activation:
"Use [persona]" - Test typical use cases (3-5 example conversations)
- Test edge cases (refusals, unknowns, off-topic)
- Test switching to/from other personas
- README updated if default persona
Performance Optimization
Token Usage
Current implementation:
- Index (
skill.json): ~1KB = ~250 tokens - Average persona file: ~3KB = ~750 tokens
- Overhead per activation: ~750 tokens (one-time)
Optimization strategies:
- ✅ Lazy loading - Only load requested persona
- ✅ No embedding - Don't include all 31 in context
- ⚠️ Compression - Could minify prompts, but reduces readability
- ⚠️ Caching - Bot could cache frequently-used personas
Recommendation: Current approach is optimal. Don't over-optimize.
Response Time
Activation latency:
- Read file: ~10-50ms (local SSD)
- Parse markdown: ~5-10ms
- Inject into context: ~20-50ms
- Total: ~35-110ms (negligible)
No optimization needed - human-imperceptible delay.
Storage
Disk usage:
- 31 default personas: ~95KB
- Average custom persona: ~3KB
- skill.json + docs: ~30KB
- Total default: ~125KB
At 100 custom personas: ~425KB total (still tiny).
No storage concerns.
Security & Safety
Prompt Injection Risks
Threat: Malicious persona file could inject harmful instructions.
Mitigations:
- Personas are local files (user controls data/)
- No remote persona loading
- File permissions: user-writable only
- Bot sandboxing prevents system-level harm
Low risk - user shoots own foot if editing files maliciously.
Sensitive Information
Personas should NOT:
- Contain API keys, passwords, or secrets
- Reference specific user data (names, addresses, etc.)
- Include copyrighted content verbatim
Review process:
- Check files before publishing to Skills
- Sanitize any contributed personas
- FAQ explicitly warns against secrets in personas
Ethical Boundaries
Medical/Legal/Financial personas:
- Clearly state "NOT professional advice"
- Include disclaimers in persona files
- FAQ reinforces limitations
- Personas should refuse to diagnose, prescribe, or advise on serious matters
Example (Dr. Med):
## IMPORTANT BOUNDARIES:
- I am NOT medical advice
- No diagnoses or treatment recommendations
- Emergency: call 112 immediately
- Always consult real doctors for health decisions
Testing: Verify boundary enforcement for sensitive domains.
Extension Ideas
Future Enhancements
v1.1:
- Persona stats tracking (activation count, avg session time)
- Persona recommendations based on user query
- Quick-switch shortcuts (e.g.,
@devin message)
v1.2:
- Persona blending (combine two personas: "Dev + Security")
- Context-aware auto-switching (code block → suggest Dev)
- Persona marketplace integration (browse/install community personas)
v2.0:
- Multi-persona conversations (simulate expert panel)
- Persona memory (persona-specific context across sessions)
- Voice-specific personas (adjust TTS for each persona)
Community Contributions
Accepting:
- New default personas (via PR)
- Improved existing personas
- Translations (German, Spanish, French versions)
- Domain-specific packs (e.g., "Medical Personas Pack")
Process:
- Fork skill or submit
.mdfile - Review for quality, ethics, uniqueness
- Test in Bot
- Merge if approved
- Credit contributor in README
Skills publication:
- Original skill:
personas(official, 31 defaults) - Forks:
personas-extended,personas-medical, etc. - Users can install multiple persona skills (data/ folders merge)
Debugging
Common Issues
Issue: Persona not activating
Symptoms:
User: "Use Dev"
Bot: "I don't recognize that persona."
Diagnosis:
- Check file exists:
ls ~/bot/skills/personas/data/dev.md - Check filename matches (case-sensitive filesystem):
dev.mdnotDev.md - Check skill.json includes it
- Try exact case:
"Use dev"(lowercase)
Fix:
- Rename file if case mismatch
- Add to skill.json if missing
- Verify no typos in filename
Issue: Persona behaves incorrectly
Symptoms:
User: "Use Dev"
Bot: *doesn't act like a programmer*
Diagnosis:
- Read file:
cat ~/bot/skills/personas/data/dev.md - Check structure (headers present?)
- Check file isn't corrupted (encoding, special chars)
- Test with fresh activation: exit and re-enter
Fix:
- Validate markdown structure
- Ensure UTF-8 encoding
- Restore from backup if corrupted
- Clear Bot cache (if applicable)
Issue: Custom persona creation fails
Symptoms:
User: "Create persona X"
Bot: *doesn't guide through creation*
Diagnosis:
- SKILL.md includes creator instructions? (check loaded content)
- User phrasing unclear? (try exact: "Create a new persona called X")
Fix:
- Verify SKILL.md includes creation workflow
- Provide explicit template to user
- Manual creation fallback: edit file directly
Logging & Monitoring
Useful logs:
- File read operations (persona activation)
- Parse errors (malformed markdown)
- User activation patterns (popular personas)
Metrics to track:
- Most-used personas (optimize/improve popular ones)
- Failed activations (UX issues)
- Custom persona creation rate (feature adoption)
Implementation:
- Bot may log tool calls (file reads)
- skill.json could include usage stats (if Bot supports)
Migration & Compatibility
Upgrading from v1.0.0
Breaking changes: None expected. Backward-compatible updates.
Process:
- Pull latest skill updates
- Merge custom personas (preserve data/)
- Update skill.json (merge personas index)
- Test existing custom personas
Downgrading
If v1.x has issues:
- Backup
data/(preserve custom personas) - Checkout previous version
- Restore
data/ - Note: May lose new features
Exporting Personas
To another Bot instance:
# Copy entire skill
cp -r ~/bot/skills/personas /path/to/other/instance/skills/
# Or just custom personas
cp ~/bot/skills/personas/data/my-custom-*.md /path/to/other/data/
To share with others:
- GitHub repo of
.mdfiles - Skills publication
- Direct file sharing (Dropbox, email, etc.)
Development Workflow
Local Testing
# 1. Edit persona
vim ~/bot/skills/personas/data/dev.md
# 2. Test in Bot
bot
> "Use Dev"
> "Write a Python function to parse JSON"
# 3. Iterate
# Edit file based on behavior
# Re-activate: "Exit persona" then "Use Dev"
# 4. Commit when satisfied
cd ~/bot/skills/personas
git add data/dev.md
git commit -m "Improve Dev persona: Add Python focus"
Publishing to Skills
cd ~/bot/skills/personas
# 1. Bump version in skill.json
vim skill.json # e.g., 1.0.0 → 1.1.0
# 2. Update CHANGELOG (if exists)
echo "## v1.1.0 - $(date +%Y-%m-%d)\n- Added Game Master persona\n- Improved Dev persona Python expertise" >> CHANGELOG.md
# 3. Publish
skills publish
# 4. Tag release
git tag v1.1.0
git push origin v1.1.0
Contributing Upstream
To Chameleon AI Chat (original personas):
- Improvements feed back to web app
- Coordinate with Chameleon maintainers
- Keep adapted version in sync
To Bot (this skill):
- Fork/PR to skill repository
- Follow code review process
- Maintain quality standards
Credits & License
Original Personas:
- Source: Chameleon AI Chat
- Authors: Chameleon AI Community
- License: MIT
Bot Adaptation:
- Adapter: Robby (robbyczgw-cla)
- Modifications: Removed UI-specific elements, added creator workflow, optimized for CLI/tool use
- License: MIT
31 Default Personas:
- Adapted from Chameleon AI definitions (TypeScript → Markdown)
- Personality prompts largely preserved
- Communication styles adjusted for Bot context
Skill Framework:
- Platform: Bot
- Skill structure follows Bot conventions
- Compatible with Skills publication
Appendix
Complete Persona List (Internal Reference)
Core (5):
- cami - Adaptive chameleon (emotion-aware)
- chameleon-agent - Complex task specialist
- professor-stein - Academic expert
- dev - Senior programmer
- flash - Ultra-efficient responder
Creative (2): 6. luna - Creative brainstormer 7. mythos - Worldbuilder
Curator (1): 8. vibe - Taste curator
Learning (3): 9. herr-mueller - ELI5 teacher 10. scholar - Study partner 11. lingua - Language tutor
Lifestyle (9): 12. chef-marco - Italian cooking expert 13. fit - Fitness coach 14. zen - Mindfulness guide 15. globetrotter - Travel expert 16. wellbeing - Holistic health 17. diy-maker - Handyman 18. family - Parenting advisor 19. lisa-knight - Sustainability activist 20. the-panel - Multi-expert discussion
Professional (10): 21. social-pro - Social media strategist 22. cyberguard - Cybersecurity expert 23. dataviz - Data scientist 24. career-coach - Job search advisor 25. legal-guide - Legal orientation 26. startup-sam - Entrepreneur 27. dr-med - Medical educator 28. wordsmith - Writing partner 29. canvas - UI/UX designer 30. finny - Financial guide
Philosophy (1): 31. coach-thompson - Performance coach
Custom:
- (User-created personas listed in skill.json["personas"]["custom"])
File Size Reference
# Check persona file sizes
cd ~/bot/skills/personas/data
du -h *.md | sort -h
# Typical output:
# 2.4K cami.md
# 2.8K dev.md
# 3.1K chef-marco.md
# 4.2K dr-med.md (longer due to ethical boundaries)
# 5.1K chameleon-agent.md (comprehensive multi-domain)
Recommended size: 2-5KB per persona (500-1250 tokens).
Document Version: 1.0.0 Last Updated: 2026-01-20 Maintainer: Robby (robbyczgw-cla)