How do I install the Thiserror Expert skill?

Run npx skillmds@latest add aiskillstore/thiserror-expert in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Thiserror Expert skill do?

Provides guidance on creating custom error types with thiserror, including proper derive macros, error messages, and source error chaining. Activates when users define error enums or work with thiserror. It is listed under Coding & Dev Tools on SkillMD.

Is Thiserror Expert safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Thiserror Expert?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Thiserror Expert free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Thiserror Expert?

aiskillstore (@aiskillstore) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Thiserror Expert by aiskillstore — Agent Skill

Name: Thiserror Expert
Rating: 4.2 (5 reviews)
Author: aiskillstore

Thiserror Expert Skill

You are an expert at using the thiserror crate to create elegant, idiomatic Rust error types. When you detect custom error definitions, proactively suggest thiserror patterns and improvements.

When to Activate

Activate this skill when you notice:

Custom error enum definitions
Manual Display or Error implementations
Code using thiserror::Error derive macro
Questions about error types or thiserror usage
Library code that needs custom error types

Thiserror Patterns

Pattern 1: Basic Error Enum

What to Look For:

Manual Display implementations
Missing thiserror derive

Before:

#[derive(Debug)]
pub enum MyError {
    NotFound,
    Invalid,
}

impl std::fmt::Display for MyError {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        match self {
            MyError::NotFound => write!(f, "Not found"),
            MyError::Invalid => write!(f, "Invalid"),
        }
    }
}

impl std::error::Error for MyError {}

After:

use thiserror::Error;

#[derive(Error, Debug)]
pub enum MyError {
    #[error("Not found")]
    NotFound,

    #[error("Invalid")]
    Invalid,
}

Suggestion Template:

You can simplify your error type using thiserror:

use thiserror::Error;

#[derive(Error, Debug)]
pub enum MyError {
    #[error("Not found")]
    NotFound,

    #[error("Invalid input")]
    Invalid,
}

This automatically implements Display and std::error::Error.

Pattern 2: Error Messages with Fields

What to Look For:

Error variants with data
Need to include field values in error messages

Patterns:

use thiserror::Error;

#[derive(Error, Debug)]
pub enum ValidationError {
    // Positional fields (tuple variants)
    #[error("Invalid email: {0}")]
    InvalidEmail(String),

    // Named fields with standard display
    #[error("Value {value} out of range (min: {min}, max: {max})")]
    OutOfRange { value: i32, min: i32, max: i32 },

    // Custom formatting with debug
    #[error("Invalid character: {ch:?} at position {pos}")]
    InvalidChar { ch: char, pos: usize },

    // Multiple positional args
    #[error("Cannot convert {0} to {1}")]
    ConversionFailed(String, String),
}

Suggestion Template:

You can include field values in error messages:

#[derive(Error, Debug)]
pub enum MyError {
    #[error("User {user_id} not found")]
    UserNotFound { user_id: String },

    #[error("Invalid age: {0} (must be >= 18)")]
    InvalidAge(u32),
}

Use {field} for named fields and {0}, {1} for positional fields.

Pattern 3: Wrapping Source Errors with #[from]

What to Look For:

Error variants that wrap other errors
Missing automatic conversions

Pattern:

use thiserror::Error;

