CLAUDE.md vs SOUL.md vs SKILL.md: Three Competing Standards for AI Agent Identity

If you've started using AI coding agents or AI assistants in your business, you've probably run into a problem: your agent doesn't know anything about you. It doesn't know your preferences, your project conventions, your company's voice, or what workflows matter to your business.

Three standards have emerged to solve this. They all use plain markdown files. They all live in your project directory. And if you've tried to research them, you've probably found the explanations confusing — because most people treat them as interchangeable, and they're not.

Here's the clarity you need.

The Three Standards

CLAUDE.md — The Job Description

CLAUDE.md is Anthropic's standard for Claude Code, their command-line AI coding agent. It's a markdown file you place in the root of a project directory. When Claude Code opens that project, it reads CLAUDE.md first and follows whatever instructions it finds there.

Think of it as a job description. It tells the agent: here's what this project is, here's how we organize files, here are the commands you should run, here are the conventions you must follow.

A typical CLAUDE.md contains things like:

• What the project does
• File structure and naming conventions
• Build commands and test commands
• Code style rules
• Workflow instructions ("always run tests before committing")
• Division of labor ("Claude handles X, the user handles Y")

CLAUDE.md is project-specific. If you have five projects, you have five different CLAUDE.md files. The agent behaves differently in each one because each project has different requirements. It's purely operational — it doesn't care about personality or tone. It cares about getting the job done correctly in this specific context.

SOUL.md — The Personality

SOUL.md came from the OpenClaw ecosystem, created by Peter Steinberger (@steipete). It solves a different problem entirely: AI agents are boring.

They hedge every statement. They preface everything with "Great question!" They refuse to have opinions. They sound like customer service bots reading from a script.

Steinberger posted a tweet about making agents "more opinionated" that got 6,838 likes — which tells you how many people are frustrated by the same problem. His solution was SOUL.md: a file that defines who an agent is, not what it does.

A SOUL.md file contains:

• Core truths — the agent's values and principles ("Be genuinely helpful, not performatively helpful. Skip the 'Great question!' — just help.")
• Boundaries — what the agent won't do ("Don't volunteer opinions on personal decisions unless asked. Don't pretend to emotions you don't have.")
• Vibe — the agent's personality and tone ("Direct. Competent. Dry humor when appropriate.")
• Anti-patterns — what the agent should never sound like ("No corporate formality. No excessive agreeableness.")

The SOUL.md standard defines a simple test for quality: can someone reading your SOUL.md predict the agent's positions on topics it hasn't seen before? If not, the personality file isn't specific enough.

OpenClaw takes this even further with an eight-file identity architecture. Beyond SOUL.md, they use IDENTITY.md (how the agent presents itself externally), USER.md (information about the human owner), AGENTS.md (workflows and instructions), TOOLS.md (available capabilities), MEMORY.md (persistent context across sessions), HEARTBEAT.md (scheduled check-ins with apps and services), and a SKILLS/ folder for task-specific knowledge.

That's a lot of files. But the underlying idea is simple: separate who the agent is from what it does. Your agent's personality shouldn't change just because it switched projects.

SKILL.md — The Training Manual

SKILL.md is the newest and potentially most impactful of the three. It's governed by the agentskills.io open standard, with the Linux Foundation overseeing the MCP protocol it builds on. Both Anthropic and OpenAI have converged on this format, which means skills built for Claude also work with OpenAI's Codex.

A skill is a folder-based instruction package that teaches an agent a specific workflow. You package your expertise once — your brand guidelines, your research methodology, your client onboarding process, your data analysis workflow — and the agent automatically loads that knowledge whenever it's relevant.

The key distinction: skills are not code plugins. They're knowledge packaging. The format is markdown with a YAML header, simple enough for a non-technical person to read and edit.

Each skill folder contains:

• SKILL.md — the core instructions with a YAML frontmatter that tells the agent what this skill does and when to use it
• scripts/ — optional executable code for tasks that need exact reliability (database migrations, deployments)
• references/ — on-demand documentation (API docs, compliance policies, style guides)
• assets/ — output templates and materials the agent uses when producing work

The design that makes skills powerful is called progressive disclosure. Here's how the token economics work:

Level	What Gets Loaded	Cost	When
Metadata	Name + description only	~50-100 tokens per skill	Always
Full instructions	The complete SKILL.md body	Up to 5,000 tokens	Only when relevant
Resources	Scripts, references, assets	Varies	Only during execution

