introspection_skill

Overview

This skill analyzes and explains Claude's reasoning, decision patterns, and problem-solving approaches to make thinking transparent and actionable. It converts implicit judgment into explicit chains of reasoning, highlights recurring patterns, and surfaces opportunities for improvement. Use it when you need error recovery, decision transparency, or structured learning.

How this skill works

The skill inspects decision traces, choice points, and outcome comparisons to expose reasoning chains and alternatives. It applies a consistent marker format (🧠, 🔄, 🎯, 🔍, 📊, ⚡, 💡) to document why an approach was chosen, what was considered, expected vs actual outcomes, pattern matches, compliance checks, optimizations, and lessons learned. Outputs are concise, structured reflections you can act on or automate into checklists and fixes.

When to use it

• When a user requests “explain your reasoning” or “show your thinking”.
• After an unexpected outcome or failed solution to diagnose root causes.
• During code reviews or architectural decision documentation for transparency.
• When optimizing recurring tasks or detecting repeated errors.
• To validate choices against quality principles or standards.

Best practices

• Start with an explicit reasoning marker (🧠) describing the primary rationale.
• List clear alternatives (🔄) and why they were rejected or deferred.
• Compare expected vs actual outcomes (🎯) to locate assumption failures.
• Search for similar cases (🔍) across recent commits or logs to find patterns.
• Include a compliance check (📊) against applicable principles and concrete optimization steps (⚡).

Example use cases

• Explain why a particular library or tool was chosen for a feature and show trade-offs.
• Diagnose recurring authentication failures by tracing assumptions and similar incidents.
• Document the decision process for a refactor and capture reusable patterns and hooks.
• Post-implementation review that extracts lessons learned and next-step action items.
• Create a pre-request validation checklist after multiple API token errors.