Getting started with Claude Skills

In Part 1 of this series - “An Intro to Claude Skills and How It’s Different” - we covered the fundamentals:

What Claude Skills are and how progressive disclosure works
The critical differences between Skills, Projects, MCP, and Custom Instructions
A decision framework for when to use each tool
Why Skills represent a fundamental shift in AI customization

If you haven’t read Part 1 yet, I highly recommend starting there to understand the concepts we’ll be building on.

Now that you understand what Skills are and why they matter, it’s time to get hands-on. In this guide, we’ll actually build Skills together, explore real-world use cases, and give you the practical knowledge to start creating your own AI expertise library.

What we’ll cover in this post:

Creating your first Skill step-by-step (Code Review Skill example)
Adding executable scripts for deterministic operations
Real-world Skills I use as a CTO
Industry examples from companies using Skills in production
Advanced patterns and best practices
Common pitfalls and debugging strategies
Your week-by-week action plan

Let’s build.

Creating Your First Skill

Let’s build something real. I’ll show you how to create a “Code Review Skill” that enforces your team’s standards.

The Anatomy of a Skill

Every skill needs just one required file: SKILL.md

Here’s the basic structure:

---
name: code-review
description: Review code following team standards, catching common issues and suggesting improvements
---

# Code Review Skill

## When to Use This Skill

Activate this skill when the user asks to:
- Review code for quality, security, or performance
- Check pull requests
- Identify anti-patterns or bugs
- Suggest code improvements

## Our Code Standards

### TypeScript/JavaScript
- Use explicit return types for functions
- Prefer const over let, never use var
- Use meaningful variable names (no single letters except loop counters)
- Max function length: 50 lines
- Max file length: 300 lines

### Python
- Follow PEP 8 strictly
- Use type hints for function signatures
- Docstrings required for all public functions
- Max function complexity: 10 (McCabe)

### General Principles
- DRY: Don’t Repeat Yourself
- Single Responsibility: Each function does one thing
- Boy Scout Rule: Leave code better than you found it

## Common Anti-Patterns to Flag

1. **God Objects**: Classes that do too much
2. **Magic Numbers**: Unexplained constants
3. **Premature Optimization**: Over-engineering simple solutions
4. **Callback Hell**: Deeply nested callbacks (use async/await)
5. **Swallowed Exceptions**: Empty catch blocks

## Review Checklist

For each code review, check:
- [ ] Code follows language-specific standards above
- [ ] Functions have clear, single purposes
- [ ] No obvious security issues (SQL injection, XSS, etc.)
- [ ] Error handling is appropriate
- [ ] Tests would be easy to write for this code
- [ ] Code is self-documenting or has necessary comments

## Output Format

Structure your review as:

**Summary**: Brief overview (2-3 sentences)

**Critical Issues**: Security or correctness problems (if any)

**Improvements**: Specific suggestions with line numbers

**Positive Notes**: What’s done well (always include this!)

**Priority**: High/Medium/Low for addressing the issues

## Examples

### Good Review Example

**Summary**: Clean implementation of user authentication with proper validation and error handling.

**Critical Issues**: None

**Improvements**:
- Line 45: Consider extracting email validation to a separate utility
- Line 78: Add rate limiting to prevent brute force attacks

**Positive Notes**: Excellent use of TypeScript types, clear separation of concerns, good test coverage.

**Priority**: Medium (suggestions are enhancements, not blockers)

Step-by-Step Creation Process

Method 1: Manual Creation

Create a folder: code-review-skill/
Inside it, create SKILL.md with the content above
Zip the folder
In Claude.ai: Settings → Capabilities → Skills → Upload Skill
Select your zip file

Method 2: Use the skill-creator Skill (Recommended)

This is meta, but it works brilliantly. The skill-creator is a pre-installed Skill that helps you create new Skills:

In Claude.ai, enable the “skill-creator” skill (it’s pre-installed)
Say: “I want to create a code review skill”
Claude will interview you about your requirements
It generates the folder structure and SKILL.md file
It even bundles resources you might need

The skill-creator asks questions like:

“What’s the primary purpose of this skill?”
“What specific workflows should it support?”
“Do you need any executable scripts?”
“What format should outputs follow?”

Then it creates everything for you. It’s like using an AI to teach an AI how to help you better.

Adding Executable Code (Advanced)

Skills can include scripts for deterministic operations. Here’s an example for the code review skill:

