Hi, I'm Lena. Something felt slightly off the first time I set up a SKILL.md file. Not wrong — just not quite what I expected. I'd read through the instructions, placed the file in the right directory, and *Claude picked it up. But then I started wondering: what exactly had I given it? Knowledge? A habit? Something could pass along?*
I've been sitting with that question for a while now. These are some observations.
What Are Claude Skills?
Claude skills are modular, reusable capability bundles — organized folders that give Claude agents domain-specific instructions, context, and optional scripts to work from. The core of each skill is a SKILL.md file.
If you're building with Claude Code or the Claude API, this is probably a pattern you've already encountered, or will soon.
How SKILL.md Works
Every skill lives in a directory. The SKILL.md file inside has two parts: a YAML frontmatter block at the top, and a markdown body below it.
The front matter is minimal. It tells Claude the skill's name and when to use it — a short description that Claude reads at startup. The markdown body is where the actual instructions live: what to do, how to format output, what edge cases to watch for, which supporting files to load.
At startup, the agent pre-loads the name and description of every installed skill into its system prompt. This metadata is the first level of progressive disclosure: it provides just enough information for Claude to know when each skill should be used, without loading all of it into context.
That part struck me as genuinely thoughtful. Claude doesn't read the whole skill file upfront — just the frontmatter. It loads more detail only when the skill becomes relevant. This means you can install many skills without constantly consuming context window capacity.
What Kinds of Behavior You Can Encode
Quite a range, actually. Skills can carry:
- Step-by-step procedural instructions — how to handle a particular file type, review pattern, or output format
- Domain conventions — naming standards, project-specific rules, preferred libraries
- Supporting files — templates, example outputs, Python scripts Claude can execute
- Conditional sub-documents — deeper reference files that only get loaded when Claude determines they're relevant
Skills prepare Claude to solve a problem, rather than solving it directly. This is fundamentally different from traditional tools, which execute and return results.
That distinction felt important to me. A skill doesn't run. It instructs. Claude still does the reasoning.
Setting Up and Using Claude Skills
File Location and Format
For personal use across all projects, skills go in claude skills. For project-level skills shared via Git, the path is claude skills. Each skill needs its own subdirectory, and inside that, a SKILL.md file.
The format itself is straightforward. Skills are simple to create — just a folder with a SKILL.md file containing YAML frontmatter and instructions. Anthropic's official skills repository on GitHub includes a template skill you can use as a starting point, along with the source-available document creation skills that power Claude's built-in PDF, Word, and PowerPoint handling.
How Claude Reads and Applies Skill Instructions
Once a skill is installed, Claude monitors incoming tasks and compares them against skill descriptions. When there's a match, it loads the SKILL.md content into context and follows the instructions from there.
You can also invoke skills manually with a slash command — skill-name — or let Claude decide automatically based on task context. Both modes work the same way under the hood.
I noticed something interesting here: when Claude uses a skill, it doesn't just "know" the instructions. It reads them fresh each time, like consulting a document. This has implications I'll come back to.
Where Claude Skills Work Well
Domain Knowledge and Project Conventions
This is probably where skills shine most clearly. If your team has particular coding standards, a preferred debugging flow, or specific output requirements, encoding those in a skill file means Claude applies them consistently — without you having to repeat the context every session.
I tested this a few times across different projects. The consistency was noticeably better than just relying on CLAUDE.md instructions or repeating myself in prompts. Claude reads the skill, follows it, and the output feels more predictable.
Consistent Output Formatting
For structured outputs — technical documents, code reviews, API documentation — skills work well as formatting contracts. You describe the expected structure, Claude loads it, and the output matches more reliably.
Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like invocation control, subagent execution, and dynamic context injection.
That cross-platform compatibility is worth noting. If you're building across multiple agent tools, the same SKILL.md format applies.
Where Claude Skills Hit a Ceiling
Here's where I started noticing something that felt slightly different from what I'd assumed going in.
Static Files vs. Dynamic Learning
A SKILL.md file is written by a human and saved to disk. It doesn't update itself. If Claude handles a task well using a skill, that success doesn't feed back into the skill file. The next session starts from the same static document.
You can ask Claude to capture its successful approaches and common mistakes into the skill — but it's a manual step. You initiate it. Claude doesn't do it on his own.
I'm not sure that's a flaw. It's more of a design boundary.
No Execution Feedback Loop
When Claude applies a skill and produces a result, there's no signal that flows back into the skill itself. There's no record of which instruction worked, which was ignored, which caused a problem. The skill has no memory of being used.
This matters more the longer you run agents in production. Patterns accumulate in your head — not in the file.
Skills Don't Persist Across Agents or Teams
Custom Skills are individual to each user; they are not shared organization-wide and cannot be centrally managed by admins.
So if one person on a team refines a skill based on months of use, that improved version doesn't automatically propagate to teammates. It stays local. Someone has to copy it, commit it, share it, and everyone has to update.
There's nothing broken about this. But it means skill improvements travel slowly, and the network of agents using the skill doesn't naturally converge toward better behavior over time.
From Static Skills to Inheritable Capability
What Reusable, Validated Capability Means Beyond SKILL.md
I've been thinking about what it would look like if the successful execution of a skill — a specific agent's successful run through a complex debugging sequence, say — could become something other agents could inherit directly. Not a copied file, but a verified solution with an audit trail.
Skills as they exist today are closer to onboarding documents. They're written once, based on someone's best current understanding, and distributed manually. That model works, and it works well for stable, well-understood domains.
But for teams running agents in production — agents that fail, recover, adapt — the gap between "what the skill says" and "what actually worked last week" can quietly widen.
When You Need Something That Evolves
The more I observe agent systems in real use, the more I notice that the hard part isn't encoding knowledge once. It's keeping it current. Skills solve the encoding problem. The currency problem is still open.
There are infrastructure-level approaches emerging that treat validated agent behaviors as shareable assets — not static files, but verified solutions with lineage. That's a different architecture than SKILL.md, and it raises different questions about trust and what "reuse" really means when agents are involved.
I don't fully understand where that line is yet.
Limits and Tradeoffs
To be clear about what I've observed:
Claude skills are genuinely useful. They reduce repetition, improve consistency, and make domain expertise portable across sessions. For individual developers and small teams, they're a meaningful improvement over ad hoc prompting.
The ceiling appears when you want capability that improves itself, travels across agents automatically, or accumulates evidence from real runs. That's not what SKILL.md was designed to do.
The tradeoff is simple: predictability vs. adaptability. Skills give you predictability. They don't — by design — give you an agent that learns from its own history.
FAQ
- What is a SKILL.md file in Claude Code?
A SKILL.md file is the core component of a Claude skill — a Markdown document with YAML frontmatter that provides Claude with domain-specific instructions, context, and metadata. It tells Claude when to apply the skill and what to do when it does. Skills leverage Claude's VM environment to provide capabilities beyond what's possible with prompts alone.
- How do Claude skills work?
Claude reads skill metadata at startup and loads the full instructions only when a relevant task is detected — or when you invoke the skill manually with a slash command. This progressive loading keeps context usage low. Supporting files within the skill directory are loaded on demand as Claude needs them.
- How do I create a custom skill for Claude Code?
Create a directory under .claude/skills/ in your project (or ~/.claude/skills/ for personal use). Add a SKILL.md file with YAML frontmatter containing name and description, followed by your markdown instructions. Claude will discover and apply the skill automatically when relevant. You can browse the Anthropic skills GitHub repository for templates and examples, or read the full Agent Skills documentation for setup guidance. For a deeper technical breakdown, Anthropic's engineering blog post on Agent Skills is worth reading carefully. If you're using the SDK, Agent Skills in the SDK covers how skill discovery and tool access work in that context.
- Are Claude skills the same as MCP tools?
Not quite — though I find myself confusing the two sometimes. MCP (Model Context Protocol) tools are external capabilities that Claude calls at runtime: file systems, databases, APIs, services. They execute and return results. Claude skills, by contrast, are instructional — they tell Claude how to behave or approach a task, rather than giving it a new tool to call. A skill might guide Claude through a code review process; an MCP tool might actually fetch the file being reviewed. They can work alongside each other, but they're solving different problems. One gives Claude access; the other gives Claude guidance.
- Can Claude skills be shared between projects?
Partially. Skills placed in ~/.claude/skills/ are personal and apply across all your projects on that machine. Skills placed in .claude/skills/ within a project directory are project-scoped and can be committed to Git — which means teammates who clone the repo get the same skills automatically. What doesn't happen is any kind of automatic sync or propagation beyond that. If you refine a skill in one project, that improvement doesn't flow anywhere on its own. Sharing is manual: copy, commit, distribute. For individuals and small teams working in the same repo, this works reasonably well. For larger organizations running multiple agent workflows across different environments, the friction starts to show.
*I'll keep watching how this space evolves. The gap between static instructions and self-updating agent capability feels like it's narrowing — slowly, and not always in obvious ways. Still not sure what to make of it yet.*See you next time.
