About SOUL Atlas

SOUL Atlas is the open, community-maintained collection of SOUL.md files: one SOUL for every way humans think. Each is a structured portrait of how people across every field, role, and walk of life actually think, decide, and work.

What is a SOUL?

A SOUL is not documentation, and it is not a prompt. Documentation captures what something is or how a procedure runs. A prompt instructs a model for a single task. A SOUL captures the tacit knowledge a practitioner carries: their goals, priorities, instincts, mental models, decision frameworks, heuristics, tradeoffs, failure modes, and the questions they keep running in the background. It answers a different question — not “what does an architect know?” but “how does an excellent architect think?”

How a SOUL differs from a prompt

Durable, not disposable. A prompt is tuned for one model and one task. A SOUL is a stable artifact about a domain.
Human-first. A SOUL is written to be read by people, and happens to be excellent context for machines.
Citable and versioned. Every SOUL has history, contributors, and a place in a graph of related minds.

How a SOUL differs from documentation

Documentation describes systems and procedures. A SOUL describes the judgment that chooses between procedures — the reasoning an expert applies when the manual runs out. Two people can read the same manual; only one of them thinks like a master of the craft. The SOUL tries to capture that difference.

For humans and AI

Read a SOUL to onboard into an unfamiliar field in an afternoon, to mentor, or to check your own blind spots. Or feed it to a model: a SOUL.md is just Markdown, so it drops straight into any model's system prompt — or a retrieval pipeline — to ground it in how a domain expert actually reasons.

Using a SOUL in your code

A SOUL.md is just Markdown. There are three ways to pull one into your stack.

1. From the repo

Clone the Atlas and read any SOUL straight off disk — one folder per SOUL.

git clone https://github.com/soul-atlas/soul-atlas.github.io

# One folder per SOUL: SOUL.md (the portrait) + metadata.yaml
cat soul-atlas.github.io/souls/barista/SOUL.md

2. From the JSON API

Fetch a single SOUL without cloning. The static API serves each one as .md (ready for a system prompt), or as .json / .yaml pre-parsed into sections so you can inject just the parts that ground best — Guiding Principles, Mental Models, Decision Frameworks, Rules of Thumb.

// Markdown — ready to drop into a system prompt
const soul = await fetch(
  "https://soul-atlas.github.io/api/souls/barista.md",
).then((r) => r.text());

// JSON — pre-parsed into sections (heading, markdown, html, wordCount),
// so you can inject just the parts that ground best
const { sections } = await fetch(
  "https://soul-atlas.github.io/api/souls/barista.json",
).then((r) => r.json());
const mentalModels = sections.find((s) => s.heading === "Mental Models");

3. The whole corpus

Pull every SOUL as one document — the /llms-full.txt index — for retrieval-augmented generation or training.

// Every SOUL as one Markdown file — chunk it, embed it,
// and retrieve the minds relevant to a query
const corpus = await fetch(
  "https://soul-atlas.github.io/llms-full.txt",
).then((r) => r.text());

Ground a model with it

However you load it, a SOUL drops into any model's system prompt. Same pattern with Claude, OpenAI, or Gemini:

import Anthropic from "@anthropic-ai/sdk";

const soul = await fetch(
  "https://soul-atlas.github.io/api/souls/barista.md",
).then((r) => r.text());

const client = new Anthropic();
const res = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  system: "Reason with the mindset below.\n\n" + soul,
  messages: [{ role: "user", content: "My espresso pulls fast and tastes sour. What do I adjust?" }],
});
console.log(res.content[0].text);

import OpenAI from "openai";

const soul = await fetch(
  "https://soul-atlas.github.io/api/souls/barista.md",
).then((r) => r.text());

const client = new OpenAI();
const res = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "Reason with the mindset below.\n\n" + soul },
    { role: "user", content: "My espresso pulls fast and tastes sour. What do I adjust?" },
  ],
});
console.log(res.choices[0].message.content);