Create code-review-skill/scripts/complexity_checker.py:

#!/usr/bin/env python3
“”“
Check code complexity metrics
“”“
import sys
import ast

def calculate_complexity(code: str) -> dict:
    “”“Calculate McCabe complexity and other metrics”“”
    try:
        tree = ast.parse(code)

        stats = {
            ‘functions’: 0,
            ‘classes’: 0,
            ‘lines’: len(code.split(’\n’)),
            ‘complexity’: 0
        }

        for node in ast.walk(tree):
            if isinstance(node, ast.FunctionDef):
                stats[’functions’] += 1
                # Simple complexity: count decision points
                complexity = 1  # Base complexity
                for subnode in ast.walk(node):
                    if isinstance(subnode, (ast.If, ast.While, ast.For,
                                           ast.ExceptHandler, ast.With)):
                        complexity += 1
                stats[’complexity’] = max(stats[’complexity’], complexity)
            elif isinstance(node, ast.ClassDef):
                stats[’classes’] += 1

        return stats
    except Exception as e:
        return {’error’: str(e)}

if __name__ == ‘__main__’:
    if len(sys.argv) < 2:
        print(”Usage: complexity_checker.py <file_path>”)
        sys.exit(1)

    with open(sys.argv[1], ‘r’) as f:
        code = f.read()

    results = calculate_complexity(code)
    print(f”Functions: {results.get(’functions’, 0)}”)
    print(f”Classes: {results.get(’classes’, 0)}”)
    print(f”Lines: {results.get(’lines’, 0)}”)
    print(f”Max Complexity: {results.get(’complexity’, 0)}”)

Update your SKILL.md to reference it:

## Tools Available

This skill includes a complexity checker script. Claude can run:
`python scripts/complexity_checker.py <file_path>`

to get objective complexity metrics before reviewing.

Now Claude can automatically run complexity analysis without you asking, and without loading the entire script into context.

Real-World Use Cases

Let me share some Skills I’ve built and how they’ve changed my workflow:

1. Architecture Documentation Skill

Problem: Every time I designed a new system, I’d have to remember our documentation template, what diagrams to include, what sections to cover.

Solution: Created a skill that knows:

Our architecture doc template (intro, requirements, constraints, options, decision, consequences)
When to create sequence diagrams vs. architecture diagrams
How to document trade-offs in our style
Our specific Mermaid diagram conventions

Impact: Architecture docs that used to take 2 hours now take 30 minutes, and they’re consistently formatted.

2. Sprint Planning Skill

Problem: Creating Jira tickets with proper structure, acceptance criteria, and labels was tedious.

Solution: Skill that encodes:

Our ticket template (title format, description structure, acceptance criteria format)
Team conventions (when to add specific labels, how to estimate points)
Links to related documentation
A script to validate ticket structure before creation

Impact: Combined with MCP (Jira connection), I can now say “create tickets for this feature” and get properly structured, ready-to-assign tickets.

3. Technical Interview Skill

Problem: Needed consistency across interviewers for technical evaluations.

Solution: Skill containing:

Interview question bank by difficulty
Evaluation rubric
Follow-up questions based on candidate responses
How to give hints without giving away answers
Note-taking template

Impact: All interviewers now use the same framework, making candidate comparisons fair and feedback consistent.

Industry Examples

Some real implementations from companies using Skills:

Rakuten (E-commerce Giant)

Created Skills for management accounting workflows
Automated finance operations that previously required manual coordination across departments
Result: Streamlined workflows, reduced processing time

Box (Enterprise Content Management)

Skills that transform stored files into presentations, spreadsheets, and Word documents
All outputs follow organizational standards automatically
Result: Hours saved on document creation, consistent branding

Financial Services Firms

Skills for Discounted Cash Flow (DCF) modeling
Comparable company analysis
Due diligence workflows
Initiating coverage reports
Result: Junior analyst work automated, consistent methodologies

Getting Started: Your Action Plan

Here’s how to dive into Skills effectively:

Week 1: Explore Pre-built Skills

Enable Skills in Settings → Capabilities
Try the document creation skills (docx, pptx, xlsx, pdf)
Ask Claude to create a simple document to see Skills in action
Note: You’ll see Skills mentioned in Claude’s “thinking” as it works

Week 2: Identify Your First Custom Skill

Ask yourself:

