/learn — Skill Extraction Workflow
Extract non-obvious discoveries into reusable skills that persist across sessions.
When to Use This Skill
Invoke /learn when you encounter:
- Non-obvious debugging — Investigation that took significant effort, not in docs
- Misleading errors — Error message was wrong, found the real cause
- Workarounds — Found a limitation with a creative solution
- Tool integration — Undocumented API usage or configuration
- Trial-and-error — Multiple attempts before success
- Repeatable workflows — Multi-step task you'd do again
- User-facing automation — Reports, checks, or processes users will request
Workflow Phases
PHASE 1: Evaluate (Self-Assessment)
Before creating a skill, answer these questions:
- "What did I just learn that wasn't obvious before starting?"
- "Would future-me benefit from this being documented?"
- "Was the solution non-obvious from documentation alone?"
- "Is this a multi-step workflow I'd repeat?"
Continue only if YES to at least one question.
PHASE 2: Check Existing Skills
Search for related skills to avoid duplication:
# Check project skills
ls .claude/skills/ 2>/dev/null
# Search for keywords
grep -r -i "KEYWORD" .claude/skills/ 2>/dev/nullOutcomes:
- Nothing related → Create new skill (continue to Phase 3)
- Same trigger & fix → Update existing skill (bump version)
- Partial overlap → Update with new variant
PHASE 3: Create Skill
Create the skill file at .claude/skills/[skill-name]/SKILL.md:
---
name: descriptive-kebab-case-name
description: |
[CRITICAL: Include specific triggers in the description]
- What the skill does
- Specific trigger conditions (exact error messages, symptoms)
- When to use it (contexts, scenarios)
author: Claude Code Academic Workflow
version: 1.0.0
argument-hint: "[expected arguments]" # Optional
---
# Skill Name
## Problem
[Clear problem description — what situation triggers this skill]
## Context / Trigger Conditions
[When to use — exact error messages, symptoms, scenarios]
[Be specific enough that you'd recognize it again]
## Solution
[Step-by-step solution]
[Include commands, code snippets, or workflows]
## Verification
[How to verify it worked]
[Expected output or state]
## Example
[Concrete example of the skill in action]
## References
[Documentation links, related files, or prior discussions]PHASE 4: Quality Gates
Before finalizing, verify:
- Description has specific trigger conditions (not vague)
- Solution was verified to work (tested)
- Content is specific enough to be actionable
- Content is general enough to be reusable
- No sensitive information (credentials, personal data)
- Skill name is descriptive and uses kebab-case
Output
After creating the skill, report:
✓ Skill created: .claude/skills/[name]/SKILL.md
Trigger: [when to use]
Problem: [what it solves]Example: Creating a Skill
User discovers that a specific R package silently drops observations:
---
name: fixest-missing-covariate-handling
description: |
Handle silent observation dropping in fixest when covariates have missing values.
Use when: estimates seem wrong, sample size unexpectedly small, or comparing
results between packages.
author: Claude Code Academic Workflow
version: 1.0.0
---
# fixest Missing Covariate Handling
## Problem
The fixest package silently drops observations when covariates have NA values,
which can produce unexpected results when comparing to other packages.
## Context / Trigger Conditions
- Sample size in fixest is smaller than expected
- Results differ from Stata or other R packages
- Model has covariates with potential missing values
## Solution
1. Check for NA patterns before regression:summary(complete.cases(data[, covariates]))
1. Explicitly handle NA values or use `na.action` parameter
2. Document the expected sample size in comments
## Verification
Compare `nobs(model)` with `nrow(data)` — difference indicates dropped obs.
## References
- fixest documentation on missing values
- [LEARN:r-code] entry in MEMORY.md