Skill Experience Layer

Skill Experience Layer - A failure-driven learning mechanism for OpenClaw agents that automatically accumulates lessons and best practices to avoid repeating...

Security Scan

The skill's purpose (recording and applying lessons) is plausible, but the runtime instructions tell the agent to read and write persistent experience files in the user's OpenClaw workspace while the registry metadata does not declare those config paths — and several example files contain hard-coded user-specific paths/IDs; these inconsistencies warrant caution.

Purpose & Capability

The skill claims to be a local 'experience/memory' layer that records lessons about tool usage. That capability reasonably requires reading/writing JSON experience files (which the SKILL.md documents). However the skill metadata declares no required config paths or environment variables even though the docs explicitly reference ~/.openclaw/workspace/memory/experiences and provide install steps that write into that directory. The missing declaration of required config paths is an incoherence (likely an oversight) and should be clarified.

Instruction Scope

SKILL.md instructs the agent to load experience files before tool calls and to update them after failures (i.e., read and write user-local JSON files). That behavior is consistent with the stated purpose, but it grants the skill the ability to read and modify persistent agent memory. The instructions do not limit which categories or paths may be accessed and include examples that hard-code an author home path and user-specific IDs, which could cause unexpected behavior if applied blindly.

Install Mechanism

This is an instruction-only skill with no install spec and no code files. There is no downloaded or executable code; the only install guidance is to copy JSON templates into ~/.openclaw/workspace/memory/experiences. Low technical install risk, but see instruction_scope/persistence concerns about file writes.

Credentials

The skill declares no required environment variables or credentials, which matches there being no external API calls. However, it nonetheless expects and instructs read/write access to the user's ~/.openclaw workspace (not declared in required config paths). Example files include hard-coded author-specific paths (/home/jilanfang/.openclaw/media) and a concrete Feishu open_id (ou_093cfcf39...), which are disproportionate for a generic template and could cause privacy/misattribution or misconfiguration if copied verbatim.

Persistence & Privilege

The skill will create and update persistent JSON experience files in the user's OpenClaw memory directory, which permanently affects agent behavior across runs. It is not set to always:true, and it does not modify other skills' configs per the provided files, but persistent writes to agent memory means this skill can change future tool invocation behavior — review and control what gets written before enabling autonomous updates.

What to consider before installing

This skill is plausible for keeping local 'lessons' about tool failures, but several points need your attention before installing: - Filesystem access: The SKILL.md expects the agent to read and write JSON files under ~/.openclaw/workspace/memory/experiences. The registry metadata did not declare these config paths — confirm you are comfortable with the skill modifying that directory and back up any existing memory files first. - Hard-coded examples: Example JSONs contain author-specific paths (/home/jilanfang/...) and a concrete Feishu open_id (ou_093cfcf...). Do not copy these verbatim into production; replace with your own user IDs and media directories to avoid misattribution and privacy leakage. - Persistent behavior: The skill updates memory files after failures. That is the intended behavior, but it means the skill can permanently change agent behavior. Consider reviewing and approving changes (or running the skill in a sandbox) before allowing it to autonomously update your memory files. - Minimal privileges: Because this skill only works with local JSONs and has no network endpoints or credential requirements, the primary risk is accidental misconfiguration or author-provided defaults. Inspect the example JSONs, update paths/IDs, and ensure file permissions restrict who can read/write the memory folder. If you want to proceed safely: create a dedicated experiences directory, copy templates there, edit examples to remove author-specific IDs/paths, run the skill in a non-autonomous/test agent first, and verify exactly what files it reads/writes and how it names entries. If the publisher can clarify why config paths were omitted from metadata, that would reduce uncertainty.

Skill Experience Layer for OpenClaw

A failure-driven learning mechanism that systematically accumulates experience from tool calls, mistakes, and successes. Each tool/skill category has its own experience file with:

• Lessons learned from failures
• Common mistakes pattern matching
• Preventive best practices
• Statistics tracking (total executions, success/failure counts)

Core Philosophy

"The man who repeats the same mistake and expects different results is a fool." - This mechanism eliminates that.

Every failure is a one-time tuition payment for permanent knowledge.

How It Works

1. Pre-execution Experience Loading

Before any tool call, the agent must:

1. Identify the experience category
2. Read the compact experience file
3. Apply learned best practices
4. Avoid known mistakes

2. Post-execution Experience Update

If the tool call fails:

1. Stop immediately and analyze root cause
2. Add/Update the experience entry
3. Record the mistake and prevention
4. Continue only after updating

If the tool call succeeds:

1. Optionally add high-value best practices
2. Keep experience lean and actionable

3. Weekly/Monthly Maintenance

• Weekly: Remove outdated experiences
• Monthly: Clean up duplicates, consolidate patterns

Experience Category Structure

{
  "type": "skill",
  "name": "tool-name",
  "lastUpdated": "ISO timestamp",
  "totalExecutions": N,
  "successCount": N,
  "failureCount": N,
  "experiences": [
    {
      "mistake": "Description of what went wrong",
      "when": "Context/scenario where it happens",
      "avoidance": "How to avoid this mistake",
      "count": 1
    }
  ],
  "patterns": {
    "commonMistakes": [
      "List of frequent mistakes"
    ],
    "bestPractices": [
      "List of proven best practices"
    ]
  }
}

Built-in Categories

Category	Description
read	File reading, web fetching
write	File writing, editing
edit	Exact text replacement in files
exec	Shell command execution
browser	Browser automation
message	Message sending, media upload
search	Web search tools
feishu	All Feishu/Lark API tools
feishu-*	Fine-grained Feishu sub-skill experiences
memory	Memory search and retrieval
skill	Skill management operations
cron	Cron job scheduling and delivery modes
video-frames	Video frame extraction with ffmpeg

Installation

clawhub install experience-layer

Or manually:

mkdir -p ~/.openclaw/workspace/memory/experiences
# Copy the empty category template to start
cp templates/empty-category.json ~/.openclaw/workspace/memory/experiences/your-category.json
# Edit the JSON and add your first experience

What's Included

• SKILL.md - Complete documentation
• templates/empty-category.json - Starter template for new categories
• templates/example.json - Real-world example from production usage
• examples/ - Full production-ready experience files:
  • examples/edit.json - Experience for file editing
  • examples/exec.json - Experience for shell command execution
  • examples/feishu.json - Experience for Feishu/Lark API
  • examples/message.json - Experience for message sending
  • examples/cron.json - Experience for cron job scheduling

Usage in OpenClaw Workflow

1. Before calling a tool:

read memory/experiences/{category}.json
apply the best practices and avoid the common mistakes

2. After failure:

analyze root cause
update the corresponding experience file
record the lesson learned
then retry

Benefits

• No repeated mistakes - Same mistake only pays tuition once
• Progressive improvement - System gets better over time
• Compact and searchable - JSON format for easy semantic search
• Low overhead - Small files, quick to load
• Open extension - Add new categories as needed

Changelog

1.0.2 (2026-03-18)

• Add examples/ directory with full production experience files
• Include 5 complete real-world experience JSON: edit, exec, feishu, message, cron
• Users can drop these directly into their memory/experiences/ to start

1.0.1 (2026-03-18)

• Add template directory with empty category template
• Add complete example JSON from production
• Improve installation documentation

1.0.0 (2026-03-18)

• Initial public release
• 25+ experience categories with real-world lessons from production usage
• Complete JSON schema
• Documentation

Author

jilanfang

License

MIT