What task do I repeat weekly that has specific rules?
What workflow requires consistency across my team?
What knowledge do I keep having to explain to Claude?

Good first Skills:

Email response templates for common scenarios
Report generation following your format
Code scaffolding for your tech stack
Meeting note structuring

Week 3: Build and Test

Use the skill-creator skill to build your first custom skill
Test it thoroughly with variations of your typical requests
Refine the instructions based on what Claude misses
Share with a colleague for feedback

Week 4: Stack and Scale

Create a complementary skill
Test how they work together automatically
Document what worked/didn’t work
Plan your next 3 skills

Common Pitfalls and How to Avoid Them

Pitfall 1: Making Skills Too Broad

Wrong: “General writing skill” that covers emails, blogs, tweets, documentation, and reports

Right: Separate skills for each content type with specific guidelines

Why: Broad skills defeat the purpose of progressive disclosure. Claude loads the whole skill when any writing task comes up.

Pitfall 2: Not Testing Edge Cases

Problem: Your skill works for the happy path but fails when things get weird

Solution:

Test with incomplete inputs
Try contradictory requirements
See what happens when users ask questions the skill doesn’t anticipate

Pitfall 3: Forgetting About Token Costs

Problem: Including your entire company handbook in a single skill

Solution:

Remember Claude only loads what it needs, but massive skills take longer to parse
Break large knowledge bases into focused skills
Use links to external docs for reference rather than including everything

Pitfall 4: Ignoring Maintenance

Problem: Creating skills and never updating them as processes change

Solution:

Version your skills (add version info to YAML frontmatter)
Set quarterly reviews
Track when skills give outdated advice
Update promptly when processes change

Advanced Patterns

Once you’re comfortable with basic Skills, here are some advanced patterns:

Pattern 1: Skill Chains

Create skills that naturally work together:

data-extraction skill → pulls data from sources
data-analysis skill → analyzes extracted data
report-generation skill → formats analysis into reports

Claude automatically chains them when you say “analyze this data and create a report.”

Pattern 2: Conditional Logic in Skills

Use clear conditionals in your skill instructions:

## Decision Logic

**If** the user is asking about production issues:
- Load emergency response procedures
- Include on-call rotation information
- Flag the urgency level

**If** the user is asking about development:
- Load coding standards
- Reference architecture docs
- Suggest testing approaches

Pattern 3: Skill Evolution

Start simple, evolve based on usage:

Version 1: Basic instructions and examples
Version 2: Add common edge cases you discovered
Version 3: Include executable scripts for repeated computations
Version 4: Add links to related skills for complex workflows

Track version history in your SKILL.md:

---
name: my-skill
description: Does something useful
version: 1.2.0
last_updated: 2025-11-02
---

## Changelog
- v1.2.0: Added script for automated validation
- v1.1.0: Expanded examples based on user feedback
- v1.0.0: Initial release

Practical Tips from Two Weeks of Heavy Usage

Tip 1: Start with Examples in Natural Language

Before writing a skill, describe what you want in a normal conversation with Claude. Refine it over several chats. Once you have wording that works consistently, turn that into a skill.

Tip 2: Use the “Skill Thinking” Feature

When Claude uses a skill, you see it in the “thinking” section (if enabled). This shows:

Which skills were activated
What information was loaded
How skills interacted

This is invaluable for debugging and improving skills.

Tip 3: Create Skill Dependencies Explicitly

If one skill relies on another, document it:

## Related Skills

This skill works best when combined with:
- `data-validation` skill (for input checking)
- `report-formatting` skill (for output styling)

Claude should load these skills when using this one for comprehensive workflows.

Tip 4: Include “When NOT to Use” Sections

## When NOT to Use This Skill

Don’t use this skill for:
- Quick calculations (use built-in math instead)
- Simple queries (this skill is for complex analysis only)
- Real-time data (use MCP connections for live data)

This helps Claude make better decisions about skill activation.

Tip 5: Iterate Based on Logs

Keep a log of times when:

The skill didn’t activate when it should have
The skill activated incorrectly
The output wasn’t what you expected

Use this to refine the description and instructions.

Skills + MCP: The Power Combo

The real magic happens when you combine Skills with MCP connections. Here’s a concrete example:

Setup:

MCP connection to your company’s PostgreSQL database
MCP connection to your Slack workspace
Skill: “Database Query Standards”
Skill: “Slack Message Formatting”

What you can do:

