What Are Claude Code Skills and When Should You Create One?
The Problem
I kept typing the same instructions to Claude. Every time I needed a PDF rotated, I explained which library to use. Every deployment, I walked through 12 steps manually. Every time I generated a contract, I pasted the same template structure.
Claude adapted each session, but I was tired of being the onboarding guide for my own workflows.
I’d seen “skills” mentioned in the Claude Code documentation. But I was confused about when to create one versus using CLAUDE.md rules, hooks, or MCP servers. Was I supposed to build an elaborate skill library? Or was that over-engineering?
What I Tried First
I read through the official skills documentation and found sample skills for PDF processing, TDD workflows, and more. They looked comprehensive - multiple files, reference documentation, scripts.
I almost built five skills in one afternoon. Then I stopped.
The question hit me: did I actually need any of them? Or was I just excited about a new feature?
The Confusion: Skills vs Everything Else
Claude Code has four customization mechanisms, and I kept mixing them up:
┌─────────────────────────────────────────────────────────────────────┐│ ││ CLAUDE.md ────────────── Always-on context, preferences ││ │ (Loaded every session) ││ │ ││ Skills ───────────────── On-demand specialized knowledge ││ │ (Loaded when triggered by task) ││ │ ││ Hooks ────────────────── Guaranteed enforcement, automation ││ │ (Fires on tool events) ││ │ ││ MCP Servers ──────────── External connections ││ (APIs, databases, services) ││ │└─────────────────────────────────────────────────────────────────────┘The key insight: Skills are just-in-time knowledge. Unlike CLAUDE.md which loads every session, skills load only when relevant to the current task.
The Reddit Insight That Clarified Everything
I found a discussion where someone explained their approach to skills:
“I was making a lot of PDFs, so I built a skill with my preferred formatting. I needed those PDFs on my phone, so I made a tool + skill to send them to me via Telegram. Needed Claude to take screenshots so built tool + skill for those.”
Then the key line:
“When I notice I’m doing something manually over and over, I automate it. That’s it, nothing else.”
This was the signal I needed. Skills aren’t about building an impressive library. They’re about eliminating repetition.
Another comment reinforced this:
“Minimal setup and learn to modify based on your need as you add more stuff is better than just copy one complicated one.”
And a harsher truth:
“Feel like a lot of the froth around setups is just the new moat to distinguish someone’s Claude workflow from someone else’s.”
I was about to fall into the “froth” trap - creating skills to feel advanced, not to solve problems.
When Skills Actually Make Sense
After analyzing my own workflows and the discussion, I identified five signals that indicate a skill is warranted.
Signal 1: Repeated Code Rewrite
You find yourself writing the same code structure repeatedly. Every time you need a PDF rotated, you look up the pypdf syntax. Every migration, you copy-paste the timestamp format.
Example: I was generating PDFs with similar formatting weekly. Each time, I’d reference the same library docs and paste similar code.
Skill solution: Package the pattern as a skill with quick-start code examples.
Signal 2: Complex Multi-Step Workflows
Your deployment process has 12 steps. You frequently ask Claude to “deploy to staging” and end up guiding it through each step.
Example: A deployment workflow with environment setup, database migrations, service restarts, and health checks.
Skill solution: Encode the workflow in a skill with step-by-step instructions.
Signal 3: Domain-Specific Knowledge
You work with a proprietary API, internal database schemas, or company-specific conventions that Claude cannot know.
Example: An internal API with non-standard authentication, custom headers, and specific rate limits.
Skill solution: Create a skill with reference documentation that Claude can consult.
Signal 4: Specialized Output Formats
You need Claude to generate documents following a specific template - legal contracts, technical specs, brand guidelines.
Example: Generating contracts with specific clauses, formatting, and legal disclaimers.
Skill solution: Package templates in a skill’s assets folder.
Signal 5: Recurring Tool Combinations
You frequently chain multiple tools: read file, transform data, write to database, send notification.
Example: A data pipeline that extracts CSV data, transforms it, and loads it into a database.
Skill solution: Document the tool chain in a skill.
When NOT to Create a Skill
I also identified anti-signals - situations where a skill is the wrong tool.
Anti-Signal 1: One-Time Tasks
Creating a skill for something you’ll do once is overhead without benefit. Skills pay off through reuse.
If you’re generating a single PDF, just ask Claude directly. No skill needed.
Anti-Signal 2: Simple Preferences
If your need is “use TypeScript strict mode” or “prefer functional components,” that belongs in CLAUDE.md, not a skill.
CLAUDE.md is for always-on preferences. Skills are for triggered workflows.
Anti-Signal 3: Enforcement Requirements
If you need Claude to never skip a step or never make a certain mistake, that’s a hook, not a skill.
Skills can be ignored; hooks cannot.
Example: “Always run tests before commit” should be a hook, because it must happen every time.
Anti-Signal 4: External Service Connections
If you need Claude to query a database or call an API, that’s an MCP server, not a skill.
Skills are for knowledge. MCP is for connections.
Anti-Signal 5: Copying Showcase Setups
Don’t create skills because others have elaborate ones. Create them because you have a problem to solve.
The Reddit comment was clear: the froth around setups is often just a moat to feel superior.
The Decision Framework
I created a flowchart to decide whether a skill is appropriate:
Do you have a recurring task/workflow?│├── NO ──▶ No skill needed. Use CLAUDE.md for preferences.│▼ YES│Can CLAUDE.md rules express it adequately?│├── YES ──▶ Keep it in CLAUDE.md. Simpler is better.│▼ NO│Does it require external connections?│├── YES ──▶ Consider MCP server instead.│▼ NO│Does it need guaranteed enforcement?│├── YES ──▶ Use hooks.│▼ NO│Is there domain knowledge Claude lacks?│├── YES ──▶ Create a skill with references/│▼ NO│Is there reusable code/scripts?│├── YES ──▶ Create a skill with scripts/│▼ NO│└──▶ Keep using ad-hoc instructionsSkill Anatomy: What Goes Where
Skills have a specific structure. Here’s what goes in each part:
~/.claude/skills/my-workflow/├── SKILL.md # Required: Core instructions├── scripts/ # Optional: Deterministic code│ ├── validate.sh│ └── transform.py├── references/ # Optional: Documentation Claude references│ ├── api-spec.md│ └── schema.md└── assets/ # Optional: Templates, boilerplate └── template.yamlSKILL.md (Required):
- YAML frontmatter with
nameanddescription- this triggers skill loading - Core workflow instructions
- Pointers to supporting resources
scripts/ (Optional):
- Deterministic code that gets rewritten repeatedly
- Python/Bash scripts for operations
- Validation and testing utilities
references/ (Optional):
- Documentation Claude should reference while working
- API specifications, schemas, policies
- Detailed pattern guides
assets/ (Optional):
- Templates used in output
- Boilerplate code
- Brand assets
A Minimal Skill Example
Here’s what a minimal skill looks like:
---name: deploy-stagingdescription: This skill should be used when the user asks to "deploy to staging", "run deployment workflow", or mentions deployment tasks. Provides step-by-step deployment guidance.---
# Deploy to Staging
## Overview
Multi-step deployment workflow for staging environment.
## Workflow Steps
1. Run test suite: `npm test`2. Build production bundle: `npm run build`3. Run database migrations: `npm run migrate`4. Deploy to staging: `npm run deploy:staging`5. Run smoke tests: `npm run smoke-test`6. Notify team on Slack
## Reference
- **references/rollback.md** - Rollback procedure if deployment failsThe skill triggers when you say “deploy to staging” and provides the workflow without you having to enumerate the steps.
The Progressive Disclosure Pattern
Skills support progressive disclosure - loading detail only when needed:
# PDF Processing
## Quick Start
Extract text with pdfplumber:
import pdfplumber with pdfplumber.open("document.pdf") as pdf: text = pdf.pages[0].extract_text()
## Advanced Features
- **Form filling**: See references/forms.md- **API reference**: See references/api.md- **Working examples**: See examples/ directoryClaude loads the reference files only when you need those specific features. This keeps the main context lean while making deep knowledge available.
My Actual Skill Count
After going through this analysis, how many skills did I create?
Two.
- A PDF processing skill - because I was generating PDFs weekly with similar formatting
- A deployment workflow skill - because our staging deployment had 12 steps I kept forgetting
I didn’t create the “code review skill” or “documentation skill” I initially planned. Those workflows weren’t repetitive enough to warrant skills.
The Audit Test
If you’ve created skills (or are planning to), run this audit:
- List every skill you’ve created or plan to create
- For each skill, ask: “How many times did I do this manually in the last month?”
- If the answer is “once” or “I don’t remember,” don’t create the skill
- If the answer is “multiple times and it was annoying,” create the skill
The repetition signal is the only honest signal.
Related Knowledge
Claude Code’s documentation emphasizes a core principle:
“Claude is already very smart. Only add context Claude doesn’t already have.”
Skills extend Claude’s capabilities for specialized domains. They’re not about making Claude smarter - they’re about giving Claude knowledge it cannot have (your internal APIs, your company’s conventions, your preferred workflows).
The three-level loading system supports this:
Level 1: Metadata (name + description) └── Always in context (~100 words) └── Lets Claude know the skill exists
Level 2: SKILL.md body └── Loaded when skill triggers (<5k words) └── Core workflow and instructions
Level 3: Bundled resources └── Loaded as needed (unlimited via scripts) └── References, assets, detailed docsThis design prevents context bloat while making comprehensive resources available.
Summary
Claude Code skills are specialized knowledge packages that load on-demand to help Claude handle specific domains or workflows. They’re not about building an impressive configuration - they’re about eliminating repetitive manual work.
The decision framework is simple: if you find yourself manually doing something over and over, that’s a skill candidate. If it’s a one-time task, a simple preference, or needs guaranteed enforcement, use a different tool.
The Reddit insight captured the essence: “When I notice I’m doing something manually over and over, I automate it. That’s it, nothing else.”
Skills are the automation layer for knowledge and workflows. Use them when the repetition signal is clear.
Final Words + More Resources
My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me
Here are also the most important links from this article along with some further resources that will help you in this scope:
- 👨💻 Reddit Discussion Source
- 👨💻 Claude Code Skills Documentation
- 👨💻 Claude Code Official Skills Repository
Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!
Comments