aeonfun/soul.md: Markdown Personality Files for Claude Code and OpenClaw

What a soul.md file is meant to fix

Most attempts to make an agent sound like a specific person fail in the same place. You write a long system prompt, the model follows it for two turns, and then it drifts back to generic assistant prose. The README frames the problem as one of format rather than model: a soul file captures who you are in a format AI agents can embody, and the stated goal is that someone reading your SOUL.md should be able to predict your takes on new topics. That is a testable claim, and the README treats vagueness as the failure mode. The audience is people who already write in public and now want an agent to write in their place: content generation, replies, brainstorming, and querying your own material. The repository also positions the format against note-taking tools. A notes vault answers what did I save about X; a soul file answers what would I think about X. That distinction is the whole pitch, and it is narrower than it sounds. You are not building a knowledge base. You are building a compressed model of your judgment.

How the builder turns raw posts into markdown

The mechanism is deliberately unglamorous. You place source material in a data/ folder, with subfolders such as data/x/ for a Twitter/X export and data/writing/ for blog posts and essays, then invoke the /soul-builder skill inside Claude Code or OpenClaw. The agent reads the corpus, extracts worldview and voice, drafts the soul file, and you review and refine it in conversation. There is no embedding index, no training run and no server. The output is a small set of markdown files that any LLM can load, which is why the compatibility table in the README lists frameworks in YAML, TypeScript, Python, Rust and Go alongside Claude Code, OpenCode, Codex and Goose. The repository layout reflects that: SOUL.template.md, STYLE.template.md, examples/good-outputs.template.md and examples/bad-outputs.template.md sit at the top level next to SKILL.md and MEMORY.md. The examples/ directory ships worked profiles for karpathy, vitalik-buterin, elon-musk, garry-tan, michael-saylor, steipete, hunter-biden and ansem, with a _GUIDE.md. Those are the closest thing to a specification of what a finished soul file looks like, and they are worth reading before you write your own. The split between SOUL.md (identity, worldview, opinions) and STYLE.md (how you write) is the main design decision, and it is a good one: voice and belief drift at different rates, so keeping them in separate files means you can revise one without disturbing the other.

Installing soul.md and running /soul-builder once

The README does not give a package install, a version number or a registry name. It points at the repository and at the skill invocation, so treat this as a checkout rather than a dependency. Clone the repository, then open Claude Code or OpenClaw in that directory so the skill is discoverable, and create the data folder structure the README shows.

git clone https://github.com/aeonfun/soul.md
cd soul.md
mkdir -p data/x data/writing

Drop a Twitter/X export into data/x/ and any essays or posts into data/writing/. Then invoke the builder from inside the agent session.

/soul-builder

The README states that the agent analyzes your data, extracts patterns and drafts your soul file, and that you review and refine together. What you should see is a draft SOUL.md and STYLE.md in the working directory, not a trained model. If you have no corpus, the interview path is the alternative: the same command, with the agent asking about worldview, opinions, how you write and what you care about. The manual path avoids the agent entirely.

cp SOUL.template.md SOUL.md
cp STYLE.template.md STYLE.md
cp examples/good-outputs.template.md examples/good-outputs.md
cp examples/bad-outputs.template.md examples/bad-outputs.md

All three options converge on the same artifact: markdown files you own and can edit by hand. That is the strongest property of the project. Nothing here locks your identity into a vendor's storage.

Wiring the soul into Aeon, or into any other agent

The README describes one integration in detail. Aeon is an autonomous agent that runs on GitHub Actions and is powered by Claude Code, with 68 skills on a cron schedule. To use a soul file there, you copy it into a soul/ directory in your Aeon repository and add a few lines to CLAUDE.md. The README claims identity then propagates to every skill Aeon runs, with no per-skill configuration. That is the division of labour the project is built around: Aeon handles the when and what, the soul files handle the who. For everything else, the README's position is that soul files are plain markdown, so if an agent can read files it can embody you, and it points to a Using With Other Tools section for models driven by a system prompt. The compatibility table names OpenClaw, Hermes Agent, Nanobot, ZeroClaw, NanoClaw, PicoClaw, OpenFang and IronClaw alongside the generic tooling. Read that table as a claim of format compatibility, not of tested integration. The README says tested with, but it does not describe what the test consisted of, and the star figures printed in the table are not evidence of anything about how well a soul file loads.

Where soul.md stops being the right tool

The failure mode is data quality, and the README says so plainly: the more signal, the sharper the output. A thin corpus produces a thin soul. If you mostly write short replies rather than long-form argument, the extracted worldview will be a list of reactions with no reasoning behind them, and the resulting file will read as a mood rather than a mind. The second limitation is that nothing here evaluates the output. There is no scoring harness, no held-out set of your takes, no way to check the README's own prediction test except by asking a colleague to guess your opinion on something new. You are the benchmark. Third, the project is a skill and a set of templates, not a service. There is no hosted builder, no API and no runtime that enforces the file at generation time. If you want an agent that refuses to break character, this does not provide that guarantee. And if your goal is factual recall over your own documents rather than imitation of your judgement, a retrieval setup over the same corpus is the more direct answer. A soul file will confidently reason in your voice about a topic you never wrote about, which is the feature and also the risk.

soul.md compared with CLAUDE.md and a plain system prompt

The nearest alternative is not another product but the mechanism you are probably already using: CLAUDE.md, or a system prompt pasted at the top of a session. Those are instructions, and they are written once and rarely revisited. A soul file is a structured artifact with a template, a builder that derives it from evidence, and a review step. The practical difference shows up when you change agents. A system prompt is rewritten for each tool and drifts between them; the same SOUL.md and STYLE.md load into Claude Code, OpenClaw or anything that reads files, because the format is markdown and the content is prose. The other difference is provenance. A system prompt encodes what you believe about yourself. A soul file built from data/x/ and data/writing/ encodes what your writing actually shows, which is often not the same thing. The examples/ directory makes the comparison concrete: you can read a finished profile for karpathy or vitalik-buterin and judge whether the format captures a real voice or only a summary of one. If it captures a summary, a hand-written prompt is cheaper and no worse.

Maintenance, licence and what the repository does not say

The repository is not archived and the last push was on 2026-09-07, so it is current as of this writing. There are no retrieved releases, which means there is no version history to pin against and no changelog to read before upgrading. In practice you upgrade by pulling the repository and re-reading SOUL.template.md and STYLE.template.md for new fields, then deciding by hand whether to merge them into your own files. Because your soul lives in your own markdown, a template change cannot break it; the cost is manual reconciliation, not a migration. The licence is MIT, which permits commercial use and modification provided the copyright notice and permission notice are included. That is a statement about the licence text, not advice about your situation; if you are building a product on top of the templates, have someone qualified read the LICENSE file at the repository root. Two things the README does not document: how to roll back a bad soul file, and how the builder handles private material such as iMessage, Slack or Discord exports that appear in its data-source table. For the first, keep your files in git. For the second, the README is silent, and you should assume anything you drop into data/ is sent to whichever model the agent is running.

Editorial conclusion

Adopt soul.md if you already run Claude Code or OpenClaw and want a voice layer that stays plain text and portable across agents. Skip it if you expect a runtime, a hosted service or a quality guarantee: the repository is a skill plus templates, and the README states no evaluation method. Before committing, read SOUL.template.md and STYLE.template.md to see whether the fields match what you actually want an agent to know about you, and run /soul-builder on a small data/ folder to judge the draft it produces.

Frequently asked questions

Official sources

1. aeonfun/soul.md on GitHub
2. Issues
3. License: MIT
4. Project website
5. README