“Check yesterday’s sales numbers and post a summary to the #sales channel”

Claude:

Loads the Database Query Standards skill
Writes a query following your conventions
Executes it via MCP connection
Loads the Slack Message Formatting skill
Formats results according to team style
Posts via MCP to Slack

All of this happens automatically, consistently, following your standards.

Future-Proofing Your Skills

Skills will evolve. Here’s how to build them for longevity:

Use Semantic Versioning

version: 2.1.3
# Major.Minor.Patch
# Major: Breaking changes to skill interface
# Minor: New features, backwards compatible
# Patch: Bug fixes and clarifications

Document Assumptions

## Assumptions

This skill assumes:
- Python 3.9+ is available
- User has basic understanding of financial models
- Data is in CSV format with headers
- Date format is YYYY-MM-DD

Plan for Deprecation

## Deprecation Notice

**Status**: Active (will be deprecated 2026-03-01)
**Replacement**: Use `advanced-analysis-v2` skill instead
**Migration**: [Link to migration guide]

Keep Skills Focused

One skill, one purpose. Don’t try to make a skill that does everything. It’s easier to maintain five focused skills than one mega-skill.

My Recommendation: Start Today

If you’re still reading, you’re probably convinced that Skills are worth exploring. Here’s my opinionated take on getting started:

If You’re a Developer

Start with: A code generation skill for your stack

Include your team’s conventions
Add linting rules
Include common patterns
Add a script to validate generated code

Then build: A PR review skill

Your review checklist
Common issues in your codebase
How to give constructive feedback
Auto-generated review comments format

Advanced: A deployment verification skill

Pre-deployment checklist
Post-deployment verification steps
Rollback procedures
Incident response templates

If You’re a Content Creator

Start with: Content formatting skill

Your brand voice guidelines
Content structure templates
SEO best practices specific to your niche
CTAs that work for your audience

Then build: Research synthesis skill

How you organize research notes
Citation formats you prefer
Insight extraction methods
Content ideation from research

Advanced: Multi-platform adaptation skill

Blog post → Twitter thread converter
Twitter thread → LinkedIn post adapter
Long-form → Newsletter snippet generator

If You’re in Operations/Business

Start with: Meeting notes skill

Your meeting note template
Action item formatting
Who gets which type of follow-up
Integration with your project management

Then build: Report generation skill

Company report templates
KPI calculations
Visualization preferences
Distribution formatting

Advanced: Process documentation skill

SOP template
Process mapping conventions
Troubleshooting flowcharts
Training material generation

Conclusion: The Skills Revolution is Just Beginning

We’re at the very beginning of the Skills era. Right now (November 2025), Skills are:

Two weeks old
Understood by few
Used by fewer
Mastered by almost none

This is your opportunity.

In six months, there will be Skills for everything. There will be best practices, design patterns, and entire ecosystems. Companies will have libraries of organizational Skills. Freelancers will specialize in Skill creation. Courses will teach “Skills Engineering.”

But right now? It’s wide open.

The people who start building Skills today will be the experts everyone learns from tomorrow. The companies that encode their processes into Skills now will have a significant advantage over competitors who wait.

This isn’t hype, it’s the logical evolution of how we work with AI. Skills turn one-off interactions into reusable expertise. They turn prompt engineering into knowledge engineering. They turn AI assistance into AI collaboration.

Your Next Steps

Today: Enable Skills in your Claude account, try the pre-built document skills
This week: Identify one repetitive task that has specific rules, use skill-creator to build your first custom skill
This month: Create three skills that work together, share them with a colleague or community
This quarter: Build a library of skills for your core workflows, measure the time saved

And when you do, I’d love to hear about it. What skills are you building? What’s working? What surprised you?

Because here’s the thing: Skills are so new that we’re all figuring this out together. Every experiment matters. Every insight contributes to the collective understanding.

The revolution isn’t coming. It’s here. And it’s wearing the humble disguise of a Markdown file in a folder.

Want to dive deeper? Check out Anthropic’s Skills GitHub repository for examples, or join the discussion on r/ClaudeAI.

Final Note: This guide will become outdated. Skills are evolving rapidly. I’ll update it as I learn more, and I encourage you to treat Skills as an experiment, not a doctrine. Try things. Break things. Share what you learn.

The best Skill you’ll ever create is the one you start building today.

Getting started with Claude Skills - The Complete Guide

Stay in the loop