AGENTS.md is for your repo. self.md is for YOU.

by Ray Svitla

every serious AI coding tool now has a config file. CLAUDE.md tells claude code how to work in your repo. AGENTS.md does the same for openai’s codex. .cursorrules for cursor. the pattern is clear: a markdown file at the root that shapes how AI behaves in that context.

this makes sense for repositories. a codebase has conventions, a stack, a structure. the AI needs to know about it.

but here’s what nobody’s building: the same thing for people.

the gap

your repo has a CLAUDE.md that says “use TypeScript strict mode, test with vitest, deploy to vercel.” every AI agent that touches your code gets this context. it works better because of it.

you don’t have an equivalent for yourself. every new AI tool you use starts from zero: no idea how you think, what you value, what kind of advice actually helps you, what kind of advice you’ll ignore. every conversation begins with “I’m a developer working on…” like the AI has amnesia. because it does.

your CLAUDE.md follows your repo. nothing follows you.

what self.md is

self.md is a file. a markdown file that describes who you are — not your resume, not your bio, but how you think, what you value, what your tensions are, what kind of input you actually respond to.

# self.md

## how I think
- first-principles over best practices
- I need to understand WHY before I'll adopt HOW
- I distrust consensus — if everyone agrees, I look for what they're missing

## energy patterns
- deep focus 6am-11am, don't interrupt with admin tasks
- creative thinking after walks, not at desk
- I procrastinate when the problem is poorly defined, not when I'm lazy

## what works for me
- direct feedback, no sandwiching
- concrete examples over abstract frameworks
- deadlines I set myself, not imposed ones

## tensions I'm navigating
- autonomy vs structure: I want both and they fight
- depth vs breadth: I go deep on everything and it slows me down
- building vs shipping: I love the craft, the market doesn't care

this isn’t a personality quiz result. it’s not MBTI or enneagram. it’s a living document — you write it, you edit it, you own it. like code, it has versions. like a journal, it evolves.

why markdown

because markdown is portable. it works everywhere. it doesn’t lock you into a platform. no app store, no account, no subscription needed to read or write a .md file.

CLAUDE.md works because it’s just a file in your repo. any tool can read it. self.md works the same way — any AI tool can read it if you provide it. no special integration required. copy-paste into any chatbot, any agent, any tool. it’s text.

the format is the feature.

what changes when AI knows you

imagine every AI interaction starting with your self.md already loaded. not as a “custom instruction” buried in settings — as a protocol. the AI reads your self.md the way claude code reads your CLAUDE.md.

a coding session: the agent knows you prefer first-principles explanations, so when it suggests an architecture, it explains why, not just what. it knows you go deep, so it gives you the detailed version without being asked.

a research query: the AI knows you distrust consensus, so it leads with contrarian perspectives and minority viewpoints. it knows you need to understand WHY, so it gives reasoning, not just conclusions.

a coaching conversation: the AI knows your tensions — autonomy vs structure. it doesn’t give you generic productivity advice. it gives you advice that navigates the specific tradeoff you’re living.

this isn’t personalization. personalization is “we noticed you like dark mode.” this is identity — giving AI enough context to treat you as a specific person with specific patterns, not as a generic user.

the architecture

~/.self/
├── self.md          # who you are: values, patterns, tensions
├── catalog/         # what exists: philosophies, tools, approaches
├── routes.md        # how to match: identity → relevant catalog items
└── .journal/        # when things change: append-only evolution log

the file describes who you are. the catalog describes what’s available — philosophies, frameworks, tools, approaches. the routing layer matches your identity to relevant catalog items. the journal tracks how your self.md evolves over time.

the file is always free. always portable. always yours. you can burn it and still know who you are — it’s a mirror, not a crutch.

what this is NOT

it’s not another note-taking app. obsidian exists, logseq exists, notion exists. self.md isn’t about capturing information. it’s about expressing identity in a format AI agents can use.

it’s not custom instructions. custom instructions are locked to one platform. self.md is a protocol — it works anywhere because it’s just a file.

it’s not a personality test. tests categorize you. self.md describes you. the difference: categories are static and reductive. descriptions can hold contradictions, tensions, evolution.

it’s not a product (mostly). the file format is the product. you write it in any text editor. the intelligence layer on top — catalog matching, routing, suggestions — that’s where the business lives. but the file itself is yours, always.

the Illich test

ivan illich warned about tools that create dependency instead of autonomy. three health checks for self.md:

can you burn it and still know who you are? yes. the file describes what you already know about yourself. destroying it doesn’t destroy the knowledge. if you feel lost without it, something’s wrong.

does it ever make you uncomfortable? yes. the catalog should sometimes suggest approaches that challenge you. if it only confirms what you already believe, it’s a recommendation engine, not a growth tool.

does it serve you or a platform? it serves you. the file is portable, the format is open, and no vendor can lock it away. your identity doesn’t belong to anthropic or openai or anyone else.

AGENTS.md shaped your repo. self.md shapes your AI.

the pattern is the same. a text file that gives context to AI agents. one lives in your project directory. the other lives in your home directory. one makes AI better at writing your code. the other makes AI better at being useful to you.

your repo already has an instruction file. why don’t you?

→ AGENTS.md vs CLAUDE.md vs INSTRUCTIONS.md — the repo config landscape → why your CLAUDE.md sucks — writing good instruction files → context engineering — the principle behind both

Ray Svitla stay evolving