Claude Code skills went from a feature announcement to a search term people type on their own within a few months. The pattern behind that is familiar: a mechanism ships, tutorials explain how to build one, a marketplace forms around sharing them, and the coverage stops right there, at "here's how you package a skill," without asking what a skill is still missing once an agent has actually run one.
What a Claude Code skill is, and how it differs from a system prompt
A skill is a folder, not a prompt pasted into a chat. At minimum it holds one file, SKILL.md, with YAML frontmatter between --- markers and a markdown body underneath. The frontmatter's two fields that matter most are name, which has to match the folder it lives in, and description, the string Claude actually reads to decide whether this skill is relevant to the task in front of it. Optional fields narrow things further: allowed-tools restricts what a skill may touch once active, disable-model-invocation controls whether the model can trigger it on its own or a person has to invoke it directly. The body is where the actual method goes, the steps, the conventions, the checklist, whatever a team wants every agent to follow the same way.
That's a meaningfully different object from a system prompt or a one-off instruction typed into a session. A system prompt is global and always loaded. A skill is discovered, scoped to a description match, and can carry its own scripts and reference files alongside the markdown, documented in full in Claude Code's own skills reference. It's closer to a function the agent can call when the task matches than to a paragraph of standing context.
Why skills spread fast: shared, versioned, marketplace-ready
The packaging is the whole point. A skill is a directory, which means it's a thing a team can put in version control, diff, review, and ship the same way it ships code. anthropic/skills is the public repository Anthropic itself publishes as a reference set. Beyond that there's no single official storefront: skills circulate through the Claude Code plugin marketplace primitive, through community catalogs, and through teams simply committing a .claude/skills/ directory to their own repo and pulling it in on every clone. That's a lower floor than most extension ecosystems set, no proprietary registry to publish to, no approval queue, just a folder with the right two frontmatter fields.
A format every agent in a project reads for free, with the folder itself as the unit of sharing, was always going to spread past a single team. What's new isn't the idea of packaging instructions, teams have done that with README files and wikis for years, it's that the packaging is now something the agent parses and activates on its own, mid-session, based on what the task actually needs.
Instruction file versus session record, again
This is the same distinction AGENTS.md runs into, applied to a more specific and more recently shipped mechanism. A skill is read before, or during, a task to shape how the agent approaches it. It's input. Once the session ends, the SKILL.md file hasn't changed, it still says exactly what it said before the agent opened it, because it describes a method, not a run. A team with a sharp, well-versioned skill and a team with a sloppy one both hit the same wall the moment someone asks what happened in a specific session: neither file answers that question, because neither was built to.
Skills actually widen the gap slightly compared to a plain instruction file, precisely because they're more powerful. A skill with allowed-tools set narrowly, bundled scripts, and a description tuned to trigger automatically is doing real work mid-session, deciding what the agent reaches for and how it reaches for it. That makes the question of what a specific run actually did with a specific skill version more consequential, not less, and the mechanism has no field for answering it.
What a skill cannot tell you after the agent runs it
Take a team that gets this right: a lean SKILL.md, a tight description that triggers only when it should, allowed-tools scoped to exactly what the method needs, versioned in git alongside the code it touches. That team still can't hand a client or an auditor an object that says, for this specific task, which skill fired, which version of it, what the agent actually did with the tools it was allowed, and who reviewed the result before it shipped. The skill file, however well written, answers a different question: what should happen when this kind of task comes up, for every session that will ever match the description, not what happened in the one that just ran.
It's the same gap Claude Code's hooks get partway toward closing from a different angle, hooks intercept the raw event as it happens rather than describing intended behavior in advance, but interception still isn't a signed record naming the task, the skill version, and the person who authorized it. A skill sits upstream of the session, same as an instruction file does; a hook sits inside it, watching. Neither one, on its own, is downstream of the session, looking back at it with a signature attached.
What a software house should log alongside its skills
Write the skill, keep the description tight enough that it fires only when it should, and treat the folder like the reusable, versioned asset it's designed to be, that's genuinely useful discipline, not wasted effort. What it doesn't replace is a separate record, per delivery: which skill version was active for this task, what the agent actually did with the tools that skill unlocked, and a human signature on the result before a client sees it, the layer that sits above the agent's own configuration, not inside it. A shared skill makes every agent on a team start from the same method. It was never going to be the object that proves, after the fact, that the method was actually followed on the one run that mattered.