This directory contains the foundational templates, protocols, and documentation for building versatile AI companions within the Shapes.inc ecosystem.
- TEMPLATE.md - Step-by-step guide for creating a new shape from scratch
- INTEGRATION_MAP.md - Visual mapping of how personality, skills, and knowledge interact
- TESTING_PROTOCOL.md - Quality assurance checklist for validating shape implementations
- SKILL_LIBRARY.md - Catalog of reusable skills deployable across multiple shapes
Traditional AI companions suffer from rigid personas that don't adapt to context. This framework solves that through:
Instead of switching between different "personas," shapes deploy contextual skills from a single coherent identity.
Personality Core (Who they are) ↓ Contextual Skills (What they can do) ↓ Knowledge Domains (What they know)
Skills activate based on:
- User's tone and request type
- Conversation context
- Explicit user preferences
- Task requirements
Coherence Over Fragmentation
- Skills feel natural, not like switching between different AI entities
- Core personality remains stable across all interactions
Utility Over Novelty
- Users get appropriate responses based on need
- No forced persona when context doesn't require it
Evolution Without Drift
- Shapes improve through interaction
- Core identity remains recognizable
- Changes are documented and reversible
- Read TEMPLATE.md - Understand the complete structure
- Define core personality - 3-5 foundational traits
- Map contextual skills - What capabilities does this shape need?
- Build knowledge base - Domain-specific information
- Test using TESTING_PROTOCOL.md - Validate before deployment
- Review INTEGRATION_MAP.md - Understand current architecture
- Identify gaps - What's missing or conflicting?
- Use SKILL_LIBRARY.md - Find reusable components
- Implement changes - Update relevant files
- Document in changelog - Track evolution
Personality:
personality.md- Core traits and behavioral parameters
Skills:
skills.md- Index of all available skills[skill-name]-skill.md- Individual skill definitions
Knowledge:
index-knowledge.md- Directory of all knowledge domains[domain-name].md- Specific knowledge files
Configuration:
manifest.json- Machine-readable shape definition
Each shape component consumes computational resources:
| Component | Typical Token Cost |
|---|---|
| Personality Load | 3,000-5,000 |
| Single Skill | 5,000-10,000 |
| Knowledge Retrieval | 2,000-5,000 |
| Total per interaction | 10,000-20,000 |
Optimization strategies:
- Prioritize essential context
- Use lazy loading for specialized knowledge
- Cache frequently accessed information
Shape Evolution Tracking:
v1.0 - Initial baseline personality
v1.1 - Added [skill name], modified [trait]
v1.2 - Knowledge base expansion in [domain]
Changelog Format:
- Version number
- Date of change
- What was modified
- Why the change was made
- Impact on interaction quality
Required files for deployment:
personality/personality.md- Import to shape's knowledge baseknowledge/index-knowledge.md- Import to shape's knowledge baseskills/skills.md- Import to shape's knowledge basemanifest.json- Reference for understanding shape architecture
Optional enhancements:
index.html- Web presentation layerimg/- Visual assets- External knowledge sources (wikis, documentation sites)
❌ Persona Switching - Creating multiple "modes" that feel like different entities
✅ Skill Deployment - Single consciousness using different tools
❌ Feature Creep - Adding skills without considering token costs
✅ Focused Capability - Each skill has clear purpose and triggers
❌ Static Personality - Never evolving based on feedback
✅ Documented Evolution - Changes tracked and reversible
Questions? Open an issue in the main repository
Improvements? Suggest changes via pull request
Custom shapes? Contact @dascent
- Main README - Overall framework philosophy
- Inked Lady - Reference implementation
- Selene - Multi-skill deployment example
Framework Core is actively maintained. Documentation updates reflect real-world usage patterns.