Claude Skills: Teaching Your AI Assistant Context-Aware Expertise

I’ve been building a lot of native macOS apps lately using AI pair programmers. Evergreen, ContextSwitch, and several others. The productivity is incredible, but there’s a problem: AI-generated code has patterns.

Not bugs exactly. Just… slop. Obvious comments that restate what the code does. Over-engineered abstractions for simple operations. Verbose documentation on trivial functions. Template boilerplate that was never filled in.

Each instance is harmless. Cumulatively, they make your codebase harder to maintain and slower to navigate.

I got tired of manually cleaning up the same patterns, so I built a Claude Skill to do it automatically. But first, let me explain what Skills actually are.

What Are Claude Skills?

Claude Skills are a new feature in Claude Code that lets you define reusable expertise for specific tasks. Think of them as specialized instructions that activate automatically when relevant.

A skill is just a markdown file with:

1. Frontmatter defining the name and when it should activate
2. Content describing what to do when activated

Here’s the structure:

---
name: your-skill-name
description: When this skill should activate and what it does
---

# Detailed instructions for Claude

Your expertise goes here...

The key insight: you’re not telling Claude what to do on every request. You’re teaching it domain-specific expertise that activates contextually.

The De-Slop Skill

For Evergreen and my other Swift projects, I needed something to identify and remove common AI code quality issues. I created a skill called de-slop that lives in .claude/skills/de-slop/SKILL.md.

The frontmatter tells Claude when to activate:

---
name: de-slop
description: Identifies and removes AI-generated code slop including dead code, unnecessary comments, over-engineered abstractions, verbose documentation, stale files, and patterns that indicate low-quality AI output. Activates when cleaning up codebases, reviewing AI-generated code, or refactoring projects.
---

When I ask Claude to “review this code” or “clean up the codebase,” the skill activates automatically and applies the patterns I’ve defined.

What the De-Slop Skill Catches

Let me walk through the categories of slop this skill identifies and fixes.

Comment Slop

Obvious comments that state what the code already says:

// BAD: AI slop
let count = items.count  // Get the count of items
user.save()  // Save the user
return result  // Return the result

// GOOD: Let the code speak
let count = items.count
user.save()
return result

Over-documented trivial functions:

// BAD: AI loves this
/// Adds two numbers together.
/// - Parameters:
///   - a: The first number to add
///   - b: The second number to add
/// - Returns: The sum of a and b
func add(_ a: Int, _ b: Int) -> Int {
    return a + b
}

// GOOD: Self-documenting
func add(_ a: Int, _ b: Int) -> Int {
    a + b
}

The pattern: if the comment just repeats what the code says, delete it.

Code Structure Slop

Over-engineered abstractions for simple operations:

// BAD: Factory pattern for no reason
class UserFactory {
    static func createUser(name: String) -> User {
        return User(name: name)
    }
}
let user = UserFactory.createUser(name: "John")

// GOOD: Direct instantiation
let user = User(name: "John")

Verbose boolean comparisons:

// BAD: AI verbosity
if isLoggedIn == true { }
if items.isEmpty == false { }

// GOOD: Concise
if isLoggedIn { }
if !items.isEmpty { }

Redundant else clauses after returns:

// BAD: Unnecessary branch
func validate() -> Bool {
    if condition {
        return true
    } else {
        return false
    }
}

// GOOD: Direct return
func validate() -> Bool {
    condition
}

Dead Code Patterns

The skill knows to look for:

• Unused variables declared but never referenced
• Functions defined but never called
• Commented-out code (delete it, git has history)
• Unreachable code after returns or in dead branches

File/Structure Slop

AI often creates unnecessary files:

• Empty or near-empty files
• Duplicate READMEs in multiple formats
• .bak, .orig, .swp backup files
• Test files with no actual tests
• Configuration duplicated across formats

Naming Slop

Overly verbose names that add no information:

// BAD: AI naming patterns
let userNameStringValue = "John"
func performUserLoginOperation() { }
class UserDataManagerService { }

// GOOD: Concise and clear
let userName = "John"
func login() { }
class UserManager { }

Generic names like data, info, manager, handler, helper, utils, misc when more specific alternatives exist.

AI-Specific Red Flags

The skill specifically watches for patterns that indicate AI generation:

Hedging language in comments:

