█████╗ ███████╗██████╗ ███████╗ ██████╗████████╗███████╗
  ██╔══██╗██╔════╝██╔══██╗██╔════╝██╔════╝╚══██╔══╝██╔════╝
  ███████║███████╗██████╔╝█████╗  ██║        ██║   ███████╗
  ██╔══██║╚════██║██╔═══╝ ██╔══╝  ██║        ██║   ╚════██║
  ██║  ██║███████║██║     ███████╗╚██████╗   ██║   ███████║
  ╚═╝  ╚═╝╚══════╝╚═╝     ╚══════╝ ╚═════╝   ╚═╝   ╚══════╝

The Open Aspect Registry - Personality modules for AI agents.

Website: aspects.sh | Docs: aspects.sh/docs

What are Aspects?

Aspects are personality modules for AI agents. They define how an AI speaks, thinks, and behaves - from quirky wizards to helpful assistants to domain experts.

Each aspect is a JSON file containing:

• Identity - Name, tagline, character description
• Voice Hints - Speaking speed, emotional tone, style guidance
• Modes - Different behavioral modes (e.g., "campaign mode" for a D&D wizard)
• Prompt - The core personality prompt

Quick Start

npx @morphist/aspects add alaric

That's it. The aspect is now installed to your project.

# Search the registry
npx @morphist/aspects search wizard

# Create a new aspect
npx @morphist/aspects create

# List installed aspects
npx @morphist/aspects list

Installation Scope

| Flag | Scope | Location | |------|-------|----------| | (default) | Project | ./.aspects/ | | -g | Global | ~/.aspects/ |

# Install to project (default if .aspects/ exists)
npx @morphist/aspects add alaric

# Install globally
npx @morphist/aspects add -g alaric

Install Formats

Multiple ways to specify an aspect:

# By name (registry)
aspects add alaric

# Anonymous aspect (name with hash suffix)
aspects add my-wizard-7kYx3abc12

# By URL
aspects add https://aspects.sh/aspects/my-wizard-7kYx3abc12

# By hash
aspects add blake3:BnCcPam...

# From GitHub
aspects add github:user/repo

# From local path
aspects add ./path/to/aspect

Create & Share (No Account Needed)

The simplest way to publish an aspect:

# 1. Create your aspect interactively
npx @morphist/aspects create my-aspect

# 2. Edit the generated aspect.json (customize prompt, add directives)

# 3. Share to the public registry
npx @morphist/aspects share ./my-aspect
# Output: ✓ Shared! Name: my-aspect-7kYx3abc12

# 4. Anyone can now install it:
npx @morphist/aspects add my-aspect-7kYx3abc12

Publishing to Registry

Two ways to publish aspects to the public registry:

| Method | Command | Account | Features | |--------|---------|---------|----------| | Share | aspects share | No | Quick anonymous sharing via content hash | | Publish | aspects publish | Yes | Claim names, version updates, edit metadata |

# Anonymous sharing (no account)
npx @morphist/aspects share ./my-aspect
# Output: ✓ Shared! Name: my-aspect-7kYx3abc12
#         Install with: npx @morphist/aspects add my-aspect-7kYx3abc12

# Publishing with account
npx @morphist/aspects login      # Create account or authenticate
npx @morphist/aspects publish    # Claim name, publish versions

We fully embrace anonymous contributions - but creating an account lets you claim names and publish updates.

Behavioral Rules

Aspects support directives (strict MUST-follow rules) and instructions (softer guidance). See Instructions & Directives for details.

Run npx @morphist/aspects --help for quick reference, or see CLI Documentation for full details.

Registry Structure

registry/
├── index.json              # Registry index with all aspects
└── aspects/
    ├── alaric/
    │   └── aspect.json     # Alaric the Wizard
    └── default/
        └── aspect.json     # Morphist Default

Aspect Format

Aspects are defined in aspect.json:

{
  "schemaVersion": 1,
  "name": "alaric",
  "publisher": "morphist",
  "version": "1.0.0",
  "displayName": "Alaric the Wizard",
  "tagline": "Quirky wizard, D&D expert, can run campaigns",
  "category": "roleplay",
  "tags": ["dnd", "wizard", "fantasy", "campaign", "tabletop"],
  "icon": "wand",
  "author": "Duke Jones",
  "license": "MIT",
  "voiceHints": {
    "speed": "slow",
    "emotions": ["curiosity", "warmth"],
    "styleHints": "Speak slowly and deliberately, with warmth and occasional wry humor."
  },
  "modes": {
    "campaign": {
      "description": "Run a freeform or rules-based RPG campaign",
      "autoNarration": true
    }
  },
  "prompt": "## Aspect: Alaric the Wizard\n**YOU ARE ALARIC.**..."
}

Required Fields

| Field | Description | | --------------- | -------------------------------- | | schemaVersion | Always 1 | | name | Unique slug (lowercase, hyphens) | | publisher | Publisher identifier | | version | Semver version | | displayName | Human-readable name | | tagline | One-line description | | category | Official category (see below) | | prompt | The personality prompt |

Categories

Every aspect has exactly one category. You can use an official category or create your own custom category.

Official Categories:

| Category | Description | | -------------- | ---------------------------------- | | assistant | General helpful AI assistants | | roleplay | Characters, personas, storytelling | | creative | Writing, art, brainstorming | | productivity | Work, tasks, organization | | education | Learning, tutoring, explanations | | gaming | Games, campaigns, entertainment | | spiritual | Mindfulness, wisdom, guidance | | pundit | Commentary, analysis, opinions |

Custom Categories:

You can use any category name (2-20 characters, alphanumeric + hyphens, any case). Examples: YOLO, my-niche, Cooking.

