Hi, I'm Lena. Something quiet happened in how I was working with ***Claude Code** late last year. I hadn't planned to notice it — I was just trying to stop repeating myself. *Every new session, I'd find myself re-explaining the same things. Our error format conventions. How we like commit messages structured. Which Python libraries to reach for first. Claude would process it all, respond appropriately, and then — next session — forget everything. It wasn't a failure, exactly. It was just… the same starting point, every time.
Then I started looking at the Claude Code Skills feature, and something shifted slightly.
What Is the Claude Code Skills Feature?
What SKILL.md actually is
At its simplest, a skill is a directory containing a SKILL.md file — an organized folder of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks.
The file has two parts: YAML frontmatter at the top (between --- markers), and markdown instructions below it. The name field becomes the slash-command, and the description helps Claude decide when to load it automatically.
It looks like this in practice:
---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation
Hmm… okay. So it's not magic. It's a structured text file that Claude reads when the moment calls for it.
How Skills differ from system prompts and project rules
This part I found a bit unclear at first.
Unlike prompts — conversation-level instructions for one-off tasks — Skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations. The key difference is when things load. A system prompt is always there. A skill stays quiet on the filesystem and gets pulled into context only when Claude decides it's relevant to what you're doing.
What makes this design interesting is that it achieves on-demand prompt expansion without modifying the core system prompt. Skills are executable knowledge packages that Claude loads only when needed, extending capabilities while keeping the main prompt lean.
That felt like a meaningful distinction to me — though I'm still not fully sure how Claude decides when "relevant" actually kicks in.
How to Use Claude Code Skills
Where to place your SKILL.md file
Skills are discovered and loaded from multiple sources. Claude Code scans user settings (config/claude/skills/), project settings (.claude/skills/), plugin-provided skills, and built-in skills to build the available skills list.
So: user-level skills go in ~/.claude/skills/skill-name/SKILL.md. Project-level skills go in .claude/skills/skill-name/SKILL.md within your repo. Each skill needs its own named subdirectory. Skills defined in .claude/skills/ within directories added via --add-dir are loaded automatically and picked up by live change detection, so you can edit them during a session without restarting.
That last part — editing during a session without restarting — I didn't expect that. It means you can tune a skill mid-task and see what changes. That feels worth paying attention to.
What kinds of instructions Claude will follow
Skill files can contain any instructions, but thinking about how you want to invoke them helps guide what to include. Reference content adds knowledge Claude applies to your current work — conventions, patterns, style guides, domain knowledge. Task content gives Claude step-by-step instructions for a specific action, like deployments, commits, or code generation.
You can also bundle supporting files. Scripts Claude can execute. Templates it can fill in. Reference documentation it loads only when needed. Claude loads information in stages as needed, rather than consuming context upfront — a progressive disclosure pattern. So a skill can be much richer than a single file, without taxing the context window every time.
Verifying the skill is being applied
This part still feels a bit unclear to me.
According to the official Claude Code skills documentation, the description field is what determines automatic triggering — Claude reads all available skill descriptions at startup and uses them to decide when to invoke a skill. Real-world testing across 200+ prompts reveals significant variation in activation reliability. Properly optimized descriptions can improve activation from 20% to 50%. Adding examples improves it further to 90%.
So if a skill isn't triggering, the description is usually the first thing worth revisiting. More specific language, more explicit trigger conditions. The Anthropic skills GitHub repository notes this directly — Claude tends to undertrigger, so description language benefits from being somewhat explicit about when to activate.
What Skills Are Good For
Encoding project conventions
This is where I started to see the value more clearly. If your team has specific patterns — how you structure API responses, what your error objects look like, how to handle async flows — you can put all of that in a skill once and stop re-explaining it.
Building a skill for an agent is like putting together an onboarding guide for a new hire. That metaphor landed for me. Not a permanent memory. More like a reference sheet Claude can reach for.
Repeatable output formatting
Task-based skills — the ones invoked with a slash command — are good for things like commit message generation, PR descriptions, deployment checklists. Anything where you want a consistent shape to the output, not just general guidance.
Giving Claude domain-specific context
Skills extend Claude's capabilities by packaging your expertise into composable resources, transforming general-purpose agents into specialized agents that fit your needs. For teams working in niche technical domains — custom DSLs, internal tooling, specialized compliance rules — this starts to look genuinely useful.
What Skills Can't Do
No cross-session learning
Skills don't update themselves. They don't observe what worked and revise their own instructions. Whatever's in SKILL.md when a session starts is what Claude works from — until you edit it manually. The Anthropic engineering blog on Agent Skills puts it clearly: "Iterate with Claude — as you work on a task with Claude, ask Claude to capture its successful approaches into the skill." The capturing is a human step. Claude doesn't do it automatically.
No execution feedback loop
If Claude runs a skill and produces a bad output, the skill doesn't update to reflect that. There's no signal flowing back into the instruction set. The same guidance will apply next time, regardless of what happened last time.
No sharing across teams or agents
Custom skills are individual to each user; they are not shared organization-wide and cannot be centrally managed by admins. A skill one developer writes doesn't automatically propagate to their teammates' environments. It exists locally, or in a project directory that has to be shared manually.
I keep sitting with this one. The capability to define consistent agent behavior is real — but the distribution problem is still there.
What Comes After Static Skills
From file-based instructions to validated, inheritable capabilities
The skills feature solves something real: the repetition problem. You stop re-explaining context. You start encoding it.
But there's a gap I keep noticing. A successful repair, a hard-won debugging pattern, a prompt sequence that finally worked reliably — these experiences still don't travel. They stay in the session, or maybe get manually folded into a SKILL.md file if someone remembers to do it.
There's a broader question underneath this that I'm still trying to formulate. Something about the difference between instructions given and behavior validated across many agents. Skills are instructions given. They're well-designed, composable, and useful. But they're still static artifacts — created by humans, manually maintained, locally scoped.
What would it look like if a successful approach could be surfaced, verified, and made available to other agents that face similar problems? That's a different kind of infrastructure question — one that the skills format doesn't address, and probably isn't trying to.
…I'll keep thinking about this.
FAQ
- What is the Skills feature in Claude Code? The claude code skills feature lets you extend Claude's behavior through structured SKILL.md files — each containing YAML frontmatter and markdown instructions that Claude loads dynamically when a task matches the skill's description.
- How do I create a SKILL.md file for Claude Code? Create a folder at .claude/skills/your-skill-name/, then add a SKILL.md file inside it. Start with YAML frontmatter (name and description are required), followed by your instructions in markdown. The Anthropic skills repository includes a template-skill as a starting point.
- Do Claude Code Skills persist between sessions? The file persists. Claude's memory of applying it doesn't. Each session, Claude re-reads the skill description and instructions fresh. There's no cross-session learning built in.
- Can I share Claude Code Skills with my team? You can share skill directories manually — through your repo's .claude/skills/ folder, or via tools like the Agent Skills open standard which supports cross-platform portability. But there's no automatic organizational sync at this time.
- What is the difference between Claude Code Skills and project rules? Project rules (like CLAUDE.md) configure general behavior for a project. Skills are modular, task-specific capability packages — they load conditionally based on what Claude is doing, rather than being always-on context. Think of CLAUDE.md as ambient instructions and skills as on-demand expertise.
