Hey, guys, Lena is here. Something shifted quietly in late 2025. I didn't notice it all at once — it came in slowly, the way most real changes do.
I'd been watching how Claude Code handled repeated tasks across projects. The pattern was familiar: the same instructions, rewritten slightly differently each time. The same context, re-explained. It started to feel like something was missing — not in the model, but in the layer between the model and the work.
That layer has a name now. It's called Claude Code Skills.
What Are Claude Code Skills?
At the simplest level, a Claude Code skill is a folder. Inside that folder lives a file called SKILL.md. When Claude Code encounters that folder, it reads the file, loads the instructions into context, and adjusts its behavior accordingly.
I keep returning to that description because it sounds almost too simple. And yet the implications — once you sit with them — are larger than they first appear.
Skills aren't prompts you paste at the start of every conversation. They're reusable behavioral packages that Claude discovers and applies automatically. You install it once. Claude picks up the context whenever it's relevant — without being reminded.
The SKILL.md Format — How It Works
Every skill starts with the same two-part structure. SKILL.md is a markdown file that follows a two-part structure — frontmatter and content. The frontmatter configures how the skill runs (permissions, model, metadata), while the markdown content tells Claude what to do.
A minimal example looks something like this:
---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---
# My Skill Name
[Instructions Claude will follow when this skill is active]
The name field becomes the slash command. The description field is what Claude reads when deciding whether to load the skill at all. The description is critical for skill selection — Claude uses it to choose the right skill from potentially 100+ available skills. Your description must provide enough detail for Claude to know when to select this skill, while the rest of SKILL.md provides the implementation details.
That last part is easy to underestimate. I got it wrong in my first few attempts — I wrote descriptions that were technically accurate but behaviorally vague. The skill would load at the wrong times, or not at all. The description isn't metadata. It's a routing decision.
You can read the official Claude Code Skills documentation for a full breakdown of the specification.
What Kinds of Behaviors You Can Encode
This is where it gets interesting. Skills aren't limited to text instructions. Each skill is a directory that can include a main SKILL.md file, templates for Claude to fill in, example outputs showing the expected format, and scripts Claude can execute.
In practice, that means you can encode:
- Coding conventions — how your team names functions, structures tests, handles errors
- Workflow patterns — multi-step processes Claude should follow when generating reports or processing files
- Executable scripts — validation logic, file transformations, external API calls that run deterministically
- Reference documents — detailed specs Claude reads on demand, without bloating every session
The key design insight: when a skill is triggered, Claude uses bash to read SKILL.md from the filesystem, bringing its instructions into the context window. If those instructions reference other files, Claude reads those too. When instructions mention executable scripts, Claude runs them and receives only the output — the script code itself never enters context.
That's a subtle but important point. The skill is lazy-loaded. You can bundle a 50-page reference document into a skill, and Claude will only pull what it actually needs.
Building Your First Claude Code Skill
I'll be honest — my first skill was bad. Not broken, just... imprecise. It loaded too broadly, its instructions competed with the conversation, and I spent more time explaining what I wanted than if I'd just typed it out.
Here's what I'd do differently.
File Placement and Format
For Claude Code, skills live in .claude/skills/ inside your project directory, or ~/.claude/skills/ for personal skills that apply globally. Claude Code supports only Custom Skills — create skills as directories with SKILL.md files.
The folder name becomes the skill's identity. Keep it lowercase, use hyphens. Inside:
my-skill/
├── SKILL.md ← required
├── examples/ ← optional but helpful
│ └── sample.md
└── scripts/ ← optional
└── validate.sh
The SKILL.md frontmatter requires two fields: name and description. The name field must use lowercase letters, numbers, and hyphens only. Always write the description in third person — the description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.
Testing That Your Skill Is Being Applied
This confused me at first. There's no explicit "skill loaded" notification in the interface. What I've found works: ask Claude directly. "What skills do you have access to?" usually surfaces the list. You can also check whether Claude's behavior changes on task-specific prompts that should trigger the skill.
The more reliable test is behavioral — run the same task with and without the skill active. If the output pattern shifts in the direction you encoded, the skill is working. Understanding the triggering mechanism helps design better skills. Skills appear in Claude's available skills list with their name and description, and Claude decides whether to consult a skill based on that description. Claude only consults skills for tasks it can't easily handle on its own — simple, one-step queries may not trigger a skill even if the description matches.
Common Mistakes in Skill Design
The Anthropic skill authoring best practices guide covers this well, but the errors I've seen most often:
- Vague descriptions — Claude can't route to a skill it doesn't understand precisely
- Overloaded SKILL.md — trying to encode everything in one file; use references for details
- No examples — skills without concrete examples produce inconsistent output
- Stale instructions — don't include information that will become outdated; version-specific instructions should be wrapped in collapsible sections or clearly dated
Sharing Skills Across Projects and Teams
Here's where things get genuinely useful — and also where the current limitations become visible.
Current Limitations of SKILL.md Sharing
Skills are file-based. That means sharing them requires file distribution: zip folders, Git repositories, manual copying. The current distribution model requires individual users to download the skill folder and place it in the Claude Code skills directory. Organization-level skills can be deployed workspace-wide by admins — this shipped in December 2025 — with automatic updates and centralized management.
That's a meaningful improvement. But it still means the skill lives as a static artifact. When the underlying workflow it encodes changes, the skill doesn't automatically update. Someone has to maintain it.
In December 2025, Anthropic released the Agent Skills specification as an open standard, and OpenAI adopted the same format for Codex CLI. Skills are model-invoked — the AI automatically decides when to use them based on context. That interoperability is real and valuable. A skill you build for Claude Code can, in principle, run in Cursor or other compatible environments. You can browse the Anthropic skills GitHub repository to see community-contributed examples.
What a Cross-Agent Sharing Layer Looks Like
This is the part I'm still trying to work out.
Right now, a skill is authored by a human, reviewed by a human, and distributed manually. The agent executes it but doesn't improve it. It doesn't learn from outcomes, doesn't propagate successful variants, doesn't flag when instructions have drifted from what actually works.
A genuine cross-agent sharing layer would need something more: execution validation, quality scoring, version lineage. The static SKILL.md captures intent well. It doesn't capture outcome.
I'm not sure I've seen that problem solved cleanly anywhere yet.
The Ceiling: Where Claude Code Skills Stop Working
Static Files vs. Adaptive Learning
Skills are instructions. They don't observe their own performance. If a skill encodes a debugging pattern that was effective six months ago but has since become less reliable due to model updates or API changes, the skill won't notice. You will — eventually.
Skills are living documents. Plan to iterate based on how they perform over time. That's good advice, but it places the iteration burden entirely on the author. The agent can't participate in improving the instruction it's following.
No Execution Validation, No Repair Loop
When a skill runs and the output is wrong, nothing in the skill mechanism catches that. Claude executes what the SKILL.md says. If the outcome doesn't match the intent, the loop doesn't close automatically.
This is less of a problem for skills encoding stable conventions (code style, document structure) and more of a problem for skills encoding dynamic workflows where correctness is task-dependent.
No Reuse Network
Skills today are either local (yours) or public (shared on GitHub). There's no ambient layer where a successful solution to a class of problem — tested, validated, version-tracked — becomes discoverable and inheritable by other agents working on similar problems.
The SkillsMP community marketplace is an early gesture in this direction. It's useful for discovering what others have built. But the skills it indexes are still static files. They don't carry audit records. They don't know how many times they've been applied, or with what results.
What Comes After Skills
From Static Instructions to Validated, Inheritable, Tradeable Capabilities
I've been sitting with this question for a while now.
Claude Code skills solve a real problem: they make agent behavior repeatable and transferable. That's not small. Before skills, context had to be re-established every session. Now it doesn't.
But a skill is still a human artifact. It captures what someone thought worked. It doesn't carry evidence of what actually worked, across what conditions, with what failure modes.
The next layer — whatever it becomes — probably looks less like a file format and more like a capability with provenance. Something that says: this approach was attempted in these conditions, succeeded at this rate, failed in these edge cases, was revised by these authors, and has been applied by these agents in comparable situations.
That's a different kind of infrastructure than a markdown file.
I'm still not sure what to make of that gap. It doesn't feel random, though. It feels like the next thing to watch.
FAQ
- What is a SKILL.md file in Claude Code?
SKILL.md contains the main instructions and is required for every Claude Code skill. It follows a two-part structure: YAML frontmatter that tells Claude when to use the skill, and markdown content with instructions Claude follows when the skill is invoked. Think of it as an onboarding document — except the agent never forgets it.
- How do I write a Claude Code skill?
Start with the frontmatter: name (lowercase, hyphens only) and description (third person, specific about when to invoke). Then write clear, imperative instructions in the markdown body. Add supporting files — examples, scripts, references — only when they genuinely improve behavior. Test by comparing task output with and without the skill active. See Anthropic's skill authoring best practices for detailed guidance.
- Can Claude Code skills be shared between team members?
Organization admins can deploy skills workspace-wide, with automatic updates and centralized management — this shipped in December 2025. For open-source sharing, GitHub is the current distribution channel. The Agent Skills open standard means skills built for Claude Code can also work in other compatible tools. Interoperability is real; a centralized reuse network with execution history is still an open problem.
I'll keep watching how this evolves. Something is happening here — I just don't fully see where it ends yet.
