@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/SKILL_GATEWAY_DESIGN.md

@@ -0,0 +1,702 @@
+# Nexus Skill Gateway Design
+
+> **Note**: State layout and credential storage are defined in
+> `STATE_ARCHITECTURE.md`. References to per-skill state and usage logs in this
+> design are canonical under `~/nexus/state/nexus/skills/{skill}/`.
+
+*Complete specification for the skill gateway CLI that solves the two hard problems.*
+
+---
+
+## Overview
+
+The skill gateway is a CLI interface that:
+1. **Gates all skill discovery** — Agent sees only what's available/configured
+2. **Wraps all skill execution** — Every invocation is logged automatically
+3. **Tracks usage patterns** — Build "neural pathways" of what works
+4. **Simplifies agent instructions** — Just "use `nexus skill run X`"
+
+This solves both hard problems:
+- **Problem 1 (Tracking State)**: Automatic via usage logging + execution gating
+- **Problem 2 (Injecting State)**: Agent queries CLI, gets current state
+
+---
+
+## Design Principles
+
+1. **CLI only** — No MCP servers, works everywhere including Cursor
+2. **Build on existing infrastructure** — Extend current `nexus skills` commands
+3. **Minimal SKILL.md changes** — New metadata goes in `~/nexus/state/`, not frontmatter
+4. **Option C verification** — Verify once on first run, trust until failure
+5. **Automatic logging** — Agent doesn't report, gateway captures everything
+
+---
+
+## Command Structure
+
+### Existing Commands (Keep As-Is)
+
+```bash
+nexus skills list [--ready|--locked|--json]  # Existing, enhance with status
+nexus skills refresh                          # Existing
+nexus skills cursor-rules                     # Existing
+nexus skills path                             # Existing
+```
+
+### New Commands
+
+```bash
+# Skill details (NEW)
+nexus skill show <name>              # Show prompt + metadata + setup guide
+nexus skill verify <name>            # Check if configured/working
+
+# Skill execution (NEW - THE GATEWAY)
+nexus skill run <name> [-- args]     # Run tool-based skill OR return prompt
+
+# Usage statistics (NEW)
+nexus skill stats [name]             # Usage statistics (all or per-skill)
+
+# State (NEW - convenience alias)
+nexus status                         # Overall capability state (alias for skills list --summary)
+```
+
+---
+
+## New Metadata Schema
+
+### Per-Skill State (`~/nexus/state/nexus/skills/{skill}/state.json`)
+
+This is separate from the skills manifest (`state/nexus/skills/manifest.json`). It tracks runtime state that changes:
+
+```typescript
+type SkillState = {
+  version: 1;
+  // Execution metadata
+  tool?: string;              // CLI binary name (e.g., "gog", "eve", "op")
+  verify?: string;            // Command to verify skill works (e.g., "gog gmail labels list")
+
+  // Runtime state (updated by gateway)
+  configured: boolean;        // Has verification passed?
+  configuredAt?: string;      // ISO timestamp of first successful verification
+  lastVerified?: string;      // ISO timestamp of last verification
+  lastUsed?: string;          // ISO timestamp of last execution
+  lastError?: string;         // Last error message if failed
+
+  // Stats (computed from usage log)
+  totalInvocations?: number;
+  successRate?: number;
+};
+```
+
+### Why Separate from SKILL.md?
+
+1. **SKILL.md stays clean** — Standard format, shareable, no nexus-specific cruft
+2. **State is mutable** — `configured`, `lastUsed`, etc. change frequently
+3. **Consistent layout** — One file per skill plus the manifest
+4. **Backward compatible** — Existing skills work without modification
+
+### Initial Population
+
+On first run or `nexus skills refresh`, populate per-skill state files by:
+1. Scanning all skills
+2. For skills with known tools, auto-populate `tool` field
+3. Set `configured: false` until verified
+
+We can hardcode a mapping for known skills initially:
+
+```typescript
+const KNOWN_SKILL_TOOLS: Record<string, { tool: string; verify: string }> = {
+  'gog': { tool: 'gog', verify: 'gog gmail labels list --account default' },
+  'eve': { tool: 'eve', verify: 'eve messages --limit 1' },
+  '1password': { tool: 'op', verify: 'op whoami' },
+  'tmux': { tool: 'tmux', verify: 'tmux -V' },
+  'peekaboo': { tool: 'peekaboo', verify: 'peekaboo --version' },
+  // ... etc
+};
+```
+
+Later, this can move to SKILL.md frontmatter or a separate config file per skill.
+
+---
+
+## Command Specifications
+
+### `nexus skill show <name>`
+
+**Purpose**: Display skill details, prompt, and setup instructions.
+
+**Implementation**:
+1. Load skill from manifest (existing `loadWorkspaceSkillEntries`)
+2. Load state from `state/nexus/skills/{skill}/state.json`
+3. Format and display
+
+**Output Format**:
+
+```
+═══════════════════════════════════════════════════════════════
+📧 GOG - Google Services Access
+═══════════════════════════════════════════════════════════════
+
+Status:     ✅ Configured (last verified: 2026-01-14)
+Tool:       gog
+Class:      OAuth/Complex (requires Google OAuth setup)
+
+Requirements:
+  • Binary: gog ✓
+  • OAuth: Google account connected ✓
+
+Usage Stats:
+  • Total invocations: 312
+  • Success rate: 98.7%
+  • Last used: 2 hours ago
+
+───────────────────────────────────────────────────────────────
+PROMPT
+───────────────────────────────────────────────────────────────
+
+[Full SKILL.md content here]
+
+───────────────────────────────────────────────────────────────
+SETUP (if not configured)
+───────────────────────────────────────────────────────────────
+
+To configure this skill:
+1. Install: go install github.com/nexus-xyz/gog@latest
+2. Authenticate: gog auth login
+3. Verify: nexus skill verify gog
+```
+
+**Flags**:
+- `--json` — Output as JSON
+- `--prompt-only` — Just the prompt content (for agent consumption)
+
+---
+
+### `nexus skill run <name> [-- args]`
+
+**Purpose**: The gateway. Execute a skill's tool or return its prompt.
+
+**Flow**:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ nexus skill run <name> [-- args]                                │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Load skill metadata                                         │
+│     - From manifest + per-skill state.json                       │
+│     - If skill not found → error with suggestions               │
+│                                                                 │
+│  2. Check if skill has a tool                                   │
+│     - If no tool → return prompt content, log as "prompt", exit │
+│                                                                 │
+│  3. Check if tool binary exists                                 │
+│     - If missing → show install instructions, exit 1            │
+│                                                                 │
+│  4. Check if configured (first-run verification)                │
+│     - If never verified → run verify command                    │
+│     - If verify fails → show setup instructions, exit 1         │
+│     - If verify succeeds → update state, continue               │
+│                                                                 │
+│  5. Execute tool with args                                      │
+│     - cmd = exec.Command(tool, args...)                         │
+│     - Capture stdout/stderr                                     │
+│     - Track duration                                            │
+│                                                                 │
+│  6. Log invocation                                              │
+│     - Append to per-skill usage.log                              │
+│     - Update per-skill state.json (lastUsed, etc.)               │
+│                                                                 │
+│  7. Return output                                               │
+│     - Print captured output to stdout                           │
+│     - Exit with tool's exit code                                │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Implementation (TypeScript)**:
+
+```typescript
+async function runSkill(skillName: string, args: string[]): Promise<void> {
+  const skill = await loadSkill(skillName);
+  if (!skill) {
+    console.error(`Skill '${skillName}' not found.`);
+    console.error(`Run 'nexus skills list' to see available skills.`);
+    process.exit(1);
+  }
+
+  const state = await loadSkillState(skillName);
+  
+  // Pure prompt skill
+  if (!state.tool) {
+    console.log(skill.prompt);
+    await logUsage({ skill: skillName, type: 'prompt' });
+    return;
+  }
+
+  // Check binary exists
+  if (!hasBinary(state.tool)) {
+    console.error(`Tool '${state.tool}' not found in PATH.`);
+    if (skill.install) {
+      console.error(`\nInstall with: ${skill.install}`);
+    }
+    process.exit(1);
+  }
+
+  // First-run verification (Option C)
+  if (!state.configured) {
+    console.error(`Verifying skill '${skillName}'...`);
+    const verified = await verifySkill(skillName, state.verify);
+    if (!verified.ok) {
+      console.error(`Skill '${skillName}' is not configured.`);
+      console.error(`Error: ${verified.error}`);
+      console.error(`\nSetup instructions:`);
+      console.error(skill.setupGuide || `Run 'nexus skill show ${skillName}' for details.`);
+      process.exit(1);
+    }
+    await updateSkillState(skillName, { configured: true, configuredAt: new Date().toISOString() });
+  }
+
+  // Execute
+  const start = Date.now();
+  const result = await exec(state.tool, args);
+  const duration = Date.now() - start;
+
+  // Log
+  await logUsage({
+    skill: skillName,
+    type: 'tool',
+    args,
+    exitCode: result.exitCode,
+    durationMs: duration,
+    error: result.exitCode !== 0 ? result.stderr : undefined,
+  });
+
+  // Update state
+  await updateSkillState(skillName, { 
+    lastUsed: new Date().toISOString(),
+    lastError: result.exitCode !== 0 ? result.stderr.slice(0, 200) : undefined,
+  });
+
+  // Output
+  process.stdout.write(result.stdout);
+  process.stderr.write(result.stderr);
+  process.exit(result.exitCode);
+}
+```
+
+**Flags**:
+- `--dry-run` — Show what would be executed without running
+- `--no-verify` — Skip verification check (for debugging)
+- `--json` — Output as JSON (including metadata)
+
+---
+
+### `nexus skill verify <name>`
+
+**Purpose**: Explicitly verify a skill works.
+
+**Flow**:
+1. Load skill state
+2. If no verify command → "Skill has no verification command"
+3. Run verify command
+4. Update state with result
+5. Report success/failure
+
+**Output**:
+```
+Verifying skill 'gog'...
+Running: gog gmail labels list --account default
+
+✅ Skill 'gog' verified successfully.
+   Configured at: 2026-01-14T10:30:00Z
+```
+
+or
+
+```
+Verifying skill 'brave-search'...
+Checking: BRAVE_API_KEY environment variable
+
+❌ Skill 'brave-search' verification failed.
+   Error: BRAVE_API_KEY not set
+
+   Setup instructions:
+   1. Get an API key from https://brave.com/search/api/
+   2. Set: export BRAVE_API_KEY=your-key
+   3. Or add to ~/.zshrc for persistence
+```
+
+---
+
+### `nexus skill stats [name]`
+
+**Purpose**: Show usage statistics.
+
+**Implementation**:
+1. Parse per-skill `usage.log`
+2. Aggregate by skill
+3. Calculate success rates, frequency, etc.
+4. Format output
+
+**Output (all skills)**:
+```
+═══════════════════════════════════════════════════════════════
+NEXUS SKILL USAGE STATISTICS
+═══════════════════════════════════════════════════════════════
+
+Total invocations: 847 (past 30 days)
+Overall success rate: 96.2%
+
+Most Used Skills:
+  #  Skill          Calls   Success   Avg Time   Last Used
+  1. gog            312     98.7%     1.2s       2 hours ago
+  2. eve            198     95.2%     0.8s       1 day ago
+  3. filesystem      89     100%      (prompt)   3 hours ago
+  4. 1password       67     99.1%     0.3s       5 hours ago
+  5. computer-use    52     100%      (prompt)   1 day ago
+
+Recent Failures (past 7 days):
+  • brave-search: "API key expired" (3 occurrences)
+  • discord: "bot not responding" (1 occurrence)
+
+Skill Categories:
+  User Data:    412 calls (gog, eve)
+  Credentials:   67 calls (1password)
+  Prompts:      141 calls (filesystem, computer-use)
+```
+
+**Output (single skill)**:
+```
+═══════════════════════════════════════════════════════════════
+GOG USAGE STATISTICS
+═══════════════════════════════════════════════════════════════
+
+Total invocations: 312
+Success rate: 98.7%
+Average duration: 1.2s
+
+Daily Usage (past 7 days):
+  Mon: ████████████ 45
+  Tue: ██████████ 38
+  Wed: ████████████████ 52
+  Thu: ██████████████ 48
+  Fri: ████████ 32
+  Sat: ████████████ 44
+  Sun: ██████████████ 53
+
+Most Common Commands:
+  1. gmail messages list (124 calls)
+  2. calendar events today (89 calls)
+  3. drive files list (56 calls)
+
+Recent Errors:
+  • 2026-01-13 14:32: "rate limit exceeded"
+  • 2026-01-10 09:15: "token expired" (resolved)
+```
+
+**Flags**:
+- `--json` — Output as JSON
+- `--days <n>` — Time window (default: 30)
+
+---
+
+## Usage Log Format
+
+**Location**: `~/nexus/state/nexus/skills/{skill}/usage.log`
+
+**Format**: JSON Lines (one JSON object per line, append-only)
+
+```json
+{"ts":"2026-01-14T10:00:00.000Z","skill":"gog","type":"tool","args":["gmail","messages","list","--limit","5"],"exit":0,"ms":1234}
+{"ts":"2026-01-14T10:01:00.000Z","skill":"eve","type":"tool","args":["messages"],"exit":1,"ms":50,"error":"not configured"}
+{"ts":"2026-01-14T10:02:00.000Z","skill":"filesystem","type":"prompt","ms":5}
+{"ts":"2026-01-14T10:05:00.000Z","skill":"gog","type":"tool","args":["calendar","events","today"],"exit":0,"ms":890}
+```
+
+**Schema**:
+```typescript
+type UsageLogEntry = {
+  ts: string;              // ISO timestamp
+  skill: string;           // Skill name
+  type: 'tool' | 'prompt'; // Execution type
+  args?: string[];         // Arguments (for tools)
+  exit?: number;           // Exit code (for tools)
+  ms: number;              // Duration in milliseconds
+  error?: string;          // Error message (truncated to 200 chars)
+};
+```
+
+**Log Rotation**: 
+- Keep last 10,000 entries (or 30 days, whichever is smaller)
+- Rotate on `nexus skills refresh` or when log exceeds 10MB
+
+---
+
+## Enhanced `nexus skills list`
+
+Update existing command to show configuration status:
+
+```bash
+$ nexus skills list
+
+═══════════════════════════════════════════════════════════════
+NEXUS SKILLS (47 total)
+═══════════════════════════════════════════════════════════════
+
+✅ READY (configured, working) — 12 skills
+   gog           Google services (gmail, calendar, drive)     [tool: gog]
+   eve           iMessage access (read tier)                  [tool: eve]
+   1password     Credential management                        [tool: op]
+   filesystem    File organization                            [prompt]
+   computer-use  Browser/desktop automation                   [prompt]
+   peekaboo      Screenshot capture                           [tool: peekaboo]
+   tmux          Terminal multiplexing                        [tool: tmux]
+   qmd           Markdown rendering                           [tool: qmd]
+   aix           AI conversations                             [tool: aix]
+   video-frames  Video frame extraction                       [tool: ffmpeg]
+   weather       Weather lookup                               [prompt]
+   camsnap       Camera capture                               [tool: camsnap]
+
+⚠️  NEEDS SETUP (requires configuration) — 8 skills
+   brave-search  Web search                     needs: BRAVE_API_KEY
+   summarize     Text summarization             needs: API key
+   discord       Agent communications           needs: bot token
+   telegram      Agent communications           needs: bot token
+   eve (send)    iMessage sending               blocked: Apple ID setup
+   nexus-cloud   Cloud sync                     needs: Cloudflare setup
+   gifgrep       GIF search (full)              needs: GIPHY_API_KEY
+   coding-agent  Autonomous coding              needs: API key + codex
+
+⏳ NOT INSTALLED (binary missing) — 3 skills
+   nano-pdf      PDF processing                 install: brew install nano-pdf
+   songsee       Music recognition              install: brew install songsee
+
+💤 DISABLED (explicitly disabled in config) — 1 skill
+   experimental  Experimental features          disabled in nexus.json
+
+Run 'nexus skill show <name>' for details on any skill.
+Run 'nexus skill run <name>' to use a skill.
+```
+
+**New Flags**:
+- `--ready` — Only show configured skills
+- `--locked` — Only show skills needing setup
+- `--summary` — One-line summary (for status command)
+
+---
+
+## Integration with Existing Infrastructure
+
+### Files We Modify
+
+1. **`src/cli/skills-cli.ts`**
+   - Add `skill show <name>` subcommand
+   - Add `skill run <name>` subcommand  
+   - Add `skill verify <name>` subcommand
+   - Add `skill stats` subcommand
+   - Enhance `skills list` with status indicators
+
+2. **`src/cli/program.ts`**
+   - Add `status` command (alias for `skills list --summary`)
+
+### Files We Create
+
+1. **`src/agents/skill-state.ts`**
+   - `loadSkillState(name)` / `updateSkillState(name, updates)`
+   - `getSkillTool(name)` / `getSkillVerify(name)`
+   - State file management
+
+2. **`src/agents/skill-usage.ts`**
+   - `logUsage(entry)` — Append to log
+   - `parseUsageLog(opts)` — Parse and filter log
+   - `aggregateStats(entries)` — Compute statistics
+
+3. **`src/agents/skill-runner.ts`**
+   - `runSkill(name, args)` — The gateway implementation
+   - `verifySkill(name)` — Run verification
+
+### Files We Read (No Modify)
+
+- `src/agents/skills.ts` — Use existing `hasBinary()`, `loadWorkspaceSkillEntries()`
+- `src/agents/skills-status.ts` — Use existing requirement checking
+- `src/commands/skills-manifest.ts` — Use existing manifest handling
+
+---
+
+## Agent Instructions (AGENTS.md)
+
+With the gateway in place, agent instructions become trivially simple:
+
+```markdown
+# Nexus Workspace
+
+## Skills
+
+All capabilities go through the nexus CLI:
+
+```bash
+# See what's available
+nexus skills list --ready
+
+# Get skill details
+nexus skill show <name>
+
+# Use a skill
+nexus skill run <name> [-- arguments]
+```
+
+If a skill isn't configured, the CLI will tell you what's needed.
+
+## Identity
+
+- Your identity: Read `state/agents/{agent}/identity/IDENTITY.md`
+- User profile: Read `state/user/identity/PROFILE.md`
+
+## Memories
+
+Store daily memory in `home/memory/` and curated memory in `state/agents/{agent}/identity/MEMORY.md`
+```
+
+That's the entire protocol. Everything else flows through `nexus skill run`.
+
+---
+
+## Cursor Integration
+
+### .cursor/rules
+
+The existing `nexus skills cursor-rules` command generates `.cursor/rules`. Update it to include:
+
+```markdown
+# Nexus Skills
+
+When you need to use a Nexus skill, use the CLI:
+
+```bash
+# List available skills
+nexus skills list --ready
+
+# Get skill details  
+nexus skill show <skill-name>
+
+# Run a skill
+nexus skill run <skill-name> [-- args]
+```
+
+The CLI will handle verification and logging automatically.
+
+## Configured Skills
+
+[Auto-generated list of configured skills with brief descriptions]
+```
+
+### Cursor Skills Directory
+
+The existing infrastructure already symlinks skills to where Cursor can find them. No changes needed.
+
+---
+
+## Implementation Order
+
+### Phase 1: State Infrastructure (Day 1)
+- [ ] Create `src/agents/skill-state.ts`
+- [ ] per-skill `state.json` schema and I/O
+  - [ ] `KNOWN_SKILL_TOOLS` mapping for initial population
+  - [ ] Auto-populate on first read / `nexus skills refresh`
+
+### Phase 2: Usage Logging (Day 1)
+- [ ] Create `src/agents/skill-usage.ts`
+  - [ ] `logUsage()` function
+  - [ ] `parseUsageLog()` function
+  - [ ] Log rotation logic
+
+### Phase 3: Core Commands (Day 2)
+- [ ] `nexus skill show <name>` in `skills-cli.ts`
+- [ ] `nexus skill verify <name>` in `skills-cli.ts`
+- [ ] `nexus skill run <name>` in `skills-cli.ts`
+  - [ ] Pure prompt handling
+  - [ ] Tool execution with capture
+  - [ ] First-run verification
+  - [ ] Logging integration
+
+### Phase 4: Stats & Polish (Day 3)
+- [ ] `nexus skill stats` command
+- [ ] Enhance `nexus skills list` with status indicators
+- [ ] Add `nexus status` alias
+- [ ] Update cursor-rules generation
+
+### Phase 5: Documentation & Testing (Day 4)
+- [ ] Update AGENTS.md template
+- [ ] Test with real skills (gog, eve, filesystem)
+- [ ] Verify Cursor integration
+
+---
+
+## Known Skill Tools (Initial Mapping)
+
+| Skill | Tool Binary | Verify Command |
+|-------|-------------|----------------|
+| gog | `gog` | `gog gmail labels list --account default` |
+| eve | `eve` | `eve messages --limit 1` |
+| 1password | `op` | `op whoami` |
+| tmux | `tmux` | `tmux -V` |
+| peekaboo | `peekaboo` | `peekaboo --version` |
+| qmd | `qmd` | `qmd status` |
+| aix | `aix` | `aix --version` |
+| video-frames | `ffmpeg` | `ffmpeg -version` |
+| camsnap | `camsnap` | `camsnap --help` |
+| brave-search | (env check) | `test -n "$BRAVE_API_KEY"` |
+| summarize | (env check) | `test -n "$SUMMARIZE_API_KEY"` |
+| nano-pdf | `nano-pdf` | `nano-pdf --version` |
+| filesystem | (none) | — |
+| computer-use | (none) | — |
+| weather | (none) | — |
+
+---
+
+## Open Questions
+
+### 1. Should `skill run` capture stderr separately?
+
+**Current design**: Combined output (stdout + stderr to stdout)
+**Alternative**: Keep them separate, let agent see both
+
+**Recommendation**: Combined for simplicity. Agent can parse if needed.
+
+### 2. How do we handle long-running skills?
+
+**Current design**: Block until complete
+**Alternative**: Background execution with status checking
+
+**Recommendation**: Block for now. Add `--background` flag later if needed.
+
+### 3. Should we truncate args in logs for privacy?
+
+**Current design**: Log full args
+**Alternative**: Truncate or hash sensitive-looking args
+
+**Recommendation**: Log full args. User controls their own logs. Add `--no-log` flag for sensitive operations if needed.
+
+### 4. How do we handle skill aliases?
+
+Example: `gog` is also known as `google`, `gmail`, etc.
+
+**Recommendation**: Defer. Use canonical names only for now.
+
+---
+
+## Success Criteria
+
+The gateway is successful when:
+
+1. ✅ `nexus skill run gog -- gmail messages list` executes and logs
+2. ✅ `nexus skill run filesystem` returns the prompt
+3. ✅ First-run verification works for unconfigured skills
+4. ✅ `nexus skill stats` shows meaningful usage data
+5. ✅ Agent can use skills with only "nexus skill run" instructions
+6. ✅ Cursor integration works via cursor-rules
+
+---
+
+*This document is the authoritative specification. Implementation should be mechanical from here.*