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 — and 2026 is the year that's really taking off — 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.

What This Actually Looks Like in Production

Most articles about these standards stop at theory. We use all three in production every day, so here's what the layered approach actually looks like.

Our main project is an intelligence hub — a system that processes research links, tracks 25+ projects, manages a content pipeline, and coordinates work across multiple machines. The CLAUDE.md file for this project is over 300 lines. Here's the structure (condensed):

# CLAUDE.md

## What This Is
A knowledge intelligence and project command center...

## Skills
| Skill        | Purpose |
|--------------|---------|
| /research    | Process a link through the full 8-step pipeline |
| /start       | Status report — project pulse, recommended focus |
| /atomize     | Turn a blog post into 10-15 social posts |
| /security    | Security audit — secrets, dependencies, permissions |

## The /research Pipeline
1. Timestamp & log
2. Fetch & understand (follow referenced links)
3. Analyze through 5 business lenses
4. Update knowledge base
5. Update docs (bookmarks, intelligence brief, people-to-watch)
6. Report to user
7. Mark processed
8. Log implementation ideas

## File Conventions
[Exact formats for every file type the agent reads/writes]

## Sensitive Data — NEVER Commit to GitHub
[Explicit rules for PII, API keys, file paths]

## Multi-Machine Setup
[Which machine owns which files, sync protocol]

That's the CLAUDE.md layer — purely operational. It tells the agent what this project is, what commands exist, what file formats to follow, and what never to do.

The SOUL.md layer sits alongside it. Our agent is configured to be skeptical and direct — it won't hype tools that aren't ready, it pushes back on bad ideas, and it assesses security and maturity before recommending anything. That personality stays consistent whether the agent is processing a research link, writing a blog post draft, or evaluating a new tool.

The SKILL.md layer adds depth. The /research skill alone contains the full 8-step pipeline — intake logging format, analysis lenses, file update rules, cross-referencing logic. The /atomize skill knows our brand voice, platform-specific formatting for X versus Facebook, and what makes a social post perform. Each skill is a folder with a SKILL.md file, and the agent loads them on demand.

The result: one command — /research https://example.com — and the agent reads the content, analyzes it through five business lenses, updates the right files in the right formats, cross-references against existing knowledge, and reports back. It knows the project conventions (CLAUDE.md), maintains a consistent analytical voice (SOUL.md), and follows a precise research methodology (SKILL.md). All three layers working together.

That's not hypothetical. That system has processed over 200 research links since January.

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. It takes 30 minutes to write a basic one. A good one — one that fundamentally changes how the agent operates in your project — takes a few hours and evolves over time.

Add SKILL.md for your repeatable processes. Our guide on how to package your business knowledge for AI walks through this step by step. 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.

Don't build all three at once. Start with CLAUDE.md. Use it for a week. Notice what's missing. Then add a skill for your most repeated workflow. Then add a SOUL.md when you care about the agent's voice. The layering emerges naturally from use — you don't need to architect it upfront.

The underlying trend here is worth paying attention to. AI agents are moving from "tools you prompt" to "colleagues you configure." For a look at how businesses are running entire teams of these configured agents, read how one-person companies are running like ten. 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.

Get Started Now

We've packaged starter templates for all three files into a free Agent Configuration Starter Kit — a CLAUDE.md template, a SOUL.md template, a SKILL.md folder with correct structure, and a one-page cheat sheet. Each template has commented instructions explaining every section.

Further Reading

• Inside Our 300-Line CLAUDE.md — a walkthrough of our actual production CLAUDE.md
• 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 — why SKILL.md matters for business discoverability
• How to Package Your Business Knowledge for AI — step-by-step guide to building your first skill

---

If you want your AI agents configured properly — identity, context, and skills — instead of running on defaults, get in touch.

Blue Octopus Technology sets up AI agent architectures that actually reflect how your business works. Learn more about our services.