Writing Claude Skills That Actually Work (With Examples)

The Problem with "Works in Theory" Claude Skills

Claude Skills don’t just need to compile—they need to work in real life. I’ve spent hours debugging skills that failed in production because they ignored edge cases or misunderstood user intent. If you’ve built a skill that stopped working after deployment, you know the pain. Let’s fix that.

Context: Why Claude Skills Fail (And How to Fix Them)

As a solo developer building 22+ Android apps, I’ve learned that AI integrations are no different from traditional code. The difference? AI is unpredictable. A skill that works in your dev environment might crash in production if it doesn’t handle ambiguous inputs or missing data.

For example, I once built a skill to automate a form submission. It worked perfectly in testing, but when users entered typos or left fields blank, it broke. The root cause? I didn’t validate inputs or handle errors gracefully. This post will walk you through the exact steps to avoid these mistakes.

Section 1: Designing Skills That Handle Real-World Chaos

The 3 Core Requirements for Reliable Skills

A working Claude Skill isn’t just about code—it’s about anticipating chaos. Here’s what I always check:

Code Example: Input Validation in Kotlin

fun validateFormInput(userInput: String): Boolean {  
    if (userInput.isNullOrEmpty() || userInput.trim().isEmpty()) {  
        return false  
    }  
    // Add regex checks for specific formats if needed  
    return true  
}  

Pitfall #1: Overlooking Ambiguous Prompts

Claude Skills often fail because they assume users will phrase requests exactly. If a user says "send email," but the skill expects "send email to boss," it breaks.

Solution: Use Claude’s

system_message

system_message: "You are a form assistant. Only respond with 'confirm' or 'cancel' based on user intent."  

Pitfall #2: Ignoring State Management

Skills that don’t track user context (e.g., previous inputs) often reset on each interaction.

Fix: Store state in shared preferences or a database.

val state = SharedPreferences.getInstance().getString("lastInput", "")  

Section 2: Testing Before Deployment (No More "It Worked in My Head")

Why Unit Tests Fail for AI Skills

Traditional unit tests don’t simulate real user behavior. A skill might pass tests but fail when users type "maybe" instead of "yes."

Solution: Use mock data that mimics real-world variability.

val testCases = listOf(  
    "Yes, send it",  
    "No thanks",  
    "Can you do this?",  
    "" // Empty input  
)  

for (input in testCases) {  
    val result = executeSkill(input)  
    assert(result.isNotEmpty()) // Add your own assertions  
}  

Table: Before vs. After Testing

Warning: Don’t Test in Production

Deploying untested skills is a recipe for disaster. Always use a staging environment. I once lost 1,000 users because a skill failed on production data.

Section 3: A Working Example: Automating a Task in Your Android App

The Goal

Build a skill that lets users say "Remind me to water the plants" and have the app create a calendar event.

Step 1: Define the Skill’s Scope

Limit the skill to specific actions. Don’t make it handle 100 tasks—focus on 2–3.

Step 2: Write the Claude Prompt

val prompt = """  
User said: "$userInput"  
Task: Create a calendar event for "Water plants" at 9 AM tomorrow.  
Return only the event details in JSON.  
"""  

Step 3: Integrate with Android UI

Use Jetpack Compose to trigger the skill from a button.

@Composable  
fun SkillButton(onClick: () -> Unit) {  
    Button(onClick = onClick) {  
        Text("Use Skill")  
    }  
}  

Step 4: Handle the Response

Parse the JSON and update the UI.

val event = parseJsonResponse(response)  
Toast.makeText(context, "Event created: $event", Toast.LENGTH_SHORT).show()  

Key Takeaways

• Start simple: Focus on 1–2 tasks per skill. Complex skills are harder to debug.
• Test with real variability: Include typos, empty inputs, and edge cases in your tests.
• Validate everything: Never assume user input is correct. Add checks for format, length, and intent.

[!TIP] Test your skills with 10+ different user phrases before deployment.
[!NOTE] Use Claude’s

code Copy

system_message

to define strict behavior.
[!WARNING] Never deploy a skill without testing it in a staging environment.