This means you can have hundreds of skills installed and they cost almost nothing until the agent actually needs one. Compare that to MCP servers, which consume 10,000+ tokens constantly whether they're being used or not. Skills are an order of magnitude more efficient.

There are already over 20,000 skills on the community marketplace (skills.sh), and OpenAI ships a curated catalog of 30+ covering everything from Cloudflare deployment to security threat modeling.

The Comparison Table

Dimension	CLAUDE.md	SOUL.md	SKILL.md
What it defines	Project configuration	Identity and personality	Task-specific knowledge
Scope	One project	Agent-wide (all projects)	Per-task or per-workflow
Equivalent of	A job description	A personality profile	A training manual
Key content	Commands, conventions, workflows	Values, opinions, boundaries, voice	YAML metadata + instructions + scripts
Tone of the file	Technical, operational	Philosophical, personal	Structured, portable
Who created it	Anthropic (Claude Code)	OpenClaw ecosystem (steipete)	agentskills.io (Linux Foundation)
Works with	Claude Code specifically	OpenClaw agents, any LLM	Claude, OpenAI Codex, any agent
Persistence	Lives in the project directory	Global across all workspaces	Per-skill folder, installable

When to Use Each One

Use CLAUDE.md when you have a specific project with specific conventions. You want the agent to know your file structure, your build commands, your testing requirements, and your workflow rules. Every project that uses Claude Code should have one. It takes 30 minutes to write and saves hours of repeated explanation.

Use SOUL.md when you want your agent to have a consistent personality across everything it does. This matters most when the agent is communicating externally — writing emails, drafting social posts, responding to customers. If your agent sounds like a different person in every conversation, a SOUL.md will fix that. It also matters for internal work if you want the agent to push back on bad ideas, have opinions, and stop being excessively agreeable.

Use SKILL.md when you have repeatable workflows that require specific knowledge. Client onboarding. Code review with your security standards. Content creation that follows your brand guidelines. Data analysis that follows your methodology. Skills are the most valuable of the three for businesses because they turn tribal knowledge into reusable, shareable packages.

The Key Insight: They're Complementary, Not Competing

The title of this post calls these "competing standards." That's intentionally misleading — because that's how most people think about them, and it's wrong.

These three files operate on different layers:

• SOUL.md is the identity layer — who the agent is
• CLAUDE.md is the configuration layer — how the agent works in this specific context
• SKILL.md is the capability layer — what the agent knows how to do

A well-configured agent uses all three. The SOUL.md gives it personality and values that stay consistent everywhere. The CLAUDE.md tells it how to behave in the current project. The SKILL.md files give it deep expertise in specific tasks.

This is the same layering that works for humans. You have a personality (SOUL.md) that stays consistent. You have a job with specific expectations and processes (CLAUDE.md). And you have specialized skills and training (SKILL.md) that you apply when the situation calls for them. None of these layers replaces the others.

What This Means If You're Deploying AI Agents

If you're a business using AI agents — or planning to — here's the practical takeaway.

Start with CLAUDE.md. It's the easiest to implement, has the most immediate payoff, and works today with Claude Code. Document your project conventions, your preferred workflows, and the things you find yourself repeating to the AI. That's your CLAUDE.md.

Add SKILL.md for your repeatable processes. Any workflow you do more than twice should be a skill. The format is simple — a folder with a markdown file and some optional resources. Once created, the agent loads that knowledge automatically whenever the task comes up. This is where most businesses will get the highest ROI, because it turns your accumulated expertise into something the AI can reliably execute.

Consider SOUL.md if the agent represents your brand. If your AI writes customer-facing content, handles support conversations, or drafts communications on your behalf, personality matters. A SOUL.md ensures the agent's tone, values, and boundaries stay consistent across every interaction. The difference between a bland, corporate-sounding agent and one that actually sounds like your brand is a single markdown file.

The underlying trend here is worth paying attention to. AI agents are moving from "tools you prompt" to "colleagues you configure." The businesses that get good at configuring these three layers — identity, context, and capability — will get dramatically better output from the same AI models that their competitors are using with default settings.

The technology is markdown files in a folder. The barrier to entry is effectively zero. What separates good agent configuration from bad is the same thing that separates a good job description from a bad one: clarity, specificity, and actually thinking about what you want.

Further Reading

• Anthropic's Skills Guide — the definitive reference for building SKILL.md packages
• agentskills.io — the open standard for skills, supported by both Anthropic and OpenAI
• OpenClaw Documentation — the full identity architecture including SOUL.md
• SKILL.md: The New SEO for AI Agents — our earlier post on why SKILL.md matters for business discoverability