create-walle 0.9.3 → 0.9.4

package/template/wall-e/docs/specs/SKILL-FORMAT.md

@@ -1,326 +0,0 @@
-# WALL-E Skill Format Specification
-
-**Version:** 1.0.0
-**Date:** 2026-03-31
-**Status:** Draft
-
-## Overview
-
-A WALL-E skill is a **reusable capability** that the agent can invoke to accomplish work. Skills sit between raw tools (Slack MCP, file I/O, shell) and tasks (scheduled/triggered jobs).
-
-```
-┌─────────────────────────────────────┐
-│          TASKS (scheduling)         │  "Run slack-sync every 15m"
-│  When to run, checkpoints, status   │
-├─────────────────────────────────────┤
-│          SKILLS (capabilities)      │  "How to sync Slack messages"
-│  Reusable, composable, shareable    │
-├─────────────────────────────────────┤
-│          TOOLS (primitives)         │  Slack MCP, brain DB, shell
-│  Raw APIs, MCP servers              │
-└─────────────────────────────────────┘
-```
-
-## Skill Directory Structure
-
-Each skill is a directory containing a `SKILL.md` file and optional supporting files:
-
-```
-skills/
-  slack-sync/
-    SKILL.md              # Required: metadata + instructions
-    run.js                # Optional: script entry point
-    lib/                  # Optional: supporting code
-    README.md             # Optional: human docs
-  morning-briefing/
-    SKILL.md              # Agent-based skill (no script)
-  my-custom-skill/
-    SKILL.md
-    run.sh                # Shell scripts work too
-```
-
-## SKILL.md Format
-
-A SKILL.md file has two parts: **YAML frontmatter** (metadata) and **Markdown body** (instructions).
-
-### Minimal Example
-
-```markdown
----
-name: hello-world
-description: A simple test skill that greets the user
-version: 1.0.0
-execution: agent
----
-# Hello World
-
-When invoked, respond with a friendly greeting that includes the owner's name.
-```
-
-### Full Example
-
-```markdown
----
-name: slack-sync
-description: >
-  Pull latest Slack messages from active conversations.
-  Discovers recently active channels, fetches new messages,
-  and stores them in WALL-E's brain for search and context.
-version: 1.2.0
-author: wall-e
-
-# Execution mode: "script" (deterministic) or "agent" (LLM-driven)
-execution: script
-entry: run.js
-args: ["--sync"]
-
-# What this skill needs to run
-requires:
-  env: []                          # Environment variables (checked at load time)
-  tools: [slack-mcp]               # MCP servers or tool modules
-  skills: []                       # Other skills this depends on
-
-# Default trigger for tasks that use this skill
-trigger:
-  type: interval                   # interval | cron | manual | event
-  schedule: "every 15m"            # Human-readable schedule
-
-# Skill configuration schema (validated at runtime)
-config:
-  mode:
-    type: string
-    enum: [incremental, full]
-    default: incremental
-    description: "incremental = only new messages, full = complete backfill"
-  max_channels:
-    type: number
-    default: 50
-    description: "Maximum channels to check per run"
-
-# Tags for discovery
-tags: [slack, messaging, sync, ingestion]
-
-# Permissions this skill requires (shown to user before install)
-permissions:
-  - slack:read          # Read Slack messages
-  - brain:write         # Write memories to brain DB
-  - network:outbound    # Make HTTP requests
----
-
-# Slack Conversation Sync
-
-## What This Skill Does
-
-Incrementally syncs Slack messages from your most active conversations
-into WALL-E's brain. Only checks recently active channels (last 7 days)
-to minimize API calls and run time.
-
-## How It Works
-
-1. Search Slack for YOUR recent messages to discover active channels
-2. Query brain DB for channels with recent activity
-3. For each active channel, fetch messages since last sync
-4. Deduplicate and store new messages as memories
-5. Emit checkpoint after each channel for resume support
-
-## Configuration
-
-- `mode: incremental` — Only pulls channels with activity in the last 7 days (~35 channels, ~1 min)
-- `mode: full` — Pulls ALL known channels (~800 channels, ~15 min)
-
-## Output
-
-Returns: `{ new_messages, skipped, channels_done, total_after }`
-```
-
-## Frontmatter Fields
-
-### Required
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | string | Unique skill identifier (kebab-case, e.g., `slack-sync`) |
-| `description` | string | What this skill does. **This is the primary field used for skill discovery.** Write it like search keywords. |
-| `version` | string | Semver version |
-| `execution` | string | `"script"` or `"agent"` |
-
-### Optional
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `author` | string | — | Skill author |
-| `entry` | string | `run.js` | Entry point file (for script execution) |
-| `args` | string[] | `[]` | Default arguments passed to entry point |
-| `requires.env` | string[] | `[]` | Required environment variables |
-| `requires.tools` | string[] | `[]` | Required MCP servers or tool modules |
-| `requires.skills` | string[] | `[]` | Other skills this depends on |
-| `trigger.type` | string | `manual` | Default trigger: `interval`, `cron`, `manual`, `event` |
-| `trigger.schedule` | string | — | Default schedule (e.g., `"every 15m"`, `"daily at 7am"`) |
-| `config` | object | `{}` | Configuration schema (JSON Schema subset) |
-| `tags` | string[] | `[]` | Discovery tags |
-| `permissions` | string[] | `[]` | Required permissions (shown before install) |
-
-## Execution Modes
-
-### Script Mode (`execution: script`)
-
-Deterministic execution. The skill runs a script file (Node.js, Python, shell) as a child process. No LLM tokens consumed. Fast and predictable.
-
-```yaml
-execution: script
-entry: run.js          # Relative to skill directory
-args: ["--sync"]       # Default CLI arguments
-```
-
-The script receives configuration via environment variables:
-- `WALL_E_SKILL_CONFIG` — JSON string of the config object
-- `WALL_E_DATA_DIR` — Path to WALL-E's data directory
-- `WALL_E_SKILL_DIR` — Path to this skill's directory
-
-Script exit codes:
-- `0` — Success
-- `1` — Failure (stderr captured as error)
-- `2` — Partial success (some work done, checkpoint saved)
-
-### Agent Mode (`execution: agent`)
-
-LLM-driven execution. WALL-E reads the SKILL.md instructions and uses available tools to accomplish the task. Flexible but costs tokens.
-
-```yaml
-execution: agent
-```
-
-The Markdown body below the frontmatter becomes the agent's instructions. The agent can use any available tools (MCP servers, brain DB, shell) to follow the instructions.
-
-Agent skills are ideal for:
-- Tasks requiring judgment (summarization, analysis)
-- Multi-step workflows that may vary each run
-- Skills that compose other skills
-- Natural language output (briefings, reports)
-
-## Skill Discovery
-
-When the agent needs to find relevant skills (e.g., user asks "sync my Slack"), it:
-
-1. Loads all installed skill metadata (name, description, tags)
-2. Matches against the user's request using description + tags
-3. For agent-mode skills: reads the full SKILL.md instructions
-4. For script-mode skills: executes the entry point
-
-The `description` field is critical for discovery. Write it with:
-- Action verbs: "Pull", "Sync", "Search", "Analyze"
-- Domain keywords: "Slack", "messages", "channels"
-- Use case phrases: "keep conversation context fresh"
-
-## Skill Locations & Precedence
-
-Skills are loaded from multiple locations. Higher precedence wins on name conflicts:
-
-1. **Workspace skills** (highest): `<project>/.wall-e/skills/`
-2. **User skills**: `~/.wall-e/skills/`
-3. **Bundled skills**: `wall-e/skills/_bundled/`
-4. **Registry skills** (lowest): `~/.wall-e/registry-skills/`
-
-## Bundled Skills
-
-WALL-E ships with these default skills:
-
-| Skill | Execution | Description |
-|-------|-----------|-------------|
-| `slack-sync` | script | Incremental Slack message sync |
-| `slack-backfill` | script | Full Slack history backfill |
-| `slack-search` | agent | Search Slack messages with context |
-| `morning-briefing` | agent | Daily meeting prep with calendar + Slack context |
-| `team-pulse` | agent | Monitor team messages for urgent items |
-| `memory-search` | agent | Search and summarize memories |
-
-## Skill ↔ Task Relationship
-
-Tasks reference skills by name. A task defines WHEN to run; the skill defines HOW.
-
-```
-Task: "Conversation Sync"
-  type: recurring
-  schedule: "every 15m"
-  skill: "slack-sync"                    # ← references the skill
-  skill_config: { mode: "incremental" }  # ← overrides skill defaults
-```
-
-A task can also chain multiple skills:
-```
-Task: "Morning Briefing"
-  type: recurring
-  schedule: "daily at 7am"
-  skill: "morning-briefing"     # Agent skill that internally uses:
-                                #   - slack-search (find recent context)
-                                #   - memory-search (find related memories)
-                                #   - calendar integration
-```
-
-## Configuration
-
-Skills define a config schema in frontmatter. Tasks can override defaults:
-
-```yaml
-# In SKILL.md
-config:
-  mode:
-    type: string
-    enum: [incremental, full]
-    default: incremental
-```
-
-```json
-// In task definition
-{
-  "skill": "slack-sync",
-  "skill_config": { "mode": "full" }
-}
-```
-
-## Skill Development
-
-### Creating a new skill
-
-```bash
-wall-e skill create my-skill          # Scaffold a new skill directory
-wall-e skill test my-skill            # Run the skill locally
-wall-e skill validate my-skill        # Check SKILL.md format
-```
-
-### Publishing
-
-```bash
-wall-e skill publish my-skill         # Publish to registry
-```
-
-### Installing third-party skills
-
-```bash
-wall-e skill install <name>           # From registry
-wall-e skill install <git-url>        # From Git repo
-wall-e skill list                     # Show installed skills
-wall-e skill update --all             # Update all skills
-```
-
-## Security Model
-
-1. **Bundled skills** — Trusted, shipped with WALL-E
-2. **User skills** — Created by the user, trusted by default
-3. **Registry skills** — Third-party, require explicit permission grant
-   - Permissions declared in `permissions` field
-   - Shown to user before installation
-   - Sandboxed: no access beyond declared permissions
-
-## Migration from Current System
-
-### Current → New
-
-| Current | New |
-|---------|-----|
-| `scripts/slack-backfill.js` | `skills/_bundled/slack-backfill/run.js` + `SKILL.md` |
-| `scripts/slack-channel-history.js` | `skills/_bundled/slack-sync/run.js` + `SKILL.md` |
-| `skills/slack-pull-live.js` | `skills/_bundled/slack-sync/incremental.js` |
-| Task with `execution: script` | Task with `skill: "slack-sync"` |
-| Task with `execution: chat` | Task with `skill: "morning-briefing"` |
-| `skills` DB table | Filesystem-based skills + DB for execution history |