skill-cortex

# Skill Cortex

Triggers when installed Skills cannot complete the current task. If you can handle it yourself, just do it — do not trigger this flow.

Cortex data file: `~/.openclaw/skill-cortex/cortex.json` (schema in `docs/DESIGN.md`).

---

## Phase 1: Perception

1. Read `cortex.json` (if missing or corrupt, skip to step 3).
2. **Semantically match** the user's task description against `sensory.patterns` signals (no exact match required — use your own judgment on intent alignment). On hit, look up the corresponding region in `motor`, sort candidates by effective weight (`effective_weight = weight * max(0.3, 1 - days_since_last_used / 180)`), filter out blacklisted and effective_weight < 0.3 entries, then proceed to Phase 2.
3. On miss, search ClawHub: `clawhub search "<3-5 English keywords>"`. Read summaries only, pick up to **3** candidates. If fewer than 2 relevant results, supplement with a GitHub search (mark as unreviewed source).

---

## Phase 2: Validation & Authorization

### Reflex Fast Path

The top candidate may enter reflex mode when ALL of the following hold:
- `reflex: true` AND effective_weight >= 0.90 AND consecutive successes >= 5
- **No write side effects** (side_effects contains no `write:`/`delete:`/`shell:` prefix)
- **Version unchanged** (slug + version match the stored record)

Reflex mode **skips only the execution plan confirmation**. Installation still requires user notification:

```
⚡ Skill Cortex reflex: todoist-cli v1.2.0 (96% success rate)
   Task: query today's todos (read-only) | Will install and execute. Say cancel to abort.
```

Version change automatically downgrades to standard mode.

### Standard Mode

Present candidates to the user (name, description, stars, downloads, source, security scan status, history). **Wait for explicit approval before installing.**

If `prefrontal.lessons` contain experiences matching the current region, retain them for use in Phase 3.

---

## Phase 3: Execution

### 3.1 Install

```bash
clawhu...

# Skill Cortex

**A self-evolving capability manager for [OpenClaw](https://github.com/openclaw) agents.**

Skill Cortex gives your agent the ability to autonomously find, install, use, and discard Skills from [ClawHub](https://clawhub.ai) — and learn from every interaction. The more you use it, the faster it gets.

## The Problem

OpenClaw loads every installed Skill into the system prompt. More Skills = more tokens burned per conversation, even when most are irrelevant to the current task. But uninstalling them means losing capability.

## The Solution

Skill Cortex introduces a **cached Skill layer** — a dynamic, temporary workspace that sits on top of your permanent Skills:

```
┌─────────────────────────────────────────────┐
│  User Task                                  │
├─────────────────────────────────────────────┤
│  Skill Cortex (this Skill)                  │
│  ┌────────────────────────────────────────┐ │
│  │ Sensory   → recognize task type        │ │
│  │ Motor     → route to best Skill        │ │
│  │ Prefrontal→ apply past experience      │ │
│  └────────────────────────────────────────┘ │
├─────────────────────────────────────────────┤
│  Cached Skills  (on-demand, auto-cleanup)   │
├─────────────────────────────────────────────┤
│  Long-term Skills  (user-installed, native) │
└─────────────────────────────────────────────┘
```

## How It Works

**Phase 1 — Perception:** Check local memory first. If the cortex has seen this type of task before, it routes directly to the best known Skill. Otherwise, search ClawHub.

**Phase 2 — Validation:** Present candidates to the user with safety info (stars, downloads, VirusTotal scan, source). Nothing installs without explicit approval.

**Phase 3 — Execution:** Install the Skill, generate an execution plan with side-effect warnings, execute the task. On failure, auto-recover or switch to the next candidate (max 2 switches).

**Phase 4 — Learning:** Update the cortex memory. Successful Skills gain weight; fail...