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

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:

YAML Frontmatter: The metadata, like nutritional information - when to use this recipe and for how many people
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.

---
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, 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):

// 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):

---
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):

---
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:

---
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:

---
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:

---
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)

---
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)

---
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:

---
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)

Clear descriptions: Like labeling each jar in the pantry - Claude uses them to decide when to load the skill
```
description: "Explains code with diagrams. Use when user asks 'how does this work?'"
```
Keep SKILL.md focused: < 500 lines. Like a recipe that fits on one page - use supporting files for additional details
```
For complete API reference, see [api-reference.md](api-reference.md)
```
Concrete examples: Like showing the photo of the finished dish
```
See examples/good-commit-message.md for format examples
```
Descriptive arguments: Like indicating "2 tablespoons" instead of just "a bit"
```
argument-hint: [issue-number]
```

❌ Avoid (questi errori, no!)

Too generic skills: "Help with development" → Like saying "food" without specifying what dish
Ambiguous instructions: "Do your best" → Like saying "cook until done" without temperature or time
Loading everything in memory: Like bringing the entire pantry to the table - use supporting files for extensive references
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:

MCP (see post): Connects Claude to external systems - the well-stocked pantry
Skills: Teaches Claude how to use those systems - nonna's recipes
Subagents: Delegates complete tasks - helpers working at other stations
Hooks: Automates workflows - the kitchen's timers and reminders

In practice (la ricetta completa):

---
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:

Technical comparisons:

Related posts:

MCP: From Function Calling to a Universal Standard - 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 🍝