@intent-systems/nexus 2026.1.5-4 → 2026.1.5-8

package/skills/guides/onboarding/docs/canonical/04_SKILL_SPECIFICATION.md

@@ -0,0 +1,393 @@
+# Skill Specification
+
+> How to create skills for Nexus.
+
+---
+
+## What is a Skill?
+
+A skill is a folder containing a `SKILL.md` file that teaches an agent how to do something. Nexus skills extend the [Agent Skills Specification](https://agentskills.io/specification) with additional metadata.
+
+**Key insight:** Skills are documentation. When an agent "uses" a skill via `nexus skill use <name>`, they receive the SKILL.md content. Nexus does not wrap tool execution.
+
+Skills are not used for session bootstrap. Bootstrap is handled by Cursor hooks,
+`AGENTS.md`, and `.cursor/rules` (see `07_AGENT_BINDINGS.md`).
+
+---
+
+## Directory Structure
+
+```
+skill-name/
+├── SKILL.md          # Required: frontmatter + instructions
+├── scripts/          # Optional: executable code
+├── references/       # Optional: additional docs
+└── assets/           # Optional: templates, images
+```
+
+Skills live in one of three folders based on type:
+
+| Type | Location | Purpose |
+|------|----------|---------|
+| Tool | `~/nexus/skills/tools/{name}/` | Binary/CLI usage guide |
+| Connector | `~/nexus/skills/connectors/{name}/` | Auth/credential setup |
+| Guide | `~/nexus/skills/guides/{name}/` | Pure instructions |
+
+---
+
+## SKILL.md Format
+
+### Frontmatter (Required)
+
+```yaml
+---
+name: skill-name
+description: What this skill does and when to use it.
+metadata:
+  nexus:
+    type: tool
+    emoji: 📧
+    provides: [email-read, email-send, calendar]
+    requires:
+      credentials: [google-oauth]
+      bins: [gog]
+    os: [darwin, linux]
+    install:
+      - id: brew
+        kind: brew
+        formula: steipete/tap/gogcli
+---
+```
+
+### Standard Fields (Agent Skills Spec)
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique identifier (lowercase, kebab-case) |
+| `description` | Yes | What the skill does and when to use it |
+| `license` | No | License name or file reference |
+| `metadata` | No | Extension point for additional data |
+
+### Nexus Extension Fields
+
+All Nexus-specific fields go under `metadata.nexus`:
+
+```yaml
+metadata:
+  nexus:
+    type: tool              # Required: tool, connector, or guide
+    emoji: 📧               # Optional: visual identifier
+    provides: [...]         # Optional: capabilities this enables
+    requires:               # Optional: dependencies
+      connectors: [...]     # Required connectors
+      bins: [...]           # Required binaries (all must exist)
+      anyBins: [...]        # Alternative binaries (any one works)
+      env: [...]            # Required environment variables
+    os: [darwin, linux]     # Optional: platform restrictions
+    install: [...]          # Optional: installation instructions
+```
+
+---
+
+## Skill Types
+
+### Tool
+
+A tool skill documents how to install and use a binary/CLI.
+
+**Location:** `skills/tools/{name}/SKILL.md`
+
+**Example:** `skills/tools/gog/SKILL.md`
+
+```yaml
+---
+name: gog
+description: Google Workspace CLI for Gmail, Calendar, Drive, Contacts.
+metadata:
+  nexus:
+    type: tool
+    emoji: 📧
+    provides: [email-read, email-send, calendar, cloud-storage, contacts]
+    requires:
+      credentials: [google-oauth]
+      bins: [gog]
+    os: [darwin, linux]
+    install:
+      - id: brew
+        kind: brew
+        formula: steipete/tap/gogcli
+        bins: [gog]
+---
+
+# gog
+
+Google Workspace CLI. Requires OAuth setup via the google-oauth connector.
+
+## Installation
+
+```bash
+brew install steipete/tap/gogcli
+```
+
+## Usage
+
+```bash
+# Search emails
+gog gmail search "is:unread" --max 10
+
+# List calendar events
+gog calendar events --json
+
+# List drive files
+gog drive files list
+```
+
+## Setup
+
+Before using, set up authentication:
+1. Use the `google-oauth` connector skill
+2. Run `gog auth add your@email.com`
+```
+
+### Connector
+
+A connector skill documents how to set up authentication for a service.
+
+**Location:** `skills/connectors/{name}/SKILL.md`
+
+**Example:** `connectors/anthropic/SKILL.md`
+
+```yaml
+---
+name: anthropic
+description: Anthropic API credentials for Claude models.
+metadata:
+  nexus:
+    type: connector
+    emoji: 🧠
+    provides: [llm-anthropic]
+    requires:
+      env: [ANTHROPIC_API_KEY]
+---
+
+# Anthropic Connector
+
+API key setup for Claude models.
+
+## Get API Key
+
+1. Go to https://console.anthropic.com
+2. Create an account or sign in
+3. Navigate to API Keys
+4. Create a new key
+
+## Store Credential
+
+Using Keychain (macOS):
+```bash
+nexus credential add \
+  --service anthropic \
+  --account your@email.com \
+  --type api-key \
+  --storage keychain
+```
+
+Using 1Password:
+```bash
+op item create --category="API Credential" \
+  --title="Anthropic API Key" \
+  --vault="Nexus" \
+  api_key="sk-ant-xxxxx"
+```
+
+## Verify
+
+```bash
+nexus credential verify anthropic
+```
+```
+
+### Guide
+
+A guide skill provides pure instructions using other tools/capabilities.
+
+**Location:** `skills/guides/{name}/SKILL.md`
+
+**Example:** `guides/filesystem/SKILL.md`
+
+```yaml
+---
+name: filesystem
+description: Scan, analyze, and organize files. Use for cleanup tasks.
+metadata:
+  nexus:
+    type: guide
+    emoji: 📁
+    provides: [file-organization]
+    os: [darwin, linux]
+---
+
+# Filesystem Organization
+
+Analyze and organize files with safety-first principles.
+
+## Safety Rules
+
+1. **Never delete without explicit approval**
+2. **Dry run first** - show what would change
+3. **Use trash, not rm** - recoverable beats gone
+
+## Common Tasks
+
+### Analyze Downloads
+```bash
+ls -la ~/Downloads | wc -l
+find ~/Downloads -mtime +180 -type f | wc -l  # Older than 6 months
+```
+
+### Find Large Files
+```bash
+find ~ -type f -size +100M 2>/dev/null
+```
+
+### Organize by Type
+```bash
+# Create structure
+mkdir -p ~/organized/{documents,images,archives}
+
+# Move files (ask user first!)
+mv ~/Downloads/*.pdf ~/organized/documents/
+mv ~/Downloads/*.{jpg,png} ~/organized/images/
+```
+```
+
+---
+
+## Provides and Requires
+
+### `provides`
+
+List of capabilities this skill enables:
+
+```yaml
+provides: [email-read, email-send, calendar]
+```
+
+Capabilities are abstract. See the capability taxonomy for the full list.
+
+### `requires`
+
+Dependencies needed for the skill to work. Tool skills typically require
+connector skills (represented as `credentials`), and connector skills require
+credentials/env/config to be present.
+
+```yaml
+requires:
+  credentials: [google-oauth]   # Required connector skills
+  bins: [gog]                   # All must be in PATH
+  anyBins: [peekaboo, interpreter]  # Any one works
+  env: [BRAVE_API_KEY]          # Required env vars
+```
+
+---
+
+## Installation Spec
+
+For tools, provide installation instructions:
+
+```yaml
+install:
+  - id: brew
+    kind: brew
+    formula: steipete/tap/gogcli
+    bins: [gog]
+    label: "Install via Homebrew"
+  
+  - id: go
+    kind: go
+    module: github.com/steipete/gogcli
+    bins: [gog]
+    label: "Install via Go"
+```
+
+**Supported kinds:**
+
+| Kind | Fields | Description |
+|------|--------|-------------|
+| `brew` | `formula`, `bins` | Homebrew package |
+| `go` | `module`, `bins` | Go install |
+| `node` | `package`, `bins` | Node package |
+| `uv` | `package`, `bins` | Python (uv) package |
+
+---
+
+## Scripts Directory
+
+Skills can include scripts for complex operations:
+
+```
+skill-name/
+├── SKILL.md
+└── scripts/
+    ├── search.mjs      # Node script
+    ├── analyze.py      # Python script
+    └── setup.sh        # Shell script
+```
+
+Reference in the skill:
+
+```markdown
+## Advanced Search
+
+Run the search script:
+```bash
+node {skill_dir}/scripts/search.mjs "query"
+```
+```
+
+---
+
+## References Directory
+
+Additional documentation that agents can read when needed:
+
+```
+skill-name/
+├── SKILL.md
+└── references/
+    ├── api-docs.md
+    ├── examples.md
+    └── troubleshooting.md
+```
+
+Keep the main SKILL.md focused. Move detailed content to references.
+
+---
+
+## Best Practices
+
+1. **Description matters** - Include keywords that help agents identify when to use the skill
+
+2. **Show, don't tell** - Include concrete command examples
+
+3. **Progressive disclosure** - Main content in SKILL.md, details in references/
+
+4. **Safety first** - Include guardrails for destructive operations
+
+5. **Test the flow** - Use the skill yourself before publishing
+
+---
+
+## Validation
+
+Check your skill follows the spec:
+
+```bash
+nexus skill info your-skill-name
+```
+
+This verifies:
+- SKILL.md exists and has valid frontmatter
+- Required fields present
+- Type is valid
+- Dependencies are specified correctly

package/skills/guides/onboarding/docs/canonical/05_CAPABILITY_TAXONOMY.md

@@ -0,0 +1,298 @@
+# Capability Taxonomy
+
+> The onboarding journey from zero to full power.
+
+---
+
+## What are Capabilities?
+
+Capabilities are abstract goals: "Can the agent read email?" not "Is gog installed?"
+
+```
+Capability (abstract)  →  Provider (concrete)
+     email-read        →  gog + google-oauth
+     messaging-read    →  eve, imsg, wacli
+     chat-send         →  discord, slack
+```
+
+Multiple providers can satisfy the same capability. This enables:
+- Portability (swap Gmail for Outlook)
+- Choice (use whatever tools you prefer)
+- Graceful degradation (some capability is better than none)
+
+---
+
+## The Onboarding Journey
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         CORE ONBOARDING (Required)                          │
+│                                                                             │
+│  1. ACCESS PLANE ──► 2. NEXUS INSTALL ──► 3. IDENTITY ──► 4. FIRST WOW     │
+│                                                                             │
+│  Immediately usable: filesystem, computer-use, weather, tmux               │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                        ════ DEPTH TRACK ════
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    5. CREDENTIAL MANAGER (Recommended)                      │
+│                    1Password, Bitwarden, or Keychain                        │
+│                                                                             │
+│  Multiplier: Makes all future setup easier and more secure                 │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                        ════ BREADTH TRACK ════
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       CAPABILITY EXPANSION (Parallel)                       │
+│                                                                             │
+│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐         │
+│  │ 6. USER COMMS   │    │ 7. USER DATA    │    │ 8. ENABLE LLM   │         │
+│  │ email, messages │    │ calendar, notes │    │ API keys        │         │
+│  └─────────────────┘    └─────────────────┘    └─────────────────┘         │
+│                                                                             │
+│  User chooses their own path — all same level                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                   (Enable LLM unlocks next level)
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    AGENT INDEPENDENCE (Requires LLM)                        │
+│                                                                             │
+│  ┌─────────────────────────┐    ┌─────────────────────────┐                │
+│  │ 9. AGENT COMMUNICATIONS │    │ 10. AUTOMATION          │                │
+│  │ Discord, Telegram       │    │ cron, reminders         │                │
+│  └─────────────────────────┘    └─────────────────────────┘                │
+│                                                                             │
+│  Agent can reach you outside IDE, work while you sleep                     │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+Note: During the Identity step, the Cursor sessionStart hook injects identity
+and memory into agent context. See `07_AGENT_BINDINGS.md`.
+
+---
+
+## Capability Categories
+
+### 🗣️ Communication
+
+| Capability | Description | Providers |
+|------------|-------------|-----------|
+| `email-read` | Read emails | gog + google-oauth |
+| `email-send` | Send emails | gog + google-oauth |
+| `messaging-read` | Read SMS/iMessage/WhatsApp | imsg, eve, wacli |
+| `messaging-send` | Send messages | imsg, wacli |
+| `chat-read` | Read Discord/Slack | discord, slack |
+| `chat-send` | Send to Discord/Slack | discord, slack |
+| `contacts` | Address book access | gog + google-oauth |
+
+### 📱 Social & News
+
+| Capability | Description | Providers |
+|------------|-------------|-----------|
+| `social-x` | X/Twitter feed & posting | bird + twitter |
+| `rss` | RSS feed monitoring | blogwatcher |
+| `news` | News search | brave-search |
+
+### 🔮 Insights
+
+| Capability | Description | Providers |
+|------------|-------------|-----------|
+| `relationship-insights` | Communication patterns | eve, comms |
+| `session-insights` | AI conversation analysis | aix |
+
+### 📋 Productivity
+
+| Capability | Description | Providers |
+|------------|-------------|-----------|
+| `calendar` | Events, scheduling | gog + google-oauth |
+| `tasks` | Todo management | things-mac, apple-reminders |
+| `notes` | Note-taking | apple-notes, obsidian, notion |
+| `reminders` | Time-based notifications | apple-reminders, gog |
+
+### 💾 Data Access
+
+| Capability | Description | Providers |
+|------------|-------------|-----------|
+| `cloud-storage` | Google Drive, Dropbox | gog + google-oauth |
+| `local-files` | Filesystem access | filesystem guide |
+
+### 🤖 Automation
+
+| Capability | Description | Providers |
+|------------|-------------|-----------|
+| `scheduling` | Cron/scheduled tasks | nexus cron + LLM |
+| `gui-automation` | Screen/mouse control | peekaboo |
+| `browser-automation` | Web automation | computer-use + peekaboo |
+
+### 🧠 AI & LLM
+
+| Capability | Description | Providers |
+|------------|-------------|-----------|
+| `llm-anthropic` | Claude models | anthropic connector |
+| `llm-openai` | GPT models | openai connector |
+| `llm-gemini` | Gemini models | gemini connector |
+| `llm-local` | Local models | ollama |
+| `text-to-speech` | Voice synthesis | elevenlabs |
+| `speech-to-text` | Transcription | openai-whisper |
+| `image-generation` | Generate images | openai (DALL-E) |
+
+### 🏠 Smart Home
+
+| Capability | Description | Providers |
+|------------|-------------|-----------|
+| `smart-lights` | Philips Hue | openhue |
+| `smart-audio` | Sonos, BluOS | sonoscli, blucli |
+| `smart-sleep` | Eight Sleep | eightctl |
+
+### 🎵 Music
+
+| Capability | Description | Providers |
+|------------|-------------|-----------|
+| `spotify` | Spotify playback | spotify-player |
+| `music-detection` | Identify songs | songsee |
+
+### 🌐 Web
+
+| Capability | Description | Providers |
+|------------|-------------|-----------|
+| `web-search` | Search the web | brave-search |
+| `web-scraping` | Extract content | firecrawl, apify |
+| `weather` | Weather forecasts | weather guide |
+
+### 💻 Development
+
+| Capability | Description | Providers |
+|------------|-------------|-----------|
+| `version-control` | Git/GitHub | github connector |
+| `terminal-sessions` | Tmux management | tmux |
+| `mcp-tools` | MCP server management | mcporter |
+
+### 🔐 Security
+
+| Capability | Description | Providers |
+|------------|-------------|-----------|
+| `credential-management` | Secure secret storage | 1password, keychain |
+| `oauth-management` | OAuth token handling | google-oauth |
+
+---
+
+## Capability Status Levels
+
+| Emoji | Status | Meaning |
+|-------|--------|---------|
+| ✅ | `active` | Configured AND has been used |
+| ⭐ | `ready` | Configured, never used |
+| 🔧 | `needs-setup` | Needs credential/config |
+| 📥 | `needs-install` | Tool needs installation |
+| ⛔ | `unavailable` | Not available on this platform |
+| ❌ | `broken` | Was working, now failing |
+
+---
+
+## What's Usable Immediately
+
+After core onboarding (identity + workspace), these work with no setup:
+
+| Skill | Type | Why |
+|-------|------|-----|
+| filesystem | Guide | Just shell commands |
+| computer-use | Guide | Uses peekaboo (macOS FDA) |
+| weather | Guide | Free API |
+| tmux | Tool | Usually pre-installed |
+| peekaboo | Tool | macOS FDA only |
+
+Everything else requires connector setup (API keys, OAuth, etc.).
+
+---
+
+## Recommended Paths
+
+### Quick Path (~35 min)
+
+For users who want to text their agent ASAP:
+
+```
+Core Onboarding (15 min)
+  └─ Filesystem wow moment
+      │
+      ▼
+User Comms: iMessage via eve (5 min)
+  └─ "You should text Mom back"
+      │
+      ▼
+Enable LLM: Anthropic API (5 min)
+      │
+      ▼
+Agent Comms: Discord (10 min)
+  └─ Can text agent from phone!
+```
+
+### Developer Path (~75 min)
+
+For developers who want full automation:
+
+```
+Core Onboarding (15 min)
+      │
+      ▼
+Credential Manager: 1Password (10 min)
+      │
+      ▼
+User Data: GitHub (5 min) + Gmail (15 min)
+      │
+      ▼
+Enable LLM: Multiple API keys (5 min)
+      │
+      ▼
+Agent Comms: Discord (10 min)
+      │
+      ▼
+Automation: cron jobs (15 min)
+```
+
+---
+
+## AI Power Formula
+
+```
+AI Power = Capability × Alignment × Duration × Throughput
+```
+
+| Factor | What It Measures | Key Unlocks |
+|--------|------------------|-------------|
+| **Capability** | What agent CAN do | Each connector adds capability |
+| **Alignment** | How well agent knows YOU | User comms, identity |
+| **Duration** | How LONG agent can work | Automation, scheduling |
+| **Throughput** | PARALLEL agent work | Enable LLM + Agent Comms |
+
+The deeper you go in the taxonomy, the more powerful ALL your capabilities become.
+
+---
+
+## Full Power Scenario
+
+When everything is configured:
+
+```
+1. Email arrives about flight check-in (email-read)
+2. Agent reads it automatically (Enable LLM)
+3. Agent uses computer-use to check you in (gui-automation)
+4. Agent texts you: "Checked in! Seat 14A" (agent-comms)
+5. Agent sets reminder for departure (scheduling)
+```
+
+This requires: Email + LLM + GUI Automation + Agent Comms + Scheduling
+
+---
+
+## See Also
+
+- **[Full Capability List](./06_CAPABILITIES_REFERENCE.md)** - Exhaustive provider mapping
+- **[CLI Reference](./02_CLI_REFERENCE.md)** - `nexus capabilities` command