| name | learn |
| description | Save session learnings as a new skill plugin. Use after experiments, debugging sessions, or when you want to preserve team knowledge. |
| user-invocable | false |
/learn
Capture session learnings and create a new skill plugin with PR.
Overview
| Item | Details |
|---|
| Date | 2025-12-29 |
| Objective | Automate knowledge capture from sessions into searchable skill plugins |
| Outcome | ✅ Operational |
When to Use
- After completing an experiment (successful or failed)
- After debugging a tricky issue
- After implementing a new pattern
- When you want to preserve learnings for the team
- Automatically prompted on session-ending keywords (if hooks configured)
Common Mistakes and Fixes
| Mistake | Symptom | Fix |
|---|
Forgot .claude-plugin/plugin.json | "Missing .claude-plugin/plugin.json" | Create with name, version, description, category, date |
| Description < 20 chars | "Description too short" | Add "Use when:" trigger conditions |
| Failed Attempts as prose | "should contain a table" | Use pipe-delimited table format |
| Missing frontmatter | "missing YAML frontmatter" | Add --- delimiters at top of SKILL.md |
| Wrong category | "Invalid category" | Use one of 9 approved categories |
## Workflow instead of ## Verified Workflow | "Missing Verified Workflow section" | Use exact header name |
| SessionEnd hook | Hook doesn't display messages to user | Use UserPromptSubmit hook instead |
| Committed without validating | PR fails CI | Run python3 scripts/validate_plugins.py skills/ before commit |
Failed Attempts
| Attempt | Why Failed | Lesson Learned |
|---|
| Auto-trigger on every session | User fatigue from constant prompts | Use >10 messages threshold |
| Generic skill names | Hard to find later via /advise | Enforce kebab-case with category prefix |
| Optional Failed Attempts section | Most valuable content missing | Make failures REQUIRED in template |
| Single references/notes.md | Information overload in one file | Split into experiment-log + troubleshooting |
| No environment capture | "Works on my machine" problems | Add environment table to Overview section |
| Committing without validation | Bad plugins entered registry | Run validate_plugins.py before commit |
Results & Parameters
N/A — this skill describes a workflow pattern.
References
- See
commands/learn.md for the full command implementation
- See
validation-workflow for CI validation details
- See
documentation-patterns for writing quality skills