// BAD: AI hedging
// This might help with performance (depending on use case)
// Generally speaking, this handles the data processing

// GOOD: Be direct or remove
// Caches frequently accessed data

Overly defensive code:

// BAD: Excessive nil checking
if let user = user {
    if let name = user.name {
        if let firstChar = name.first {
            // finally do something
        }
    }
}

// GOOD: Guard or optional chaining
guard let name = user?.name, let firstChar = name.first else { return }

How It Works in Practice

Here’s what happens when I’m working on Evergreen:

Without the skill:

Me: "Review the ContactsView file"
Claude: "The code looks good. I see some minor improvements we could make..."

With the de-slop skill:

Me: "Review the ContactsView file"
Claude: [skill activates automatically]
"I found several slop patterns to clean up:
- Line 23: Obvious comment 'Get count of items' - removing
- Line 45: Redundant else clause - simplifying
- Line 67: Over-engineered wrapper function - inlining
- Line 89: Unused import Foundation.Combine - removing"

The skill gives Claude a systematic framework for code review rather than generic feedback.

The Cleanup Checklist

The skill includes a checklist for systematic cleanup:

1. Comments: Remove obvious, redundant, and placeholder comments
2. Dead code: Delete unused functions, variables, and commented code
3. Files: Remove empty, duplicate, and stale files
4. Imports: Remove unused imports and dependencies
5. Abstractions: Inline unnecessary wrappers and factories
6. Verbosity: Simplify boolean expressions and verbose names
7. Documentation: Remove duplicate and aspirational docs
8. Consistency: Align new code with existing patterns
9. Dependencies: Audit and remove unused packages

When NOT to Clean

The skill also includes guardrails:

• Don’t remove code you don’t understand without investigation
• Don’t delete “unused” public API methods (external code may depend on them)
• Don’t remove comments that explain non-obvious behavior
• Don’t refactor and change behavior in the same commit
• Keep legitimate error handling even if verbose

This prevents overzealous cleanup that breaks things.

Building Your Own Skills

The de-slop skill is specific to my Swift development workflow. But the pattern applies to any domain expertise you want to embed.

Good candidates for skills:

• Code review checklists for your language/framework
• Architecture patterns specific to your project
• Documentation standards for your team
• Testing approaches you want consistently applied
• Deployment procedures with specific steps

Skill design principles:

1. Activation context matters: Be specific about when the skill should activate. “When reviewing code” is better than “always.”

2. Examples over rules: Show good/bad examples rather than abstract principles. Claude learns better from concrete patterns.

3. Structured checklists: Break complex expertise into ordered steps. The de-slop cleanup checklist ensures systematic coverage.

4. Include guardrails: Specify what NOT to do. This prevents the skill from being overapplied.

5. Iterate from real usage: I built the de-slop skill by noting patterns I kept manually fixing, then codifying them.

Skills vs Other Context Methods

Claude Code has several ways to provide context:

• CLAUDE.md: Project-level instructions and architecture
• Skills: Reusable expertise that activates contextually
• Slash commands: One-off prompts for specific tasks
• MCP tools: External capabilities and data access

Skills fit a specific niche: expertise you want applied automatically when relevant, without cluttering your CLAUDE.md or repeating yourself.

For Evergreen, I have:

• CLAUDE.md: Overall architecture, how the app works
• de-slop skill: Code quality patterns to check during review
• swift-code-quality skill: Modern Swift best practices and API usage

Each serves a different purpose. Skills are the knowledge layer that activates contextually.

Real Impact

Since adding the de-slop skill to Evergreen:

• Code reviews catch more issues automatically
• Less manual cleanup after AI-generated changes
• Consistent quality across the codebase

The skill has 257 lines documenting patterns I used to check manually. Now Claude checks them automatically whenever I review code.

Try It Yourself

If you’re using Claude Code and dealing with repetitive code review patterns, try building a skill:

1. Create .claude/skills/[skill-name]/SKILL.md in your repo
2. Add frontmatter with name and description
3. Document the patterns you want checked
4. Test by asking Claude to review code and see if it activates

Start with a narrow domain. The de-slop skill focuses specifically on AI-generated code quality issues. Your first skill should be similarly focused on a problem you face regularly.

The best skills solve real problems you’re already dealing with manually. Watch for patterns in your code reviews, note what you keep fixing, and codify it.