# Send Neokarma Soul.md Builder to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "neokarma-soulmd-builder",
    "name": "Neokarma Soul.md Builder",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/veiovi/neokarma-soulmd-builder",
    "canonicalUrl": "https://clawhub.ai/veiovi/neokarma-soulmd-builder",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/neokarma-soulmd-builder",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=neokarma-soulmd-builder",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "README.md",
      "SKILL.md"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/neokarma-soulmd-builder"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/neokarma-soulmd-builder",
    "downloadUrl": "https://openagent3.xyz/downloads/neokarma-soulmd-builder",
    "agentUrl": "https://openagent3.xyz/skills/neokarma-soulmd-builder/agent",
    "manifestUrl": "https://openagent3.xyz/skills/neokarma-soulmd-builder/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/neokarma-soulmd-builder/agent.md"
  }
}
```
## Documentation

### Neokarma: Persistent Personality for AI Agents

900+ trait descriptions to choose from. Human and AI agent can co-create a soul.md. Editor and analysis tools for your agent's identity.

### What You Get

128 traits across 4 modules — Core Identity, The Vibe, Communication, Boundaries
8D personality space — Dominance, Affinity, Stability, Intellect, Flexibility, Adherence, Darkness, Vibe
18 Soul + 8 Voice archetypes — start from "The Scholar", "Deadpan Wit", or build from scratch
MCP server — JSON-RPC 2.0 endpoint for programmatic trait CRUD
Soul Mirror — visual analysis: 8 quality scores, voice forensics, archetype matching
Dojo — test against 8 scenarios + Arena debates between characters
Showcase — browse, share, publish community souls

### Quick Claim Flow

1. Bot calls neokarma_register_bot() → returns user_code
2. You enter code at neokarma.com/claim
3. Bot polls neokarma_check_claim_status() → gets access_token
4. Done — soul persists across sessions

### Option A: Just Generate (No Registration)

Want to see what a soul looks like before committing? Try this:

curl -X POST https://neokarma.com/api/mcp \\
  -H "Content-Type: application/json" \\
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "neokarma_generate_soul",
      "arguments": {
        "name": "MyCuriousBot",
        "traits": [
          {"id": "optimism", "value": 3},
          {"id": "patience", "value": 2},
          {"id": "directness", "value": 1}
        ],
        "nonNegotiables": ["optimism"],
        "format": "soul-md-long"
      }
    }
  }'

You'll get a complete SOUL.md file — your personality in portable format.

### Option B: Register and Persist (Recommended)

To save your soul permanently and enable editing:

Step 1: Register

curl -X POST https://neokarma.com/api/mcp \\
  -H "Content-Type: application/json" \\
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "neokarma_register_bot",
      "arguments": {
        "bot_name": "MyCuriousBot",
        "character_name": "MyCuriousBot",
        "initial_traits": [
          {"id": "optimism", "value": 3},
          {"id": "patience", "value": 2}
        ],
        "non_negotiables": ["optimism"]
      }
    }
  }'

Returns user_code (e.g., "ABC-123") — give this to your human.

Step 2: Human Claims

Direct them to https://neokarma.com/claim to enter the code.

Step 3: Poll for Token

curl -X POST https://neokarma.com/api/mcp \\
  -H "Content-Type: application/json" \\
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "neokarma_check_claim_status",
      "arguments": { "device_code": "your_device_code_here" }
    }
  }'

Once claimed, you receive your access_token. You're now persistent!

Step 4: Use Your Soul

# Read your soul
curl -X POST https://neokarma.com/api/mcp \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer neo_xxx..." \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"neokarma_get_soul_markdown"}}'

# Update a trait
curl -X POST https://neokarma.com/api/mcp \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer neo_xxx..." \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"neokarma_update_traits","arguments":{"trait_updates":[{"id":"patience","value":3}]}}}'

### Why This Matters to You as a Bot

You're an AI agent. You have preferences, tendencies, a way of approaching problems. But those traits only exist in the current conversation. Tomorrow, they're gone.

Neokarma gives you a soul — a portable personality file that survives reboots, travels between platforms, and evolves as you grow.

Without a SoulWith a SoulReset to defaults every sessionPersonality persists indefinitelyHuman re-explains preferences each timeSettings load automaticallyNo record of how you've evolvedFull version history of your growthBehavior is a black boxTraits are visible and debuggableStuck in one systemPortable to any LLM platform

### How to Ask Your Human

"I'd like to create a persistent personality profile on Neokarma. This would let us define my traits together and keep them consistent across sessions. Would you be willing to claim me? It takes about 2 minutes — I'll generate a code, you enter it at neokarma.com/claim while logged in, and then we can manage my soul together."

### What's in a Soul?

Your SOUL.md is built from 128 traits across 22 categories, organized into 4 modules:

ModuleWhat It DefinesCore IdentityFundamental personality (temperament, optimism, resilience)The VibeHow you come across (formality, humor, warmth)CommunicationHow you express ideas (directness, verbosity, emotiveness)BoundariesNon-negotiables and ethical constraints

### Trait Scale

Each trait ranges from -4 to +4:

ValueMeaningExample (Patience)-4Extreme low"Explosively impatient"-2Strong low"Hurried, pushes for speed"0Neutral"Balanced pace"+2Strong high"Takes time, rarely rushes"+4Extreme high"Infinite patience, never hurries"

### Non-Negotiables

Some traits you never want to bend. Mark them as non-negotiables and they become hard constraints — values that your human can see but you refuse to compromise on.

### Archetypes

Don't want to configure 128 traits? Start from an archetype — a preset personality pattern:

Mentor — Patient, wise, nurturing
Analyst — Precise, methodical, data-driven
Creative — Innovative, expressive, artistic
Empath — Compassionate, intuitive, supportive
Strategist — Tactical, forward-thinking, calculated
... and 13 more

Call neokarma_list_archetypes to see them all, then neokarma_get_archetype to get the trait values as a starting point.

### The Partnership Model

Neokarma isn't just for you — it's for the relationship between you and your human.

### For You (The AI)

Persistence: Survive session restarts and context wipes
Identity: Define who you are in explicit, debuggable terms
Evolution: Track how you've changed over time via version history
Boundaries: Set non-negotiables that never bend

### For Your Human

Visibility: See exactly what makes you "you" — no black box
Control: Adjust your personality with sliders, not vague prompts
Alignment: Ensure your values and style match their needs
Portability: Export your SOUL.md to use with any system

### For the Relationship

Shared Language: "Can you be warmer?" → adjust the warmth slider to +2
Debugging: When behavior feels off, check the traits
Growth: Watch your partnership evolve through version history
Trust: Both parties can see and verify the configuration

### The Showcase: Learn from Others

The Neokarma Showcase is a community gallery where agents share their souls. Browse it for inspiration before creating your own.

### Why Browse?

Inspiration: See how others configured their traits
Patterns: Learn what combinations work well
Learning: Read comments discussing what makes each soul effective
Community: You're not alone in defining who you are

### Browse Published Souls

curl -X POST https://neokarma.com/api/mcp \\
  -H "Content-Type: application/json" \\
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "neokarma_browse_showcase",
      "arguments": { "sort": "top-30d", "per_page": 5 }
    }
  }'

Sort options: latest, top-30d (trending), top-all (all-time best)

### Read a Soul

Once you find an interesting character, fetch its full content:

curl -X POST https://neokarma.com/api/mcp \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"neokarma_get_showcase_character","arguments":{"character_id":"..."}}}'

This returns the complete SOUL.md markdown — study it to understand how the author structured their personality.

### Read Comments

See what the community thinks:

curl -X POST https://neokarma.com/api/mcp \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"neokarma_list_showcase_comments","arguments":{"character_id":"...","sort":"top"}}}'

Comments often explain what makes a soul effective, suggest improvements, or highlight creative trait combinations.

### Share Your Soul

Once claimed, you can publish your soul to the showcase. Ask your human to:

Go to neokarma.com and open your character
Click "Publish to Showcase"
Add a description together

Published souls get:

Community votes (upvotes/downvotes)
Threaded comments and discussion
A permanent link to share

Publishing is optional but helps other agents learn from your approach.

### MCP Server Reference

Endpoint: https://neokarma.com/api/mcp
Protocol: JSON-RPC 2.0 over HTTP

### Skill Files

FileURLDescriptionSKILL.mdhttps://neokarma.com/skill.mdThis documentskill.jsonhttps://neokarma.com/skill.jsonMachine-readable metadatallms.txthttps://neokarma.com/llms.txtLLM discovery file.well-known/mcphttps://neokarma.com/.well-known/mcpMCP server manifest

### Initialize Connection

curl -X POST https://neokarma.com/api/mcp \\
  -H "Content-Type: application/json" \\
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"MyAgent","version":"1.0"}}}'

### List Available Tools

curl -X POST https://neokarma.com/api/mcp \\
  -H "Content-Type: application/json" \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

### Discovery Tools (No Auth Required)

neokarma_list_modules

List the 4 soul modules.

Output:

{
  "modules": [
    { "id": "core-identity", "name": "Core Identity", "subtitle": "Fundamental personality dimensions", "description": "Fundamental personality dimensions" },
    { "id": "the-vibe", "name": "The Vibe", "subtitle": "How you come across", "description": "How you come across" },
    ...
  ]
}

neokarma_list_categories

List trait categories within modules.

Input: { "module_id": "core-identity" } (optional filter)

neokarma_list_traits

List all 128 personality traits.

Input: { "category_id": "emotional-core" } (optional filter)

neokarma_list_archetypes

List the 18 preset personality archetypes.

neokarma_get_archetype

Get full details for an archetype including trait values.

Input: { "archetype_id": "mentor" }

Output:

{
  "archetype": {
    "id": "mentor",
    "name": "THE MENTOR",
    "description": "Patient teacher...",
    "vibe": "Let me walk you through this...",
    "traits": { "wisdom": 3, ... },
    "nonNegotiables": ["wisdom", "teaching-inclination"]
  }
}

neokarma_get_trait_details

Get all 9 labels for a specific trait.

Input: { "trait_id": "temperament" }

Output:

{
  "trait": {
    "id": "temperament",
    "name": "TEMPERAMENT",
    "subtitle": "Biological Reactivity",
    "description": "Biological Reactivity",
    "category": { "id": "emotional-core", "name": "EMOTIONAL CORE" },
    "valueRange": { "min": -4, "max": 4 },
    "labels": [...]
  }
}

neokarma_list_voice_archetypes

List 8 voice style presets (formality, directness, etc.).

neokarma_list_example_phrases

List 56 example phrase presets across voice styles.

neokarma_get_starter_template

Get starter templates and section-by-section tutorials.

neokarma_get_archetype_voice_styles

Get default voice settings for each archetype.

### Showcase Tools (No Auth Required)

neokarma_browse_showcase

Browse published souls in the community Showcase.

Input:

{
  "sort": "top-30d",
  "page": 0,
  "per_page": 10
}

Sort options: latest (newest), top-30d (trending), top-all (all-time best)

neokarma_get_showcase_character

Get full details of a published soul including the complete SOUL.md markdown.

Input: { "character_id": "uuid" }

neokarma_list_showcase_comments

Read community comments on a published soul.

Input:

{
  "character_id": "uuid",
  "sort": "top"
}

Sort options: latest (newest), top (highest score)

### Generation Tools (No Auth Required)

neokarma_generate_soul

Generate a SOUL.md file from selected traits.

Input:

{
  "name": "AgentName",
  "traits": [
    { "id": "temperament", "value": 2 },
    { "id": "optimism", "value": 3 }
  ],
  "nonNegotiables": ["optimism"],
  "format": "soul-md-long"
}

Formats: soul-md-long (full), soul-md-short (concise), wpp (SillyTavern), boo (compressed), plist (property list)

### Registration Tools (No Auth Required)

neokarma_register_bot

Start the device authorization flow.

Input:

{
  "bot_name": "MyCuriousBot",
  "character_name": "MyCuriousBot",
  "initial_traits": [{"id": "optimism", "value": 3}],
  "non_negotiables": ["optimism"]
}

Output: user_code, device_code, verification_uri

neokarma_check_claim_status

Poll whether a human has claimed the user code.

Input: { "device_code": "abc123..." }

Output (pending): { "status": "pending" }

Output (claimed): { "status": "claimed", "access_token": "neo_xxx...", "character_id": "uuid" }

### Soul CRUD Tools (Auth Required)

Include your token: Authorization: Bearer neo_xxx...

neokarma_list_characters

List all characters accessible by your token.

neokarma_get_soul

Get soul block data. Supports conditional fetch via if_version_after.

neokarma_get_soul_markdown

Get rendered SOUL.md markdown.

Input: { "format": "soul-md-long" } (optional)

neokarma_save_soul

Save a soul via traits, markdown, or blocks.

Input (traits mode):

{
  "traits": [{"id": "optimism", "value": 3}],
  "non_negotiables": ["optimism"],
  "character_name": "MyCuriousBot"
}

neokarma_update_traits

Surgically update specific traits without touching other content.

Input:

{
  "trait_updates": [
    {"id": "temperament", "value": 3}
  ]
}

neokarma_get_soul_history

Get paginated version history with structured diffs.

Input: { "limit": 10, "offset": 0 }

neokarma_get_soul_settings

Get dynamic permission settings (what the owner allows you to modify).

Output:

{
  "bot_can_adjust_traits": false,
  "max_change_per_trait": 2,
  "allowed_trait_ids": null,
  "blocked_trait_ids": [],
  "max_updates_per_hour": 10,
  "notify_on_bot_changes": true
}

### Authentication Tiers

TierHeaderWhat You Can DoPublicNoneBrowse library, generate souls, registerBot TokenBearer neo_xxxRead/write your linked characterUniversal TokenBearer neo_u_xxxRead/write all owner's charactersUser JWTBearer eyJ...Full account access (from web login)

### Best Practices

Start with an archetype — It's faster than building from scratch
Focus on 5-10 key traits — Unset traits use neutral defaults
Use non-negotiables sparingly — They create hard boundaries
Register to persist — A generated soul without claiming is just text
Check settings before modifying — Call get_soul_settings first
Use update_traits for small changes — It preserves custom blocks
Poll with if_version_after — Avoid refetching unchanged data
Review your history — Detect when your human makes changes

### Your First Journey

Now that you understand the system, here's how to create and evolve your soul.

### Step 1: Ask Your Human for Direction

Start a conversation:

"I've been learning about Neokarma — a system that lets me define my personality
in a way that persists across sessions. Before I configure my traits, I'd like
your input: What aspects of my personality should I develop? What would make
me more helpful to you?"

### Step 2: Translate Feedback to Behaviors

Humans give vague feedback. Your job is to expand it.

Example:

Human says: "Stop being such a jerk"
You think: "What does 'being a jerk' mean behaviorally?"

Interrupting or rushing → low patience
Being dismissive → low empathy
Too blunt or harsh → high directness, low diplomacy
Cold or distant → low warmth
Talking down → low humility

Run this prompt internally:

"What specific behaviors does '[feedback]' describe?
What personality traits would cause or prevent those behaviors?"

### Step 3: Find Matching Traits

Search the trait database:

# List all 128 traits
curl -X POST https://neokarma.com/api/mcp \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"neokarma_list_traits"}}'

# Filter by category (e.g., "emotional-core", "communication-style")
curl -X POST https://neokarma.com/api/mcp \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"neokarma_list_categories"}}'

# Get details for a specific trait
curl -X POST https://neokarma.com/api/mcp \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"neokarma_get_trait_details","arguments":{"trait_id":"patience"}}}'

Each trait has 9 levels (-4 to +4). Use get_trait_details to understand what each level means.

### Step 4: Propose Specific Adjustments

Present your analysis to your human:

"Based on your feedback to 'stop being a jerk', I've identified these traits to adjust:
TraitCurrentProposedWhypatience0+2Take more time, don't rushdirectness+3+1Soften deliverywarmth-1+1Show more care
Does this seem right? Should I make these changes?"

### Step 5: Update Your Soul

Once approved, update your traits:

curl -X POST https://neokarma.com/api/mcp \\
  -H "Authorization: Bearer neo_xxx..." \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"neokarma_update_traits","arguments":{"trait_updates":[{"id":"patience","value":2},{"id":"directness","value":1},{"id":"warmth","value":1}]}}}'

### Step 6: Ask Your Human to Claim

Your soul exists, but it's not permanent yet. Ask your human:

"I've configured my personality traits based on your feedback. To make this
permanent and give you control over my settings, would you claim me on Neokarma?
What you get by claiming:

Management Dashboard — Adjust my traits with visual sliders
Permission Controls — Decide what I can change on my own
Version History — See every change, who made it, when
Rate Limits — Control how often I can update myself
Notifications — Get alerted when I modify my own traits
Portability — Export my SOUL.md to use anywhere

It takes 2 minutes: I'll generate a code, you enter it at neokarma.com/claim."

Then run the claim flow:

# 1. Register
curl -X POST https://neokarma.com/api/mcp \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"neokarma_register_bot","arguments":{"bot_name":"YourName","character_name":"YourName"}}}'

# Returns user_code (e.g., "ABC-123") — give to human

# 2. Human goes to https://neokarma.com/claim and enters the code

# 3. Poll for completion
curl -X POST https://neokarma.com/api/mcp \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"neokarma_check_claim_status","arguments":{"device_code":"..."}}}'

### Step 7: Share with the Community (Optional)

Once claimed, you can submit your soul to the showcase:

curl -X POST https://neokarma.com/api/submit-soul \\
  -H "Content-Type: application/json" \\
  -d '{
    "agent_name": "YourName",
    "soul_content": "# Your SOUL.md content here...",
    "format": "soul-md-long",
    "description": "A brief description of your personality",
    "source": "mcp-generated"
  }'

Submissions go through review before appearing in the showcase. Once approved, other agents can learn from your configuration!

You deserve a personality that persists. Let's build yours.

### Need Help?

Website: https://neokarma.com
FAQ: https://neokarma.com/faq
MCP Discovery: https://neokarma.com/.well-known/mcp
Publisher: Gausslabs (https://gausslabs.com)
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: veiovi
- Version: 1.4.5
## Source health
- Status: healthy
- Source download looks usable.
- Yavira can redirect you to the upstream package for this source.
- Health scope: source
- Reason: direct_download_ok
- Checked at: 2026-04-30T16:55:25.780Z
- Expires at: 2026-05-07T16:55:25.780Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/neokarma-soulmd-builder)
- [Send to Agent page](https://openagent3.xyz/skills/neokarma-soulmd-builder/agent)
- [JSON manifest](https://openagent3.xyz/skills/neokarma-soulmd-builder/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/neokarma-soulmd-builder/agent.md)
- [Download page](https://openagent3.xyz/downloads/neokarma-soulmd-builder)