Claude Agent Skills: Teaching Your AI Agent to Wear Multiple Hats
Episode #45: How to teach Claude specialized capabilities without bloating your prompts
Here’s a situation you might recognise: You want an AI agent that can help you with both Kubernetes troubleshooting AND Python development. So you load it with docs for both. Add some guidelines for how to approach each. Throw in examples, templates, edge cases. Before you know it, your system prompt is thousands of tokens. It becomes a bloated mess that confuses more than it clarifies.
This is the fundamental problem with how we traditionally extend AI agents: prompt stuffing. We take everything the agent might ever need and cram it into system prompts or CLAUDE.md files. The result? Higher costs, slower inference, maintenance headaches, and an agent that struggles to apply the proper context at the right time.
Claude Agent Skills solves this by flipping the approach entirely. Instead of loading everything upfront, skills use progressive context loading: the agent gets just enough information to decide if it needs a skill, then loads only what’s relevant when it’s needed.
This article introduces Claude Agent Skills: what they are, how they work, and why they’re a game changer for anyone building with AI.
How to Interact with Claude
Before diving into skills, let’s quickly map the landscape of ways to extend Claude:
Slash Commands (/commands) are saved user prompts. They provide quick automation for tasks you run manually and are great for repetitive workflows you already know you need.
Output Styles are saved system prompts that change how Claude formats responses and behaves.
MCPs (Model Context Protocol) have been getting a lot of hype lately. Every company rushed to write them. But here’s the reality: MCPs are powerful but complex. Learn more at modelcontextprotocol.io.
Claude Agent Skills are the focus of this article. They combine Markdown-based instructions with optional Python code, designed for complex workflows and automatic invocation.
Claude Agent Skills: Wearing Different Hats
Imagine an agent as a person with multiple jobs. One day, they’re a system designer. Next, they’re a code reviewer. Then they’re a documentation specialist. A single Claude instance can do all of this. You need to teach it how, one skill at a time.
That’s what Claude Agent Skills do. They let you extend Claude with specialised capabilities without rebuilding the entire agent. To understand the deeper architecture and design patterns, read Anthropic’s Equipping Agents for the Real World with Agent Skills article. It explains the reasoning behind how skills are structured.
The Structure of a Skill
A skill is surprisingly simple. It’s just a folder under .claude/skills/ that contains:
A SKILL.md file: Markdown-based instructions (required)
Optional reference files: Detailed guides, templates, examples
Optional Python code: Logic that executes when needed
The reference files, docs, and code can be organised however you want, as long as they’re referenced in the SKILL.md. Claude will find them. For a deeper dive into the technical setup and how to manage skills in Claude Code, see the Claude Code Documentation. That’s it.
A skill is just a folder with some Markdown and some optional Python code. You can copy the skill from one laptop to another, and it works. Move it from one project to another, and it works. No special installation, no dependencies to configure, no marketplace publishing required (though you can do that later).
Just a portable folder of instructions and code.
How Progressive Context Loading Works
This is where skills get powerful. Context loads in stages:
Level 1 - Front Matter (Always Loaded)
The description at the top of SKILL.md is always present in context. It’s short (usually one or two sentences) and answers the question: “Should I use this skill?” Claude reads this and decides if the task matches.
Level 2 - SKILL.md Content (On-Demand)
The full skill instructions load only when Claude decides they’re needed. The agent asks to confirm loading the skill before proceeding. If the task doesn’t match, the skill never loads.
Level 3 - Reference Files (Selectively Loaded)
Detailed guides, templates, and reference docs stay in separate files. They are referenced in SKILL.md and loaded only when required. Unless you explicitly need them, they don’t consume context.
Level 4 - Source Code (Execute, Don’t Load)
Python code executes in the background but isn’t loaded into the context. Claude sees only the input and output. Complex logic stays external, keeping your context clean.
The beauty of this design: the agent only carries the context it actually needs, when it needs it. No bloat. No distraction.
Why This Matters
Code Execution: Unlike slash commands or output styles, skills can run Python code. This means complex workflows, calculations, and integrations happen outside the context window.
Rich Documentation: Unlike basic prompts, skills can include detailed reference materials that load on demand.
Problems Addressed by Skills
Skills aren’t just technically clever. They solve real problems. Here’s what they fix:
Problem A: Slash Command Fatigue
With slash commands, you have to remember what /analyse-code does and when to use it. You’re responsible for invoking the correct command at the right time. Scale this to 10 commands, 20 commands, and you’re perpetually context-switching.
Skills flip this: Claude automatically invokes them when it recognises a matching task. You don’t need to remember anything.
Problem B: MCP Tool Memory Bloat
MCPs are powerful, but they have a hidden cost. Every tool description from every installed MCP loads into context all the time. If you have 5 MCPs with 10 tools each, that’s 50 tool descriptions constantly taking up tokens, whether you need them or not. This bloats your context window and drives up costs.
Skills solve this through progressive loading. Only the brief front matter description loads initially. The full skill content loads on demand.
Problem C: CLAUDE.md Context Overload
CLAUDE.md is great for repo-wide rules, but it breaks down at scale. You might have instructions for “How to bootstrap a Python project” that load every single time you interact with Claude, even when you’re writing Golang. In monorepos, different areas need different rules, but CLAUDE.md can’t distinguish between them. It gets bloated quickly.
Skills let you apply focused rules to specific tasks. Context appears only when necessary.
Problem D: Prompt Distribution Challenge
How do you share a working prompt, workflow, or skill with your team? There’s no standard way. CLAUDE.md is repo-specific. Slash commands are personal. MCPs require publishing infrastructure.
Skills solve this through Claude Plugins, a Git-based marketplace. Build once, share everywhere.
Quick Comparison: When to Use What
In practice: I use slash commands for very short prompts I remember. Agent Skills are for complex workflows where I can also benefit from code execution and better context management.
Learning to Build Skills
You don’t need to start from scratch. Anthropic built tools to help:
The Skills Creator Skill: Anthropic’s own interactive skill-building tool. Find it at github.com/anthropics/skills. That repo contains instructions for adding the Anthropic marketplace to your Claude Code instance. Once the marketplace is added, install the required plugins, then ask Claude to use the skill-creator skill to create a new skill. Claude will ask for confirmation to load that skill and then guide you through building your first skill interactively.
Deep Dives (I won’t repeat what’s already well-documented):
Anthropic Engineering Blog: Equipping Agents for the Real World with Agent Skills - The canonical explanation of what skills are and how to design them
Agent Skills Best Practices - Comprehensive guide to building production-quality skills
Read those for the deep technical guidance. This article introduces the concept.
(Bonus point) Sharing Skills: Marketplaces and Plugins
Once you’ve built a skill, you can share it with the world through Claude Plugins. However, it’s entirely optional.
Remember: as explained earlier, a skill is just a folder. You can copy it from one project to another, from one laptop to another, and it works immediately. No special setup required. If that’s all you need, you’re done. Sharing is as simple as putting your skills folder in a Git repo and sending the link to your team.
If you want broader distribution, Marketplaces and Plugins provide a discoverable way to share:
A Marketplace is just a public GitHub repository with a .claude-plugin folder containing a marketplace.json file. That’s it.
See an example here: github.com/anthropics/skills/.claude-plugin/marketplace.json
A Plugin is a container for one or more Claude Agent Skills. Group related skills together, publish the whole plugin, and others can discover it and add it to their Claude environment.
The key requirement: your GitHub repo must be public so others can add your marketplace.
Again, this is entirely optional. Most of the time, copying the skill folder is enough.
Why This Matters (And Why I’m Excited)
I’ve been using Claude Agent Skills since they launched in mid-October, and they’ve been a genuine game changer.
They’ve fundamentally changed how I extend Claude’s capabilities. Instead of fighting with bloated prompts, I build focused skills with progressive context loading. Maintenance is easier. Sharing is easier. The agent is smarter about when to use what.
This is the first article about skills because I’ll reference them often in future articles. We’ll explore real-world use cases, including system design, code review, documentation generators, and more. This foundation matters: understanding why skills exist and how they work differently than everything else.
If you’re building AI agents or extending Claude for your team, invest time in learning Claude Agent skills. They’re worth it.
Get in Touch
If you enjoy this content, please repost it, share it online, and give it a like. Substack is a place for everyone to learn from each other, so please let me know about your experience with Claude Skills, or share a link to an article about Claude Skills that you found helpful. I’ll make sure to read it.
Since I’ve already been using extensively Claude Agent Skills both at work and in my personal life, if you need some help with Claude Agent Skills, please feel free to reach out to me both on Substack or on my Mentorcruise profile page at https://mentors.to/gsantoro where I provide paid mentorship to anyone interested in learning about AI, system design, cloud-native concepts, or anything that’s been discussed in this newsletter.
Since this is a free newsletter, all the content is accessible to everyone.
Mentorship is how I keep this newsletter up and running.
References
Anthropic Skills Marketplace - Open repository with Anthropic’s official skills and the Skills Creator tool
Equipping Agents for the Real World with Agent Skills - Anthropic Engineering blog explaining skill architecture and design patterns
Agent Skills Best Practices - Official documentation on building production-quality skills
Claude Code Documentation - Claude’s official CLI tool for working with skills and agents
Model Context Protocol (MCP) - Alternative approach to extending AI capabilities with tools
The progressive loading is what sold me on skills. Only pulling in context when it's actually needed keeps things fast and cheap. The fiddly bit was the development loop though. Every new SKILL.md and its reference files just sat in my working tree as untracked noise until I sorted a decent local exclusion setup. Wrote about the approach here: https://blog.stackademic.com/how-to-test-mcp-servers-and-agent-configs-without-annoying-your-team-20692917488d