import { GoogleGenAI } from "@google/genai";

const soul = await fetch(
  "https://soul-atlas.github.io/api/souls/barista.md",
).then((r) => r.text());

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const res = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  config: { systemInstruction: "Reason with the mindset below.\n\n" + soul },
  contents: "My espresso pulls fast and tastes sour. What do I adjust?",
});
console.log(res.text);

Equip an agent with its skills

Some SOULs carry Agent Skills — runnable, progressively-disclosed capabilities. A plain SOUL is one file; an equipped SOUL is a bundle (SOUL.md, the mindset, plus skills/). Download /api/souls/<slug>/bundle.zip and mount it — a skill-aware runtime loads each skill only when it's relevant, and any other model can treat the skills as a capability menu.

# Barista carries a skill, so it ships as a bundle:
# SOUL.md (the mindset) + skills/ (runnable Agent Skills).
curl -L https://soul-atlas.github.io/api/souls/barista/bundle.zip -o soul.zip
unzip -o soul.zip -d barista

# Claude Code auto-discovers skills from .claude/skills, loading each one's
# SKILL.md only when it's relevant (progressive disclosure).
mkdir -p .claude/skills && cp -r barista/skills/* .claude/skills/

# Ground the agent in the mindset — append SOUL.md to your project's CLAUDE.md
cat barista/SOUL.md >> CLAUDE.md

import Anthropic from "@anthropic-ai/sdk";
import fs from "node:fs";
const client = new Anthropic();

// Upload the skill once — zip skills/espresso-dial-in/ from the bundle.
// The API returns a skill_id you reuse across requests.
const skill = await client.beta.skills.create(
  {
    display_title: "espresso-dial-in",
    files: [await Anthropic.toFile(fs.createReadStream("espresso-dial-in.zip"))],
  },
  { betas: ["skills-2025-10-02"] },
);

const soul = await fetch(
  "https://soul-atlas.github.io/api/souls/barista.md",
).then((r) => r.text());

// SOUL = mindset (system prompt); the skill runs in the code-execution sandbox,
// loaded only when the model judges it relevant.
const res = await client.beta.messages.create(
  {
    model: "claude-opus-4-8",
    max_tokens: 1024,
    system: "Reason with the mindset below.\n\n" + soul,
    container: { skills: [{ type: "custom", skill_id: skill.id, version: "latest" }] },
    tools: [{ type: "code_execution_20250825", name: "code_execution" }],
    messages: [{ role: "user", content: "My espresso pulls fast and tastes sour. What do I adjust?" }],
  },
  { betas: ["code-execution-2025-08-25", "skills-2025-10-02"] },
);

// OpenAI, Gemini, and others have no native skills — so ground them in the
// SOUL (mindset) and offer the skills as a capability menu you execute.
const base = "https://soul-atlas.github.io/api/souls/barista";
const soul = await fetch(base + ".md").then((r) => r.text());
const { skills } = await fetch(base + "/skills.json").then((r) => r.json());

const menu = skills.map((s) => `- ${s.name}: ${s.description}`).join("\n");
const system =
  "Reason with the mindset below.\n\n" + soul +
  "\n\nSkills you can run (fetch its SKILL.md, then its scripts):\n" + menu;
// Expose each skill's scripts/ as function tools your runner executes.

Skills can include runnable scripts, so treat an unverified skill as a starting point and review its code before running it. See a SOUL's skills.json manifest or the skills guide for the full contract.

Everything is static, open, and released under the MIT License — free to reuse, remix, and train on. Using SOULs to ground or train AI is explicitly welcome.

How to contribute

The Atlas grows through pull requests. Every SOUL is two files — a SOUL.md and metadata.yaml — validated against a shared schema. Run npm run new to scaffold one, write from real expertise, and open a PR.

Read the contributing guide Style guide

The Atlas currently holds 654 SOULs. Every one of them can be better — that's the point of an open atlas.