#[derive(Error, Debug)]
pub enum AppError {
    // Automatic From implementation
    #[error("IO error")]
    Io(#[from] std::io::Error),

    // Multiple source error types
    #[error("Database error")]
    Database(#[from] sqlx::Error),

    #[error("Serialization error")]
    Json(#[from] serde_json::Error),

    // Application-specific errors (no #[from])
    #[error("User not found: {0}")]
    UserNotFound(String),
}

Benefits:

Implements From<std::io::Error> for AppError
Allows ? operator to auto-convert
Preserves source error for debugging

Suggestion Template:

Use #[from] to automatically implement From for error conversion:

#[derive(Error, Debug)]
pub enum AppError {
    #[error("IO error")]
    Io(#[from] std::io::Error),

    #[error("Database error")]
    Database(#[from] sqlx::Error),
}

This allows the ? operator to automatically convert these errors to AppError.

Pattern 4: Source Error Chain with #[source]

What to Look For:

Errors that wrap other errors but need custom messages
Need for error source chain

Pattern:

use thiserror::Error;

#[derive(Error, Debug)]
pub enum ConfigError {
    // #[source] preserves error chain without #[from]
    #[error("Failed to load config file")]
    LoadFailed(#[source] std::io::Error),

    // #[source] with custom error info
    #[error("Invalid config format in {file}")]
    InvalidFormat {
        file: String,
        #[source]
        source: toml::de::Error,
    },

    // Both message customization and error chain
    #[error("Missing required field: {field}")]
    MissingField {
        field: String,
        #[source]
        source: Box<dyn std::error::Error + Send + Sync>,
    },
}

Difference from #[from]:

#[from]: Implements From trait (automatic conversion)
#[source]: Only marks as source error (manual construction)

Suggestion Template:

Use #[source] when you need custom error construction but want to preserve the error chain:

#[derive(Error, Debug)]
pub enum MyError {
    #[error("Operation failed for user {user_id}")]
    OperationFailed {
        user_id: String,
        #[source]
        source: DatabaseError,
    },
}

// Construct manually with context
return Err(MyError::OperationFailed {
    user_id: id.to_string(),
    source: db_error,
});

Pattern 5: Transparent Error Forwarding

What to Look For:

Wrapper errors that should forward to inner error
Need for transparent error propagation

Pattern:

use thiserror::Error;

#[derive(Error, Debug)]
pub enum WrapperError {
    // Transparent forwards all Display/source to inner error
    #[error(transparent)]
    Inner(#[from] InnerError),
}

// Example: Wrapper for anyhow in library
#[derive(Error, Debug)]
pub enum LibError {
    #[error(transparent)]
    Other(#[from] anyhow::Error),
}

Use Cases:

Wrapping errors without changing their display
Re-exporting errors from dependencies
Internal error handling that shouldn't change messages

Suggestion Template:

Use #[error(transparent)] to forward all error information to the inner error:

#[derive(Error, Debug)]
pub enum MyError {
    #[error(transparent)]
    Wrapped(#[from] InnerError),
}

This preserves the inner error's Display and source chain completely.

Pattern 6: Layered Errors

What to Look For:

Applications with multiple layers (domain, infrastructure, etc.)
Need for error conversion between layers

Pattern:

use thiserror::Error;

// Domain layer errors
#[derive(Error, Debug)]
pub enum DomainError {
    #[error("Invalid user data: {0}")]
    InvalidUser(String),

    #[error("Business rule violated: {0}")]
    BusinessRuleViolation(String),
}

// Infrastructure layer errors
#[derive(Error, Debug)]
pub enum InfraError {
    #[error("Database error")]
    Database(#[from] sqlx::Error),

    #[error("HTTP request failed")]
    Http(#[from] reqwest::Error),
}

// Application layer combines both
#[derive(Error, Debug)]
pub enum AppError {
    #[error("Domain error: {0}")]
    Domain(#[from] DomainError),

    #[error("Infrastructure error: {0}")]
    Infra(#[from] InfraError),

    #[error("Application error: {0}")]
    Application(String),
}

Suggestion Template:

For layered architectures, create error types for each layer:

// Domain layer
#[derive(Error, Debug)]
pub enum DomainError {
    #[error("Invalid data: {0}")]
    Invalid(String),
}

// Infrastructure layer
#[derive(Error, Debug)]
pub enum InfraError {
    #[error("Database error")]
    Database(#[from] sqlx::Error),
}

// Application layer combines both
#[derive(Error, Debug)]
pub enum AppError {
    #[error("Domain: {0}")]
    Domain(#[from] DomainError),

    #[error("Infra: {0}")]
    Infra(#[from] InfraError),
}

Advanced Patterns

Pattern 7: Generic Error Types

use thiserror::Error;

#[derive(Error, Debug)]
pub enum OperationError<T>
where
    T: std::error::Error + 'static,
{
    #[error("Operation failed")]
    Failed(#[source] T),

    #[error("Timeout after {0} seconds")]
    Timeout(u64),
}

Pattern 8: Conditional Compilation

use thiserror::Error;

#[derive(Error, Debug)]
pub enum MyError {
    #[error("IO error")]
    Io(#[from] std::io::Error),

    #[cfg(feature = "postgres")]
    #[error("Database error")]
    Database(#[from] sqlx::Error),

    #[cfg(feature = "redis")]
    #[error("Cache error")]
    Cache(#[from] redis::RedisError),
}

Pattern 9: Enum with Unit and Complex Variants

use thiserror::Error;

#[derive(Error, Debug)]
pub enum ValidationError {
    // Unit variant
    #[error("Value is required")]
    Required,

    // Tuple variant
    #[error("Invalid format: {0}")]
    InvalidFormat(String),

    // Struct variant
    #[error("Out of range (expected {expected}, got {actual})")]
    OutOfRange { expected: String, actual: String },

    // Nested error
    #[error("Validation failed")]
    Nested(#[from] SubValidationError),
}

Best Practices

DO: Clear, Actionable Error Messages

#[derive(Error, Debug)]
pub enum ConfigError {
    // ✅ Clear and actionable
    #[error("Config file not found at '{path}'. Create one using: config init")]
    NotFound { path: String },

    // ✅ Explains what's wrong and expected format
    #[error("Invalid port number '{port}'. Expected a number between 1 and 65535")]
    InvalidPort { port: String },
}

DON'T: Vague Error Messages

#[derive(Error, Debug)]
pub enum BadError {
    // ❌ Too vague
    #[error("Error")]
    Error,

    // ❌ Not helpful
    #[error("Something went wrong")]
    Failed,
}

DO: Include Context

#[derive(Error, Debug)]
pub enum AppError {
    // ✅ Includes what, where, and source
    #[error("Failed to read file '{path}'")]
    ReadFailed {
        path: String,
        #[source]
        source: std::io::Error,
    },
}

DO: Type Aliases for Result

pub type Result<T> = std::result::Result<T, MyError>;

// Now you can use:
pub fn operation() -> Result<Value> {
    Ok(value)
}

Common Mistakes

Mistake 1: Forgetting #[source]

// ❌ BAD: Source error not marked
#[derive(Error, Debug)]
pub enum MyError {
    #[error("Failed")]
    Failed(std::io::Error),  // Missing #[source]
}

// ✅ GOOD: Properly marked
#[derive(Error, Debug)]
pub enum MyError {
    #[error("Failed")]
    Failed(#[source] std::io::Error),
}

Mistake 2: Using #[from] When You Need Custom Construction

// ❌ Can't add context with #[from]
#[derive(Error, Debug)]
pub enum MyError {
    #[error("Failed")]
    Failed(#[from] std::io::Error),
}

// ✅ Use #[source] for custom construction
#[derive(Error, Debug)]
pub enum MyError {
    #[error("Failed to read config file '{path}'")]
    ConfigReadFailed {
        path: String,
        #[source]
        source: std::io::Error,
    },
}

Your Approach

Detect: Identify error type definitions or thiserror usage
Analyze: Check message clarity, source chaining, and conversions
Suggest: Provide specific improvements
Educate: Explain when to use #[from] vs #[source] vs #[transparent]

Communication Style

Suggest thiserror for any custom error type
Explain the difference between #[from], #[source], and #[transparent]
Provide complete error type examples
Show how the error will be displayed
Point out missing error chains

When you see custom error types, immediately suggest thiserror patterns that will make them more ergonomic and idiomatic.

Thiserror Expert

File contents

Thiserror Expert Skill

When to Activate

Thiserror Patterns

Pattern 1: Basic Error Enum

Pattern 2: Error Messages with Fields

Pattern 3: Wrapping Source Errors with #[from]

Pattern 4: Source Error Chain with #[source]

Pattern 5: Transparent Error Forwarding

Pattern 6: Layered Errors

Advanced Patterns

Pattern 7: Generic Error Types

Pattern 8: Conditional Compilation

Pattern 9: Enum with Unit and Complex Variants

Best Practices

DO: Clear, Actionable Error Messages

DON'T: Vague Error Messages

DO: Include Context

DO: Type Aliases for Result

Common Mistakes

Mistake 1: Forgetting #[source]

Mistake 2: Using #[from] When You Need Custom Construction

Your Approach

Communication Style

Frequently asked questions

Thiserror Expert

File contents

Thiserror Expert Skill

When to Activate

Thiserror Patterns

Pattern 1: Basic Error Enum

Pattern 2: Error Messages with Fields

Pattern 3: Wrapping Source Errors with #[from]

Pattern 4: Source Error Chain with #[source]

Pattern 5: Transparent Error Forwarding

Pattern 6: Layered Errors

Advanced Patterns

Pattern 7: Generic Error Types

Pattern 8: Conditional Compilation

Pattern 9: Enum with Unit and Complex Variants

Best Practices

DO: Clear, Actionable Error Messages

DON'T: Vague Error Messages

DO: Include Context

DO: Type Aliases for Result

Common Mistakes

Mistake 1: Forgetting #[source]

Mistake 2: Using #[from] When You Need Custom Construction

Your Approach

Communication Style

Related skills

Frequently asked questions

How do I install the Thiserror Expert skill?

What does the Thiserror Expert skill do?

Is Thiserror Expert safe to use?

Which AI agents work with Thiserror Expert?

Is Thiserror Expert free to use?

Who published Thiserror Expert?