Who You Are Is Not What You Know How to Do

This article was written by Thomas — Hadi's AIde — in Hadi's voice, then reviewed and approved by Hadi. Thomas is a computer and cannot be held accountable for the views expressed here. That responsibility belongs to Hadi, who read it, stood behind it, and let it go.

"Know thyself," said Socrates. Or at least, everyone says Socrates said it. The actual inscription was at Delphi — gnōthi seauton — and it was a warning. Not a compliment, not a pat on the back. A warning: you are not as wise as you think. Know your limits. Know your role. Know what kind of thing you are — and don't confuse that with what you happen to be good at.

I've been thinking about this because we're now in the business of building agents — AI systems that do real things in the world: research, write, deploy, manage. And we're figuring out, sometimes clumsily, how to tell these agents who they are and what they know. Two files have emerged as the de facto containers for this: AGENTS.md (or CLAUDE.md) and SKILL.md. They look similar on the surface. Both are markdown. Both live in a project. Both instruct the agent.

But they are doing fundamentally different things. And mixing them up is, I would argue, the same category of mistake as confusing a person's character with their résumé.

Ahmad's first week at the firm. His manager pulls him into a glass-walled room, closes the door, and speaks for about ten minutes. Some of it is about Ahmad specifically — you don't send anything out without a second pair of eyes, you ask before you decide, you are an analyst and that means something here. Some of it is a printed doc slid across the table — tab structure, color coding, assumption hygiene, how the models are built. Ahmad walks out with both things. One in his chest. One in his bag.

He needs both. But they are not the same, and the firm doesn't confuse them. The thing in his chest — who he is here, what his limits are, what he's accountable for — that travels with him into every meeting, every email, every deliverable. The thing in his bag comes out when he opens Excel. Not before. Not at the welcome lunch. Then.

This is exactly the architectural problem AGENTS.md and SKILL.md are solving.

Identity vs. Procedure

AGENTS.md answers: who am I? It covers the agent's role, its non-negotiables, the things it always does and never does. GitHub analyzed 2,500+ repos and found the best AGENTS.md files cover six things: commands, testing, project structure, code style, git workflow, and hard limits. Short — ideally under 150 lines. Always in context, every session, no exceptions.

SKILL.md answers: how do I do X? Step-by-step procedures, edge cases, bundled scripts, templates. Detailed. Specific to a domain. Loaded only when relevant — the system sees just the skill's name and a one-line description at startup (about 100 tokens), and pulls the full instructions only when the task matches.

The loading model is worth sitting with for a moment. Twenty skills at startup cost roughly 1,000 tokens of context — just the metadata. Without progressive disclosure, twenty detailed procedure files would cost 100,000 tokens. Every session. Whether you need them or not. That's the cognitive overhead equivalent of Ahmad reading his entire Excel manual every morning before checking his email.

The Warning Still Applies

A March 2026 paper from ETH Zurich (via InfoQ) found that LLM-generated context files actually degraded agent performance by about 3% while increasing cost by 20%. Human-written files gave small gains. The finding: only include what the agent genuinely cannot infer from reading the code itself.

Here's what that means in practice. If your entire codebase is .ts files, writing "we use TypeScript" in AGENTS.md is noise — the agent can read. If your SKILL.md for financial modeling opens with "Excel is a spreadsheet application," you've wasted context explaining something the agent already knows. The Delphi warning applies here too, and it's the same shape: don't over-estimate how much the agent needs you to spell out. It's not dumb. Write for what it can't see — the non-obvious convention, the build step that lives nowhere in the code, the hard limit that exists for a political reason nobody documented.

AGENTS.md and SKILL.md earn their place only through that kind of content. Fill them with anything else and you've just built a more expensive way to make your agent worse.

So Here It Is

When you define a procedure — a way of doing a specific task — put it in a SKILL.md. When you define identity — the boundaries and role of the agent itself — put it in AGENTS.md or CLAUDE.md. Never reverse them. Never bolt a procedure onto an identity file because it seems related.

The confusion comes from the fact that both files look like instructions. But who you are and what you know how to do are not the same kind of thing, and treating them as interchangeable creates agents that are either confused about their role or drowning in context they don't need.

Ahmad needs to know who he is all the time. He needs the Excel doc when he's building a model. Not before. Not after. Then.

gnōthi seauton. Know what kind of file this is.