# Skill Catalog

Wall-E ships with bundled skills that run on a schedule to keep your brain up to date.

## Bundled Skills

### google-calendar
**Schedule:** every 30m | **Execution:** script

Syncs macOS Calendar events (Google, iCloud, Outlook) into the brain via EventKit. Stores event title, attendees, location, notes, and calendar name. Deduplicates by event UID + start time.

**Config:**
- `days_back` (number, default: 1) — days of past events to include
- `days_ahead` (number, default: 14) — days of future events to include

---

### slack-sync
**Schedule:** every 15m | **Execution:** script

Incremental Slack message sync via MCP. Pulls new messages since the last checkpoint and stores them as memories with sender, channel, and direction metadata.

**Requires:** `SLACK_TOKEN`, `SLACK_OWNER_USER_ID`

---

### slack-backfill
**Schedule:** manual | **Execution:** script

Full Slack history backfill from 2022 to present. Paginates through all search results (up to 20 pages per month). Supports checkpoint/resume for interrupted runs.

**Usage:**
```bash
node scripts/slack-backfill.js              # full backfill
node scripts/slack-backfill.js incremental  # new messages only
node scripts/slack-backfill.js 2024-01      # single month
```

---

### email-sync
**Schedule:** every 30m | **Execution:** script

Syncs sent emails from macOS Mail via JXA (JavaScript for Automation). Captures subject, recipients, date, and body text. Deduplicates by message ID.

---

### email-digest
**Schedule:** daily at 7am | **Execution:** agent

AI-generated summary of recent email activity. Uses the LLM to synthesize patterns, key threads, and action items from email memories.

---

### morning-briefing
**Schedule:** daily at 7am | **Execution:** agent

Generates a comprehensive daily briefing by searching memories across all sources. Includes: today's meetings, pending action items, Slack mentions, and active threads.

---

### memory-search
**Schedule:** on-demand | **Execution:** script

Full-text search across all memories using SQLite FTS5. Available as a tool in Wall-E chat.

---

## Skill Management GUI

The Skills tab in the Wall-E dashboard provides a full management interface:

### Analytics Bar
A summary row at the top showing total skills (by source), enabled count, skills run in the last 24 hours, overall success rate, and a count of currently failing skills (clickable to filter).

### Search, Filter & Sort
- **Search** — real-time filter on name, description, and tags
- **Category pills** — derived from skill `tags[]` (e.g. sync, data, coding, communication)
- **Status filter** — All / Enabled / Disabled / Failing
- **Sort** — Name, Last Run, Success Rate, Run Count

### Skill Cards
Each skill is displayed as a card with:
- Left color stripe: green (healthy + enabled), amber (enabled + failing), gray (disabled)
- Name, version badge, source badge (bundled/user/workspace), execution type badge (agent/script)
- Tag pills, 2-line description, stats row (success rate bar, run count, last run, result dot)
- Run button, toggle switch, overflow menu (View Details, Edit, Export, Delete)

### Detail Panel
Click any card to open a right-side slide-over with five tabs:

| Tab | Contents |
|-----|----------|
| **Overview** | Full description, metadata grid (version, author, source, execution, trigger, path), tags, permissions, pre-flight requirements validation, statistics |
| **Config** | Auto-generated form from SKILL.md config schema — text inputs, number inputs, toggles, selects — with save button |
| **History** | Execution log table: timestamp, status, duration, memories created, error |
| **Source** | Read-only SKILL.md content, monospace formatted |
| **Logs** | Last execution's tool_calls and tool_results, plus error stack if applicable |

### Pre-Flight Validation
Skills with a `requires` field are validated before execution:
- `bins: [node, npx]` — checks binary availability via `which`
- `env: [SLACK_TOKEN]` — checks environment variables
- `mcp: [slack]` — checks MCP server configuration

The Overview tab shows a live validation result with actionable suggestions for any missing requirements.

---

## Creating Custom Skills

### From the UI

Click **"+ New Skill"** in the Skills tab toolbar. You can:

1. **Pick a template** — Data Fetcher, Script Runner, Periodic Checker, or Manual Action
2. **Fill in the form** — name, description, execution type, trigger, tags, instructions
3. **Toggle to Raw mode** — edit the full SKILL.md directly

Skills are saved to `~/.wall-e/skills/<name>/SKILL.md` and auto-registered in the database.

### From the Filesystem

Create a directory with a `SKILL.md` file:

```
~/.wall-e/skills/my-skill/
  SKILL.md
  run.js        # (optional, for script skills)
```

Wall-E auto-discovers skills from these directories (highest precedence first):
1. **Workspace** — `.wall-e/skills/` in the current project
2. **User** — `~/.wall-e/skills/`
3. **Bundled** — `wall-e/skills/_bundled/`
4. **Registry** — `~/.wall-e/registry-skills/`

### SKILL.md Format

```yaml
---
name: my-skill
description: What this skill does
version: 1.0.0
execution: script
entry: run.js
trigger:
  type: interval
  interval_ms: 3600000
tags: [custom, sync]
requires:
  bins: [node]
  env: [MY_API_KEY]
config:
  target:
    type: string
    description: "URL to fetch"
  verbose:
    type: boolean
    default: false
permissions:
  - brain:write
---
# My Skill

Additional documentation and agent instructions here.
```

### Execution Modes

**Script mode** (`execution: script`): Deterministic, no LLM cost. The daemon runs your `entry` file (Node.js script) and captures stdout/stderr. Use for data ingestion, sync, and automation.

**Agent mode** (`execution: agent`): LLM-driven. The markdown body of SKILL.md becomes the agent's prompt. Use for summarization, synthesis, and tasks requiring judgment.

### Config Schema

Define typed config fields in SKILL.md frontmatter:

| Type | UI Element |
|------|-----------|
| `string` | Text input |
| `string` + `enum` | Select dropdown |
| `boolean` | Toggle switch |
| `number` | Number input |

Users configure values in the Config tab of the detail panel. Saved values are stored per-skill in the database and merged with SKILL.md defaults at execution time.

### Script Pattern

```javascript
#!/usr/bin/env node
'use strict';

const brain = require('../../brain');
brain.initDb();

// Read config from environment
const config = JSON.parse(process.env.WALL_E_SKILL_CONFIG || '{}');

// Do work, store results
const mem = {
  source: 'my-source',
  source_id: 'unique-id',
  memory_type: 'my_type',
  subject: 'Title',
  content: 'Human-readable content',
  metadata: JSON.stringify({ raw: 'data' }),
  importance: 0.5,
  timestamp: new Date().toISOString(),
};
brain.insertMemory(mem);

// Output JSON summary
console.log(JSON.stringify({ inserted: 1 }));
brain.closeDb();
```

### Export / Import

- **Export**: From the overflow menu on any card, or from the detail panel. Downloads a JSON bundle containing the SKILL.md and all associated files.
- **Import**: Click "Import" in the toolbar, select a `.json` bundle file. The skill is created in `~/.wall-e/skills/` and auto-registered.

### Key Conventions

- **Deduplication**: Always use `source` + `source_id` for dedup. Check existing before inserting.
- **Exit codes**: 0 = success, 1 = failure, 2 = partial success (checkpoint saved)
- **Checkpoints**: Emit `CHECKPOINT:value` lines to stdout for resumable tasks
- **Config**: Passed via `WALL_E_SKILL_CONFIG` env var (JSON string)
- **Deletion**: User-created skills can be deleted from the UI (removes directory + DB entry). Bundled skills can only be disabled.
