菜单
WHEN: You've discovered something worth capturing — a pattern, a gotcha, a process improvement — and want to preserve it so future sessions can benefit. Invoke at end of session or when asked to 'save this insight', 'capture learning', 'log lesson'.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
WHEN: You need to detect performance regressions before merge — TTFB, response time, bundle size. Run as part of forge-eval-gate or standalone before raising a PR.
WHEN: A decision is being superseded, deprecated, or has aged out. Archive it without deletion — marks as warm→cold→archived with full audit trail.
WHEN: You are writing a new decision, superseding an old one, or querying relationships across decisions. Create semantic edges between decisions and link concepts across products/projects/time.
WHEN: You are about to make a decision and need to check if prior art or past learnings exist. Recall decisions, patterns, and gotchas from the brain before proceeding.
WHEN: You need to trace the full provenance of a specific decision — who made it, when, why, and what alternatives were considered. Shows why, when, by whom, evidence, alternatives, outcome.
WHEN: You need to record a decision, lock a spec, log an eval run, or document learnings in the brain.
| name | learn |
| description | WHEN: You've discovered something worth capturing — a pattern, a gotcha, a process improvement — and want to preserve it so future sessions can benefit. Invoke at end of session or when asked to 'save this insight', 'capture learning', 'log lesson'. |
| type | flexible |
| version | 1.0.1 |
| preamble-tier | 2 |
| triggers | ["what did we learn","capture learning","save this insight","log lesson","remember this for next time"] |
| allowed-tools | ["Bash","Write","AskUserQuestion"] |
Writes session learnings to brain so future sessions benefit. Unlike brain-write (formal decisions), learn captures soft knowledge: patterns, gotchas, process improvements.
| Skill | Captures | Writes to | When |
|---|---|---|---|
learn | Reusable patterns, gotchas, process insights — things useful in future tasks | ~/forge/brain/learnings/<slug>.md | During or after any task, when a non-obvious pattern is discovered |
retro | Post-task reflection — what went well, what to improve, time/effort reality vs. estimate | ~/forge/brain/prds/<task-id>/retro.md | After a task completes (post-PR), before next sprint |
brain-write | Formal decisions with rationale (technical or product choices, contract records) | ~/forge/brain/prds/<task-id>/decisions/<id>.md | At the moment a decision is made — not retrospective |
Rule of thumb: "This will help me on the next PRD" → learn. "This reflects how this task went" → retro. "I just decided X because Y" → brain-write.
This skill lists AskUserQuestion in allowed-tools — canonical for Claude Code and skill lint. Map to the host’s blocking interactive prompt per skills/using-forge/SKILL.md Blocking interactive prompts (Cursor AskQuestion; hosts without the tool: numbered options + stop). See using-forge Interactive human input.
| Rationalization | Why It Fails |
|---|---|
| "I'll remember this next time" | Context windows reset. Sessions end. Knowledge not written is knowledge lost. |
| "The git commit message has this" | Commit messages describe what changed, not what you learned about the system. |
| "brain-write is for this" | brain-write is for decisions. learn is for insights. Different audiences, different formats. |
Write it now. The next session won't have this context.
/learn — interactive: asks for category and insight/learn "pattern: always check X before Y on this service" — inline, no prompts| Category | When to use |
|---|---|
pattern | A reusable approach discovered (e.g., "always flush cache before running eval") |
gotcha | A non-obvious trap (e.g., "Kafka consumer group IDs must be unique per eval run") |
process | A workflow improvement (e.g., "run eval with --verbose when diagnosing YELLOW") |
If invoked as bare /learn, use a blocking interactive prompt per using-forge — e.g. AskQuestion with options pattern | gotcha | process, then a follow-up for one-sentence insight (or a single multi-field prompt if the host supports it). Do not rely on prose-only what’s the category and insight? with no AskQuestion / numbered options in the same turn.
If invoked as /learn "<category>: <insight>", parse directly — no prompting.
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
FILEDATE=$(date -u +"%Y%m%d")
RAW="${INSIGHT}"
SLUG=$(echo "$RAW" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9-]/-/g' | sed 's/--*/-/g' | cut -c1-40)
BRAIN_DIR="${FORGE_BRAIN:-${FORGE_BRAIN_PATH:-$HOME/forge/brain}}/learnings"
mkdir -p "$BRAIN_DIR"
FILENAME="${FILEDATE}-${SLUG}.md"
Write $BRAIN_DIR/$FILENAME with this structure:
---
category: <pattern|gotcha|process>
date: <ISO8601>
session: <BRANCH>
---
# <Insight as a short title>
<The learning in 1-3 sentences. Concrete and specific — not "be careful" but exactly what to do or avoid.>
## Context
<What situation surfaced this learning — 1-2 sentences.>
## Apply When
<When a future session should recall this: what scenario triggers it.>
Fill all sections with actual content. Do not write placeholder text.
cd "$(git rev-parse --show-toplevel)"
git add "$BRAIN_DIR/$FILENAME"
git commit -m "learn($CATEGORY): $SLUG"
LEARNING SAVED
Category: <category>
File: ~/forge/brain/learnings/<filename>
Branch: <branch>