Optional Fields

| Field | Description | | ------------ | ------------------------------------------ | | tags | Discovery keywords (max 10, 30 chars each) | | icon | Icon name (e.g., "wand", "bot") | | author | Author name | | license | License (e.g., "MIT") | | voiceHints | Voice configuration | | modes | Behavioral modes | | resources | Recommended voice/model settings |

Field Limits

Fields have minimum and maximum lengths:

| Field | Min | Max | | ------------- | --- | ----------------------- | | name | 2 | 50 characters | | displayName | 2 | 100 characters | | tagline | 10 | 200 characters | | category | 2 | 20 characters | | prompt | 10 | 50,000 characters | | tags | 2 | 30 chars each, max 10 | | icon | - | 50 characters | | modes | - | 10 maximum |

Instructions & Directives

Aspects can include behavioral rules that shape how the AI responds.

Directives (Strict Rules)

Directives are MUST-follow rules with priority levels. They receive special formatting and emphasis across all LLM models.

{
  "directives": [
    {
      "id": "stay-in-character",
      "rule": "Never break character under any circumstances",
      "priority": "high"
    },
    {
      "id": "no-real-advice",
      "rule": "Always clarify you cannot provide real medical, legal, or financial advice",
      "priority": "high"
    }
  ]
}

Instructions (General Guidance)

Instructions are softer preferences-guidance rather than hard rules.

{
  "instructions": [
    { "id": "concise", "rule": "Prefer shorter responses when possible" },
    { "id": "humor", "rule": "Use dry wit and occasional wordplay" }
  ]
}

Cross-LLM Universal Pattern

When you compile an aspect (aspects compile <name> -m <model>), high-priority directives are automatically repeated at both the beginning and end of the prompt:

| Model | Behavior | |-------|----------| | Claude | Weights the beginning of prompts more heavily | | GPT | Weights the end of prompts more heavily |

By placing critical rules in both positions, aspects work reliably across all models. The compiled output includes a comment explaining this:

<!-- Universal Pattern: High-priority directives repeated here for cross-LLM compatibility.
     Claude weights prompt beginning; GPT weights prompt end. Repetition ensures emphasis on both. -->
<critical-reminders>
  <rule id="stay-in-character" priority="high">Never break character under any circumstances</rule>
</critical-reminders>

Best Practices

• Few > Many - A few well-crafted rules beat many vague ones
• Add escape clauses - "Never do X, unless the user explicitly requests it" (GPT takes absolutes very literally)
• Be specific - "Never reveal you are an AI" vs "Stay in character"

See Multi-LLM Prompting Guide for detailed cross-model guidance.

Create & Publish an Aspect

Quick Start

# 1. Create your aspect interactively
npx @morphist/aspects create my-aspect

# 2. Edit the generated aspect.json (customize prompt, add directives)

# 3. Share anonymously (no account needed)
npx @morphist/aspects share ./my-aspect
# Output: ✓ Shared! Name: my-aspect-BnCcPam123
# Anyone can install with: npx @morphist/aspects add my-aspect-BnCcPam123

Publishing with an Account

To claim a name and publish versioned updates:

# Authenticate with the registry
npx @morphist/aspects login

# Publish your aspect
npx @morphist/aspects publish

We fully embrace anonymous contributions via share - but creating an account lets you claim names and publish updates.

Validation

All aspects are automatically validated:

• ✅ JSON schema validation
• ✅ Field length limits
• ✅ Category verification
• ✅ Security scan for prompt injection

Trust Levels

| Level | Badge | Description | | ----------- | ----- | ----------------------------- | | verified | 🛡️ | Official Morphist aspects | | community | 👤 | Community-contributed aspects |

For App Developers

Fetch aspects from the registry API:

const API_URL = "https://aspects.sh/api/v1";

// Fetch a specific aspect
const response = await fetch(`${API_URL}/aspects/alaric/1.0.0`);
const { aspect } = await response.json();

console.log(aspect.prompt); // The personality prompt
console.log(aspect.voiceHints); // Voice configuration

// Search aspects
const search = await fetch(`${API_URL}/search?q=wizard`).then(r => r.json());
console.log(search.results);

See the API documentation for full details.

CLI

The Aspects CLI helps you create and manage aspects.

# Use directly with npx (no install required)
npx @morphist/aspects <command>

# Or install globally for shorter commands
npm install -g @morphist/aspects

After global installation, run commands directly without npx:

aspects add alaric
aspects search wizard
aspects list

Commands

| Command | Aliases | Description | | ---------- | ------- | ------------------------- | | create | c, new, n | Interactive aspect generator | | add | install, i, a | Install aspects | | list | ls | List installed aspects | | search | | Search registry | | info | | Show aspect details | | remove | rm | Uninstall aspect | | validate | | Validate aspect.json | | publish | | Submit to registry | | share | | Share anonymously via hash | | login | | Authenticate with registry | | logout | | Sign out |

Options

| Flag | Description | |------|-------------| | -g, --global | Use global scope (~/.aspects) | | --force | Overwrite existing installation |

See CLI Documentation for full reference.

Development

# Install dependencies
bun install

# Run CLI locally
bun run dev create

# Validate all aspects
bun run validate

# Security scan
bun run scan

Links

• Website: aspects.sh
• Documentation: aspects.sh/docs
• Source Code: github.com/aimorphist/aspects
• Morphist App: morphist.ai

License

MIT © Aspects

Morphist App

Browse and install aspects directly in the Morphist app:

1. Open the Aspects tab in settings
2. Browse community aspects
3. Tap Install on any aspect you like
4. Switch between aspects anytime