learner_skill

Overview

This skill extracts a reusable engineering insight from a troubleshooting session and saves it as a durable, searchable lesson for future agents. It focuses on principles and decision heuristics rather than copy-paste fixes, so Claude learns how to approach a class of problems across this codebase. The skill enforces quality checks so only non-trivial, context-rich discoveries are recorded.

How this skill works

When invoked after resolving a tricky bug or uncovering an undocumented behavior, the skill collects a precise problem statement, the exact fix, failure triggers, and scope. It validates that the insight is non-Googleable, context-specific, and actionable. Finally, it saves the formatted skill to the project-level skills folder with required metadata and body structure.

When to use it

• After solving a bug that required deep debugging or unusual investigation
• When you find a workaround or behavior specific to this codebase not documented elsewhere
• If the fix includes exact file paths, error messages, and exact code/config changes
• When the insight changes how Claude should reason about a class of problems
• Before saving any lesson that might be mistaken for generic programming advice

Best practices

• Collect precise evidence: error messages, file paths, line numbers, and minimal repro steps
• Record the exact code or configuration change that fixed the issue, not vague guidance
• Provide trigger keywords or fragments that reliably surface the same problem later
• Mark scope explicitly—default to project-level unless truly portable
• Reject anything easily searchable, overly generic, or lacking precise instructions

Example use cases

• Capture a race condition fix that required changing await placement in worker.ts
• Save a workaround for an undocumented library quirk found in server.py:42
• Document an ESM path resolution gotcha requiring fileURLToPath in this repo's build
• Record a specific null-check and session regeneration needed to avoid a TypeError
• Store a trigger set for a recurring CI failure tied to a particular config mismatch