``text
█████╗ ███████╗██████╗ ███████╗ ██████╗████████╗███████╗
██╔══██╗██╔════╝██╔══██╗██╔════╝██╔════╝╚══██╔══╝██╔════╝
███████║███████╗██████╔╝█████╗ ██║ ██║ ███████╗
██╔══██║╚════██║██╔═══╝ ██╔══╝ ██║ ██║ ╚════██║
██║ ██║███████║██║ ███████╗╚██████╗ ██║ ███████║
╚═╝ ╚═╝╚══════╝╚═╝ ╚══════╝ ╚═════╝ ╚═╝ ╚══════╝
`

> 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

`bash
npx @morphist/aspects add alaric
`

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

`bash


Search the registry

npx @morphist/aspects search wizard

Create a new aspect

npx @morphist/aspects create

List installed aspects

npx @morphist/aspects list
`

$3

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

`bash


Install to project (default if .aspects/ exists)

npx @morphist/aspects add alaric

Install globally

npx @morphist/aspects add -g alaric
`

$3

Multiple ways to specify an aspect:

`bash


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
`

$3

The simplest way to publish an aspect:

`bash


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
`

$3

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 |

`bash


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.

$3

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

`text
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:

`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\nYOU ARE ALARIC...."
}
`

$3

| 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 |

$3

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.

$3

| 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 |

$3

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.

$3

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

`json
{
"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"
}
]
}
`

$3

Instructions are softer preferences-guidance rather than hard rules.

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

$3

When you compile an aspect (aspects compile -m ), 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:

`xml


Never break character under any circumstances

`

$3

- 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

$3

`bash


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

`

$3

To claim a name and publish versioned updates:

`bash


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.

$3

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:

`typescript
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.

`bash


Use directly with npx (no install required)

npx @morphist/aspects

Or install globally for shorter commands

npm install -g @morphist/aspects
`

After global installation, run commands directly without npx:

`bash
aspects add alaric
aspects search wizard
aspects list
`

$3

| 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 |

$3

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

See CLI Documentation for full reference.

Development

`bash


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