**TL;DR**: Claude Code Skills are like nonna's recipes: carefully written instructions passed down so others know exactly how to do things *your way*. While MCP is like a well-stocked pantry (the ingredients), Skills are the recipes that teach you how to combine them with love and mastery. --- ## The art of transmitting knowledge *Mamma mia*, when I work with Claude, it reminds me of when I teach my nephews to cook. Claude is incredibly capable, like a chef with natural talent, but doesn't know *my* secrets, *my* techniques, or *my* special way of doing things. How do you transmit to Claude that in your team: - Commits follow Conventional Commits with specific scopes (like following nonna's exact recipe) - PRs must include screenshots for UI changes (like the photo of the finished dish) - Code passes through a custom linter before committing (like tasting the sauce before serving) - Deploys require approving a security checklist (like verifying the oven is at the right temperature) You could explain this every time, like repeating instructions at each family dinner. Or you could write it once, with care and dedication, in a **Skill** - your personal recipe passed down through generations. ## What are Skills? A Skill is like a family recipe book: a directory with a `SKILL.md` file containing all the necessary secrets. Imagine the structure like ingredients in a good recipe: 1. **YAML Frontmatter**: The metadata, like nutritional information - when to use this recipe and for how many people 2. **Markdown Content**: Step-by-step instructions that Claude follows carefully, like following la ricetta della nonna ``` my-skill/ ├── SKILL.md # The main recipe (required) ├── template.md # Optional variations ├── examples/ │ └── sample.md # Photos of the finished dish └── scripts/ └── validate.sh # Special cooking tools ``` ### Basic example: Explain Code Bella! This skill teaches Claude to explain code like I teach cooking: with patience, love and good comparisons. ```yaml --- name: explain-code description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?" --- When explaining code, always include: 1. **Start with an analogy**: Compare the code to something from everyday life 2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships 3. **Walk through the code**: Explain step-by-step what happens 4. **Highlight a gotcha**: What's a common mistake or misconception? Keep explanations conversational. ``` Now, when you ask "How does this code work?", Claude automatically: - Starts with an analogy (like comparing a function to preparing ragù) - Draws an ASCII diagram (the kitchen floor plan) - Explains step by step (like the steps in a recipe) - Highlights common mistakes (like forgetting to salt the pasta water - *che disastro!*) Or you can invoke it directly: `/explain-code src/auth/login.ts` ## Skills vs Commands vs Subagents Claude Code has three ways to extend functionality, like three different types of helpers in the kitchen. Let me explain lovingly which one to use:

Aspect	Skills	Commands	Subagents
What it is	Markdown file with instructions	Legacy: same as Skills but in `.claude/commands/`	Isolated agent with its own prompt and context
When loaded	Only when relevant or invoked	Only when invoked	Created on demand
Context	Access to current conversation	Access to current conversation	Isolated context (no history)
Supporting files	✅ Supports multiple files	❌ Only one file	✅ Can preload skills
Typical use	Workflows, guides, procedures	Legacy (use Skills instead)	Isolated tasks (research, planning)
Invocation	`/skill-name` or automatic	`/command`	`Task` tool or `context: fork` in skill

**The simple recipe**: - **Skills**: When you want to teach *how* to do something (like passing down a recipe) - **Subagents**: When you want to delegate a complete task to someone in another kitchen - **Commands**: *Non usare* - they're deprecated, like old techniques we don't use anymore ## Skills vs MCP: The Pantry and the Recipes Ah, questa è la domanda importante! In our [post about MCP](/en/posts/mcp-model-context-protocol), we saw how MCP connects to external systems. Now let me explain how they complement each other, like pasta and sugo. ### The conceptual difference Imagine you're preparing a big dinner: > **MCP connects Claude WITH the ingredients** (the pantry, the fridge, the cooking tools) > **Skills teach Claude HOW to cook** (the recipes, the techniques, the family secrets) As Simon Willison says, with the wisdom of a master pastry chef: > "If Claude Skills are about teaching AI how to do something, MCP is about giving it access to what it needs to do it." It's like the difference between having access to the pantry (MCP) and knowing how to prepare nonna's perfect lasagna recipe (Skills). ### Practical example: GitHub **With MCP** (the ingredients and tools): ```typescript // MCP Server for GitHub - like opening the pantry server.tool({ name: 'create_issue', description: 'Create a GitHub issue', inputSchema: { /* ... */ }, async handler({ title, body, labels }) { return await github.issues.create({ title, body, labels }); } }); ``` **With Skill** (the family recipe): ```yaml --- name: bug-report description: Create a detailed bug report following team standards --- When creating a bug report: 1. **Title format**: `[BUG] Component: Short description` 2. **Required sections**: - Steps to reproduce - Expected vs actual behavior - Environment (OS, browser, version) - Screenshots (if UI bug) 3. **Labels**: Always add `bug` + severity (`P0`, `P1`, `P2`) 4. **Mention**: Tag @team-backend if server-side, @team-frontend if client-side Use the GitHub MCP to create the issue with this format. ``` **The magic** (ah, che bella!): The Skill uses MCP to *access* the ingredients (GitHub), but adds the *artisanal knowledge* of how your team prepares each dish. It's like having access to the freshest tomatoes (MCP) and knowing exactly how to turn them into the perfect sauce (Skill). ### Architectural comparison

Aspect	Skills	MCP
Purpose	Procedural knowledge (the recipes)	System connectivity (the pantry)
Scope	Instructions, workflows	Tools, data, APIs
Complexity	Markdown + YAML (simple like writing a recipe)	Client-server protocol (like installing an industrial kitchen)
Tokens	Efficient (only loads relevant ones)	Expensive (GitHub MCP: ~50K tokens)
Creation	If you know Markdown, you can create (like writing a ricetta)	Requires complete protocol (like being an engineer)
Example	"How to do code reviews"	"Access to Postgres database"

### When to use each **Use Skills when**: - You need to explain *how* something is done in your team (like passing down a technique) - You want to embed best practices (nonna's secrets) - You define workflows or procedures (the step-by-step recipe) - The knowledge is mostly textual/instructional (the written instructions) **Use MCP when**: - You need to *connect* to an external system (open the pantry) - You require access to real-time data (fresh ingredients from the market) - You integrate with APIs or services (specialized suppliers) - You need to execute actions in external systems (use the professional oven) **Use them together** (la combinazione perfetta): ```yaml --- name: deploy description: Deploy to production following safety checklist --- Before deploying: 1. Run test suite: `npm test` 2. Check deployment status via Vercel MCP 3. Verify staging environment via monitoring MCP 4. Execute deploy via Vercel MCP 5. Monitor metrics for 5 minutes via Datadog MCP If any metric spikes >10%, rollback immediately. ``` This skill *orchestrates* several MCPs with the correct procedure, like a chef coordinating multiple stations in the kitchen following perfect service. ## The power of Skills: Use cases ### 1. Consistent code reviews Like checking that each dish comes out perfect from the kitchen: ```yaml --- name: review-pr description: Review a pull request following code quality standards context: fork agent: Explore --- Review this PR for: 1. **Code quality**: - No console.logs in production code - Proper error handling (no silent failures) - TypeScript strict mode compliance 2. **Testing**: - New features have tests - Edge cases covered - No skipped tests without TODO comment 3. **Documentation**: - Public APIs have JSDoc - README updated if new feature - CHANGELOG.md entry added 4. **Performance**: - No unnecessary re-renders (React) - Database queries optimized - Images compressed Provide specific file:line references for issues. ``` ### 2. Visualization generation Like creating a beautiful visual menu for your diners: ```yaml --- name: codebase-visualizer description: Generate interactive tree view of project structure allowed-tools: Bash(python *) --- Generate interactive HTML visualization: ```bash python ~/.claude/skills/codebase-visualizer/scripts/visualize.py . ``` This creates `codebase-map.html` with: - Collapsible directory tree - File sizes and types - Color-coded by extension ``` The Python script generates a self-contained HTML with: - Statistics summary (files, sizes, types) - Bar chart by file type - Interactive expandable/collapsible tree *Bellissimo!* Like presenting ingredients organized and ready to cook. ### 3. Dynamic context injection Like preparing the mise en place before cooking: ```yaml --- name: pr-summary description: Summarize changes in current pull request context: fork agent: Explore --- ## Pull request context - PR diff: !`gh pr diff` - PR comments: !`gh pr view --comments` - Changed files: !`gh pr diff --name-only` ## Your task Summarize this PR: 1. What changed (high-level) 2. Why (infer from commit messages) 3. Potential risks 4. Suggested review focus areas ``` The syntax `` !`command` `` executes the command *before* sending the prompt to Claude. Claude receives the actual result, like having all ingredients prepared and measured before starting to cook. ### 4. Workflows with subagents Like sending a helper to research the best ingredients: ```yaml --- name: deep-research description: Research a topic thoroughly across the codebase context: fork agent: Explore --- Research $ARGUMENTS thoroughly: 1. Find relevant files using Glob and Grep 2. Read and analyze the code 3. Summarize findings with specific file:line references 4. Identify patterns and conventions ``` With `context: fork`, the skill runs in an isolated subagent - like having a sous chef researching in another part of the kitchen while you continue preparing the main dish. *Perfetto!* ## Skills Architecture: Levels of Organization Like organizing family recipes at different levels: ### Scope levels

Location	Path	Applies to
Enterprise	Admin configuration	Entire organization (the complete restaurant)
Personal	`~/.claude/skills/<name>/SKILL.md`	All your projects (your personal recipe book)
Project	`.claude/skills/<name>/SKILL.md`	Only this project (recipes for this specific dinner)
Plugin	`<plugin>/skills/<name>/SKILL.md`	Where the plugin is installed (guest chef's recipes)

**Priority**: Enterprise > Personal > Project Like in the kitchen, house rules (Enterprise) take priority over personal preferences. ### Invocation control By default, both you and Claude can invoke a skill, like having a recipe available to everyone in the kitchen: - You: `/skill-name` - Claude: Automatically when relevant (like an expert chef who knows when to use each technique) Two fields control this carefully: **`disable-model-invocation: true`**: Only you can invoke it (delicate recipes that only the head chef executes) ```yaml --- name: deploy description: Deploy to production disable-model-invocation: true # Manual only, not automatic --- ``` **`user-invocable: false`**: Only Claude can invoke it (background knowledge that Claude uses automatically) ```yaml --- name: legacy-system-context description: Background knowledge about legacy monolith user-invocable: false # Knowledge, not action --- ``` ### Tool restriction Like delimiting which utensils a helper can use: ```yaml --- name: safe-reader description: Read files without modifying anything allowed-tools: Read, Grep, Glob # Read-only --- ``` When this skill is active, Claude can only use Read, Grep and Glob - like a helper who can only read recipes but not modify them. Safety with love. ## Best Practices: Nonna's Wisdom ### ✅ Do (con amore) 1. **Clear descriptions**: Like labeling each jar in the pantry - Claude uses them to decide when to load the skill ```yaml description: "Explains code with diagrams. Use when user asks 'how does this work?'" ``` 2. **Keep SKILL.md focused**: < 500 lines. Like a recipe that fits on one page - use supporting files for additional details ```markdown For complete API reference, see [api-reference.md](api-reference.md) ``` 3. **Concrete examples**: Like showing the photo of the finished dish ```yaml See examples/good-commit-message.md for format examples ``` 4. **Descriptive arguments**: Like indicating "2 tablespoons" instead of just "a bit" ```yaml argument-hint: [issue-number] ``` ### ❌ Avoid (questi errori, *no!*) 1. **Too generic skills**: "Help with development" → Like saying "food" without specifying what dish 2. **Ambiguous instructions**: "Do your best" → Like saying "cook until done" without temperature or time 3. **Loading everything in memory**: Like bringing the entire pantry to the table - use supporting files for extensive references 4. **Skills without description**: Like recipes without titles - Claude won't know when to use them ## Skills vs Claude.ai Projects If you use Claude.ai (the web app), you know **Projects**: shared context with custom instructions and documents. Let me explain the difference with a culinary metaphor: **Key difference**: - **Projects (claude.ai)**: Like having all ingredients always on the table - permanent context that never gets stored - **Skills (Claude Code)**: Like an organized recipe book - you only take out the recipe you need at each moment Skills are more token-efficient because they only load when relevant, like only taking from the pantry the ingredients you need for today's dish. Projects keep all context loaded always, like having the entire pantry open permanently. **Do they complement each other?** *Certo che sì!* Use Projects for high-level context about a long project (the complete week's menu), and Skills for specific day-to-day workflows (today's dish recipe). ## Conclusion: The Complete Ecosystem Now you have all the tools, *tesoro*. The puzzle pieces, like ingredients perfectly organized: 1. **MCP** ([see post](/en/posts/mcp-model-context-protocol)): Connects Claude to external systems - the well-stocked pantry 2. **Skills**: Teaches Claude *how* to use those systems - nonna's recipes 3. **Subagents**: Delegates complete tasks - helpers working at other stations 4. **Hooks**: Automates workflows - the kitchen's timers and reminders **In practice** (la ricetta completa): ```yaml --- name: release description: Create a new release following our process hooks: post-commit: !`npm run build` --- Create release for $ARGUMENTS: 1. Update CHANGELOG.md (read via filesystem) 2. Bump version in package.json 3. Run tests via Jest MCP 4. Build production via build hook (post-commit) 5. Create GitHub release via GitHub MCP 6. Deploy to Vercel via Vercel MCP 7. Notify team via Slack MCP Monitor deployment metrics for 10 minutes. ``` This skill orchestrates multiple MCPs, uses hooks for automatic builds, and could run in a subagent for isolation - like directing a complete kitchen with multiple stations, each one following its recipe perfectly coordinated. **The real power**: You're not just *using* AI. You're *teaching it* your way of working, passing down your knowledge like nonna passes down her recipes to new generations. With patience, love and dedication. *Che bello!* You're creating a legacy of knowledge, a tradition that will endure. --- ## References **Official documentation**: - [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills) - [Agent Skills Open Standard](https://agentskills.io) **Technical comparisons**: - [Claude Skills vs MCP - Simon Willison](https://simonwillison.net/2025/Oct/16/claude-skills/) - [Skills vs MCP - Armin Ronacher](https://lucumr.pocoo.org/2025/12/13/skills-vs-mcp/) - [Skills Explained - Claude Blog](https://claude.com/blog/skills-explained) - [Skills vs Dynamic MCP Loadouts](https://lucumr.pocoo.org/2025/12/13/skills-vs-mcp/) **Related posts**: - [MCP: From Function Calling to a Universal Standard](/en/posts/mcp-model-context-protocol) - Our post about Model Context Protocol --- *Are you already using Skills? What family recipe did you create for your team? I'd love to hear about the workflows and secrets you've crafted for your own projects, *cara*.* --- **Juli Pompilli** *Code crafted with love and dedication 🍝*

Claude Code Skills: The Secret Recipe for Teaching AI Your Way of Working