We Write Better SKILL.md Files Than Job Descriptions

What even are skills anymore?

Everyone in AI-land is suddenly obsessed with skills.

Not skills the way HR means skills. Skills the way an agent means skills: a markdown file that spells out, with surprising precision, what the model should do when it encounters a task. Here’s when to use this. Here’s the input format. Here’s the expected output. Here’s the failure mode to avoid. A good SKILL.md is tight, composable, and testable. You can diff it. You can version it. You can A/B the phrasing and watch the agent’s behavior change downstream.

Which is funny, because on the human side of the same industry, we’ve been using the word “skills” for decades and mostly gotten away with it being vague.

“Strong communicator.” “Excellent executor.” “Analytical thinker.” “Owns outcomes.” These are the load-bearing phrases of every job description I’ve ever read. The more SKILL.md files I see in my day job, the more I notice how sloppy the human version of “skills” has always been.

Two definitions of skill, and only one of them is holding up

A SKILL.md is precise because it has to be. If you write “communicate clearly” in a markdown file for an agent, nothing happens. The model can’t do anything with that. You have to decompose it: clarify to whom, clarify in what format, clarify toward what decision. The work of writing a skill for an agent forces you to name the thing underneath the thing.

A job description does the opposite. “Excellent communicator” is doing so much unspecified work that nobody who reads it and nobody who writes it could tell you what’s actually being measured. It’s a container word. It means “the outputs this person produces tend to land well with other humans” but it’s also quietly standing in for a dozen underlying capabilities that were never named: reading the room, knowing what to leave out, sensing which stakeholder needs what framing, picking the right moment.

We got away with the vagueness because, until recently, the only way to produce the outputs was to have the underlying capabilities. If your Slack messages consistently landed well, you probably had pretty good situational awareness. The deliverable was evidence of the skill, and we could use the word “skills” loosely because the evidence chain was short.

AI just snapped that chain. The outputs are now cheap to produce. Clean emails, tight documents, competent first drafts of basically anything, can be generated without any of the underlying human capability that used to produce them. Which means the old container words don’t tell you anything anymore. “Strong communicator” in a 2020 JD meant something. “Strong communicator” in a 2026 JD is a question, not an answer.

The data is already moving

This isn’t just a vibes-based observation. The research is catching up.

McKinsey Global Institute published a report in January 2026 making a very similar point in different language: AI isn’t mostly substituting for what people do, it’s changing what people need to be good at. Their analysis found that more than 70% of the skills employers currently list in job postings apply to both automatable and non-automatable work. In other words, the way we describe skills doesn’t distinguish between the part the machine can do and the part it can’t. The vocabulary is blurry where it most needs to be sharp.

The WEF’s Future of Jobs 2025 report shows the same thing from the skills-demand side. The top five core skills employers now name as essential are analytical thinking, resilience and flexibility, leadership and social influence, creative thinking, and motivation and self-awareness. Communication — the item that leads almost every JD I’ve ever read — doesn’t make the list. Empathy and active listening sits at number seven.

The most useful framing I’ve seen comes from a 2025 MIT Sloan paper that proposed something called the EPOCH framework, which is centered around concepts related to Empathy, Presence, Opinion and judgment, Creativity, and Hope. One of the researchers said something that stuck with me: “We deliberately don’t call these ‘soft’ skills. A ‘hard’ skill, like solving a math problem, is comparatively easy to teach. It is much harder to teach a person these critical human skills and capabilities…”

That’s the inversion. For decades, we called this stuff soft. Soft as in squishy, soft as in hard-to-measure, soft as in nice-to-have after the real requirements. When the machines take over the “hard” skills, the so-called soft skills turn out to be the genuinely difficult ones. The ones that take a career to develop. The ones you cannot learn in a weekend course or from a YouTube playlist.

So what do we do with this

I think the JDs and competency frameworks we’ve been writing for the last twenty years are about to need the SKILL.md treatment. Not in the sense of literal markdown files, but in the sense of actually decomposing the thing you mean when you say someone is a “strong executor.” What specifically? Judgment under ambiguity? Prioritization when nothing is urgent but everything is important? The ability to ask one more clarifying question when everyone else is nodding along?

This feels like where the AI side and the people side start talking to each other. The discipline of writing a tight SKILL.md for an agent happens to be excellent practice for writing a tight skill definition for a human because in both cases you’re being forced to specify what was previously implicit.

The container words used to be enough. They covered the capabilities underneath because the capabilities and the outputs were so tightly coupled you could point at either and mean the same thing. They are decoupling now, quickly, and the words we’ve been using to describe valuable work haven’t caught up.

The evidence layer got cheap. The thing the evidence was pointing at is about to have to come out from hiding and name itself.