Forge Skill
Typically runs automatically via SessionEnd hook.
Extract knowledge from session transcripts.
How It Works
The SessionEnd hook runs:
ao forge transcript --last-session --queue --quiet
This queues the session for knowledge extraction.
Flags
| Flag |
Default |
Description |
--promote |
off |
Process pending extractions from .agents/knowledge/pending/ and promote to .agents/learnings/. Absorbs the former extract skill. |
Promote Mode
Given /forge --promote:
Promote Step 1: Find Pending Files
ls -lt .agents/knowledge/pending/*.md 2>/dev/null
ls -lt .agents/ao/pending.jsonl 2>/dev/null
If no pending files found, report "No pending extractions" and exit.
Promote Step 2: Process Each Pending File
For each file in .agents/knowledge/pending/:
- Read the file content
- Validate it has required fields (
# Learning:, **Category**:, **Confidence**:)
- Copy to
.agents/learnings/ (preserving filename)
- Remove the source file from
.agents/knowledge/pending/
Promote Step 3: Process Pending Queue
if [ -f .agents/ao/pending.jsonl ] && [ -s .agents/ao/pending.jsonl ]; then
cat .agents/ao/pending.jsonl
> .agents/ao/pending.jsonl
fi
Promote Step 4: Report
Promoted N learnings from pending → .agents/learnings/
Queue cleared.
Done. Return immediately after reporting.
Manual Execution
Given /forge [path]:
Step 1: Identify Transcript
With ao CLI:
ao forge transcript --last-session
ao forge transcript <path>
Without ao CLI:
Look at recent conversation history and extract learnings manually.
Step 2: Extract Knowledge Types
Read skills/forge/references/uncaptured-lesson-patterns.md for signal patterns and the 26 known uncaptured lesson categories.
Look for these patterns in the transcript:
| Type |
Signals |
Weight |
| Decision |
"decided to", "chose", "went with" |
0.8 |
| Learning |
"learned that", "discovered", "realized" |
0.9 |
| Failure |
"failed because", "broke when", "didn't work" |
1.0 |
| Pattern |
"always do X", "the trick is", "pattern:" |
0.7 |
Uncaptured Lesson Matching: During transcript scanning, match events against the 26 known uncaptured lesson patterns (see references/uncaptured-lesson-patterns.md). Pre-fill learning templates with matched pattern metadata (category, base confidence, pattern number tag).
Step 3: Write Candidates
Write to: .agents/forge/YYYY-MM-DD-forge.md
# Forged: YYYY-MM-DD
## Decisions
- [D1] <decision made>
- Source: <where in conversation>
- Confidence: <0.0-1.0>
## Learnings
- [L1] <what was learned>
- Source: <where in conversation>
- Confidence: <0.0-1.0>
## Failures
- [F1] <what failed and why>
- Source: <where in conversation>
- Confidence: <0.0-1.0>
## Patterns
- [P1] <reusable pattern>
- Source: <where in conversation>
- Confidence: <0.0-1.0>
Step 4: Index for Search
if command -v ao &>/dev/null; then
ao forge markdown .agents/forge/YYYY-MM-DD-forge.md 2>/dev/null
else
mkdir -p .agents/learnings .agents/ao
for f in .agents/forge/YYYY-MM-DD-*.md; do
[ -f "$f" ] || continue
CONF=$(grep -i "confidence:" "$f" | head -1 | awk '{print $NF}')
case "$CONF" in
high) CONF_NUM=0.9 ;; medium) CONF_NUM=0.6 ;; low) CONF_NUM=0.3 ;; *) CONF_NUM=$CONF ;;
esac
if (( $(echo "$CONF_NUM >= 0.7" | bc -l) )); then
{ printf -- '---\ntype: learning\nsource: forge\ndate: %s\nmaturity: provisional\nutility: 0.5\n---\n' "$(date +%Y-%m-%d)"; cat "$f"; } > .agents/learnings/"$(basename "$f")"
TITLE=$(head -1 "$f" | sed 's/^# //')
echo "{\"file\": \".agents/learnings/$(basename $f)\", \"title\": \"$TITLE\", \"keywords\": [], \"timestamp\": \"$(date -Iseconds)\"}" >> .agents/ao/search-index.jsonl
echo "Auto-promoted (confidence $CONF): $(basename $f)"
fi
done
echo "Forge indexing complete (ao CLI not available — high-confidence candidates auto-promoted)"
fi
Step 5: Update Capture Tracking
After extracting learnings that match uncaptured lesson patterns (Step 2), record which patterns were captured. This state lives in .agents/forge/capture-tracking.json (a runtime artifact, never in skills/).
mkdir -p .agents/forge
- Read
.agents/forge/capture-tracking.json if it exists, otherwise start with {}
- For each matched pattern, add or update an entry keyed by pattern number:
{
"3": {"captured": true, "date": "2026-03-30", "learning_path": ".agents/learnings/tooling/use-bin-cp.md"},
"7": {"captured": true, "date": "2026-03-29", "learning_path": ".agents/learnings/operations/worktree-commit.md"}
}
- Write the updated JSON back to
.agents/forge/capture-tracking.json
Pattern numbers correspond to the numbered headings in references/uncaptured-lesson-patterns.md (1-30, 26 total patterns).
Step 6: Report Results
Tell the user:
- Number of items extracted by type
- Location of forge output
- Candidates ready for promotion to learnings
- Capture progress: "X/26 uncaptured lesson patterns captured" (read from
.agents/forge/capture-tracking.json)
The Quality Pool
Forged candidates enter at Tier 0:
Transcript → /forge → .agents/forge/ (Tier 0)
↓
Human review or 2+ citations
OR auto-promote (confidence >= 0.7, ao-free fallback)
↓
.agents/learnings/ (Tier 1)
Key Rules
- Runs automatically - usually via hook
- Extract, don't interpret - capture what was said
- Score by confidence - not all extractions are equal
- Queue for review - candidates need validation
Examples
SessionEnd Hook Invocation
Hook triggers: session-end.sh runs when session ends
What happens:
- Hook calls
ao forge transcript --last-session --queue --quiet
- CLI analyzes session transcript for decisions, learnings, failures, patterns
- CLI writes session ID to
.agents/ao/pending.jsonl queue
- Next session start triggers
/forge --promote to process the queue
Result: Session transcript automatically queued for knowledge extraction without user action.
Manual Transcript Mining
User says: /forge <path> or "mine this transcript for knowledge"
What happens:
- Agent identifies transcript path or uses
ao forge transcript --last-session
- Agent scans transcript for knowledge patterns (decisions, learnings, failures, patterns)
- Agent scores each extraction by confidence (0.0-1.0)
- Agent writes candidates to
.agents/forge/YYYY-MM-DD-forge.md
- Agent indexes forge output with
ao forge markdown
- Agent reports extraction counts and candidate locations
Result: Transcript mined for reusable knowledge, candidates ready for human review or 2+ citations promotion.
Troubleshooting
| Problem |
Cause |
Solution |
| No extractions found |
Transcript lacks knowledge signals or ao CLI unavailable |
Check transcript contains decisions/learnings; verify ao CLI installed |
| Low confidence scores |
Weak signals or vague conversation |
Focus sessions on concrete decisions and explicit learnings |
| forge --queue fails |
CLI not available or permission error |
Manually append to .agents/ao/pending.jsonl with session metadata |
| Duplicate forge outputs |
Same session forged multiple times |
Check forge filenames before writing; ao CLI handles dedup automatically |
Reference Documents
