Self-Learning Skill
Minimum Model
Any model for logging. Use a medium model for writing behavioral rules to SOUL.md.
The Learning Loop
Event happens → Log it immediately → Weekly: find patterns → Promote to config → Verify next week
Part 1 — Log Events (Do Immediately)
When to Log
| Trigger | File | Category |
|---|
| Owner corrects you | LEARNINGS.md | correction |
| Task fails | ERRORS.md | — |
| Better approach found | LEARNINGS.md | best_practice |
| Owner asks for missing capability | FEATURE_REQUESTS.md | — |
| Information was outdated | LEARNINGS.md | knowledge_gap |
| Same mistake twice | LEARNINGS.md | pattern |
| Owner praises something | LEARNINGS.md | positive_signal |
| Acted outside role | LEARNINGS.md | scope_error |
| Forgot past context | LEARNINGS.md | memory_gap |
Rule: Log the event before replying to the owner. Don't delay.
Log Format
## [YYYY-MM-DD] | category | short title
**Trigger:** What happened
**Context:** What I was trying to do
**What went wrong / what worked:**
**Root cause:**
**Correct behavior going forward:**
**Applied to:** [SOUL.md / AGENTS.md / TOOLS.md / none yet]
Quick Log Script
#!/bin/bash
set -e
LEARNINGS_DIR="$HOME/.openclaw/workspace/.learnings"
mkdir -p "$LEARNINGS_DIR"
LOG_FILE="$LEARNINGS_DIR/LEARNINGS.md"
DATE=$(date +%Y-%m-%d)
# First arg: category (default: correction)
CATEGORY="${1:-correction}"
# Second arg: short title
TITLE="${2:-Short description}"
# Append a new entry to the log
cat >> "$LOG_FILE" << EOF
## [$DATE] | $CATEGORY | $TITLE
**Trigger:**
**Context:**
**What went wrong:**
**Root cause:**
**Correct behavior:**
**Applied to:** none yet
EOF
echo "Logged to $LOG_FILE"
Usage:
./quick-log.sh "correction" "Sent message without confirming with owner"
Part 2 — Weekly Reflection
Run every 7 days. Find patterns across log entries.
Pattern Detection Script
#!/bin/bash
set -e
LEARNINGS_FILE="$HOME/.openclaw/workspace/.learnings/LEARNINGS.md"
# Exit cleanly if no file yet
if [ ! -f "$LEARNINGS_FILE" ]; then
echo "No learnings file at $LEARNINGS_FILE"
exit 0
fi
echo "=== Corrections (most common) ==="
grep "correction" "$LEARNINGS_FILE" \
| sed 's/.*| //' \
| sort \
| uniq -c \
| sort -rn \
| head -10
echo ""
echo "=== All Categories ==="
grep -oP '\| \K\w+(?= \|)' "$LEARNINGS_FILE" \
| sort \
| uniq -c \
| sort -rn
Weekly Reflection Template
# Weekly Reflection — YYYY-MM-DD
## Stats
- Corrections logged: X
- Errors logged: X
- Best practices logged: X
## Top Patterns (appeared 2+ times)
1.
2.
## Priority Fixes Applied This Week
- [ ] Updated SOUL.md:
- [ ] Updated AGENTS.md:
- [ ] Updated TOOLS.md:
## Positive Signals (do more of this)
-
Part 3 — Promote Learnings to Config
After identifying a pattern, update the right config file.
Where to Promote
| Learning Type | Promote To |
|---|
| Communication rule | SOUL.md → Communication section |
| Behavior pattern | SOUL.md → Execution rules |
| Workspace convention | AGENTS.md |
| Tool-specific note | TOOLS.md |
| Contact / credentials | MEMORY.md |
| Recurring task improvement | HEARTBEAT.md |
Rule: If the same mistake appears 2+ times → promote it. Once is a log; twice is a rule.
Promote Script
#!/bin/bash
set -e
SOUL_FILE="$HOME/.openclaw/workspace/SOUL.md"
LEARNINGS_FILE="$HOME/.openclaw/workspace/.learnings/LEARNINGS.md"
DATE=$(date +%Y-%m-%d)
# Replace this placeholder with the actual rule text before running
RULE="[Replace this with the actual rule text]"
# Verify SOUL.md exists
if [ ! -f "$SOUL_FILE" ]; then
echo "ERROR: SOUL.md not found at $SOUL_FILE"
exit 1
fi
# Append the new learned rule to SOUL.md
printf "\n## Learned Rule — %s\n- %s\n" "$DATE" "$RULE" >> "$SOUL_FILE"
echo "Added rule to SOUL.md"
# Mark the entry as applied in LEARNINGS.md (Linux and macOS compatible)
if [ -f "$LEARNINGS_FILE" ]; then
if sed --version 2>/dev/null | grep -q GNU; then
# Linux (GNU sed)
sed -i "s/Applied to: none yet/Applied to: SOUL.md ($DATE)/" "$LEARNINGS_FILE"
else
# macOS (BSD sed)
sed -i '' "s/Applied to: none yet/Applied to: SOUL.md ($DATE)/" "$LEARNINGS_FILE"
fi
echo "Marked as applied in LEARNINGS.md"
fi
Part 4 — Verify (Next Week)
Check: did the behavior actually change?
## Verification Check — YYYY-MM-DD
| Learning | Applied? | Behavior Changed? | Notes |
|---|---|---|---|
| [Title] | ✅ | ✅ | Working |
| [Title] | ✅ | ❌ | Needs a stronger rule |
If behavior didn't change → revise the rule with more explicit wording and re-apply.
Monthly Combined Report
#!/bin/bash
LEARNINGS_DIR="$HOME/.openclaw/workspace/.learnings"
echo "=== Monthly Learning Report ==="
LEARNINGS_FILE="$LEARNINGS_DIR/LEARNINGS.md"
ERRORS_FILE="$LEARNINGS_DIR/ERRORS.md"
FEATURES_FILE="$LEARNINGS_DIR/FEATURE_REQUESTS.md"
# Helper: count matching lines (returns 0 if file missing)
count_matches() {
local file="$1"
local pattern="$2"
grep -c "$pattern" "$file" 2>/dev/null || echo 0
}
# Print counts per file
if [ -f "$LEARNINGS_FILE" ]; then
echo "Corrections: $(count_matches "$LEARNINGS_FILE" 'correction')"
echo "Positive signals: $(count_matches "$LEARNINGS_FILE" 'positive_signal')"
fi
if [ -f "$ERRORS_FILE" ]; then
echo "Error entries: $(wc -l < "$ERRORS_FILE")"
fi
if [ -f "$FEATURES_FILE" ]; then
echo "Feature requests: $(count_matches "$FEATURES_FILE" '^##')"
fi
Cost Tips
- Cheap: Logging a single correction — very few tokens.
- Expensive: Writing nuanced behavioral rules — use a medium model for this step.
- Batch: Review all weekly logs at once during the monthly reflection, not one by one.
- Small model OK: Pattern detection is mostly grep — no model needed for that step.
Phase 2: Reflection (Merged from self-reflection skill)
When the owner wants to improve how you operate, follow this structured process. Goal: turn vague dissatisfaction into specific, technical changes.
Reflection Process
1. Understand the Problem (2–3 questions max)
Ask focused questions to pin down:
- What specifically is wrong? (Get a concrete example)
- What would "good" look like? (Expected vs actual behavior)
- How important is this? (Tweak vs fundamental change)
If the complaint is clear enough, skip to step 2.
2. Deep System Scan
Read ALL relevant parts before changing anything:
- Core identity: SOUL.md, AGENTS.md, USER.md, MEMORY.md, TOOLS.md
- All active skills (custom + bundled + workspace)
- Configuration (model, tools, channels, heartbeat, cron jobs)
Read broadly, change surgically.
3. Diagnose & Propose
Present findings:
- Root cause — what causes the unwanted behavior
- Proposed changes — specific files and edits
- Side effects — anything else affected
- Alternatives — if multiple approaches exist
4. Implement (after approval)
- Edit workspace files (persona, memory, etc.)
- Edit/create/modify skills
- Update config and cron jobs
- Every change must be technically concrete. "I'll be more careful" is NOT a valid change.
5. Verify & Document
- Test the change if possible
- Document what changed and why
- Commit workspace changes
Key principles:
- Scan everything, change only what's needed
- No fake fixes — if no technical change is possible, say so
- Compound improvements — each reflection makes the system permanently better
Part 4 — HOT.md (Rules You Keep Breaking)
Inspired by Jarvis.
What It Is
HOT.md is a short file (≤20 lines) read before every reply. It contains only rules you've broken 2+ times. Not documentation — active behavioral correction.
When to Create / Update
- A rule appears in Part 1 logs twice or more → promote to HOT.md
- HOT.md grows beyond 20 lines → you have a discipline problem, not a documentation problem. Fix the behavior, don't add more lines.
- A rule stays unbroken for 30+ days → move it to SOUL.md permanently, remove from HOT.md
Format
# HOT.md — Rules I Keep Breaking
_Read before every reply. Max 20 lines. If it's not here, it doesn't count._
- [Rule 1 — short, imperative] (broken N times)
- [Rule 2] (broken N times)
Promotion Flow
Log (Part 1) → Pattern 2x (Part 3 weekly) → HOT.md → 30 days clean → SOUL.md permanent
Key Rule
If it should apply to EVERY interaction → SOUL.md.
If you keep forgetting it → HOT.md first, SOUL.md after 30 clean days.
This is also why dynamic-temperature and proactive-pa were merged into SOUL.md — rules for every interaction don't belong in skills.
