@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/SKILLS_SPECIFICATION.md

@@ -0,0 +1,947 @@
+# Skills Specification
+
+Complete specification for the Nexus skill system: structure, types, state, usage tracking, and discovery.
+
+## Related Work / Inspiration
+
+This specification draws from several sources:
+
+- **Dex (Chetan Conikee)** — Skill crystallization, adapter pattern, fingerprinting, adaptive forgetting, workspace recording as training data
+- **Taxonomy Discussion (Opus)** — Clean separation of Connector → Tool → Skill layers, abstract interfaces, "skills are stateless prompts"
+- **Claude Skills / ClawdHub** — SKILL.md format, skill sharing hub, tool mappings
+- **MCP (Anthropic)** — Protocol patterns, tool definitions, server manifests
+
+Key insights incorporated:
+1. Skills should be **stateless prompts** — tools own state, not skills
+2. **Crystallization** is a powerful optimization for repeated workflows
+3. **Abstract interfaces** enable portability (email_sender vs gog)
+4. **Fingerprinting** enables security and drift detection
+5. **Workspace as training data** — usage logs are valuable
+
+---
+
+## 1. What is a Skill?
+
+A **skill** is a packaged capability that an agent can use. It consists of:
+
+1. **SKILL.md** — The prompt/instructions + metadata (required)
+2. **Supporting files** — Scripts, docs, references (optional)
+3. **Runtime state** — Tracked in `~/nexus/state/nexus/skills/{skill}/` (managed by nexus)
+
+Skills are the atomic units of agent capability. They can be:
+- **Pure prompts** — Just instructions the agent follows
+- **Tool-backed** — Require a binary installed on the system
+- **Script-backed** — Run via interpreter (node, python)
+- **Connector-backed** — Require external credentials/API keys
+
+### 1.1 Conceptual Layering
+
+To understand skills properly, we need to distinguish three layers:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  SKILL (Prompt Layer)                                           │
+│  • Stateless instructions (.md file)                            │
+│  • References tools and connectors                              │
+│  • Distributable as .md + manifest                              │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓ uses
+┌─────────────────────────────────────────────────────────────────┐
+│  TOOL (Capability Layer)                                        │
+│  • Binary/CLI that performs work                                │
+│  • Stateful — owns caches, databases, files                     │
+│  • May depend on connectors                                     │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓ authenticates via
+┌─────────────────────────────────────────────────────────────────┐
+│  CONNECTOR (Auth Layer)                                         │
+│  • Auth + API endpoint access                                   │
+│  • Stateless — just credentials                                 │
+│  • Maps to ~/nexus/state/credentials/                           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Key insight:** Skills are prompts (stateless). Tools have state. Connectors are just auth.
+
+This means:
+- **Skills don't have state** — They're just instructions
+- **Runtime state** (`state.json`, `usage.log`) tracks skill *execution*, not skill *data*
+- **Tool state** lives in the tool's own location (e.g., `~/.config/gog/`)
+- **Connector state** lives in `~/nexus/state/credentials/`
+
+---
+
+## 2. SKILL.md Structure
+
+### 2.1 Frontmatter (YAML)
+
+```yaml
+---
+name: skill-name
+description: One-line description of what the skill does
+homepage: https://example.com/docs
+metadata: {"nexus":{...}}
+---
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique identifier (lowercase, kebab-case) |
+| `description` | Yes | Brief description for agent context |
+| `homepage` | No | Link to documentation/source |
+| `metadata` | No | JSON object with nexus-specific config |
+
+### 2.2 Nexus Metadata Object
+
+The `metadata` field contains a JSON object with a `nexus` key:
+
+```json
+{
+  "nexus": {
+    "emoji": "📧",
+    "os": ["darwin", "linux"],
+    "requires": {
+      "bins": ["gog"],
+      "anyBins": ["interpreter", "peekaboo"],
+      "env": ["BRAVE_API_KEY"],
+      "config": ["browser.enabled"]
+    },
+    "install": [
+      {
+        "id": "brew",
+        "kind": "brew",
+        "formula": "steipete/tap/gogcli",
+        "bins": ["gog"],
+        "label": "Install gog (brew)"
+      }
+    ],
+    "primaryEnv": "BRAVE_API_KEY",
+    "skillKey": "brave",
+    "bundled": true,
+    "priority": "high",
+    "always": true
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `emoji` | string | Visual identifier for the skill |
+| `os` | string[] | Platform restrictions: `["darwin", "linux", "win32"]` |
+| `requires.bins` | string[] | ALL of these binaries must exist in PATH |
+| `requires.anyBins` | string[] | ANY ONE of these binaries must exist |
+| `requires.env` | string[] | Required environment variables |
+| `requires.config` | string[] | Required nexus config paths (e.g., `browser.enabled`) |
+| `install` | InstallSpec[] | How to install required tools |
+| `primaryEnv` | string | Main env var for API key (used with `apiKey` in config) |
+| `skillKey` | string | Override key for skill-specific config lookup |
+| `bundled` | boolean | True if this ships with nexus-core |
+| `priority` | string | `"high"` for skills that should load early |
+| `always` | boolean | True to always include, ignoring requirements |
+
+### 2.3 Install Specification
+
+```typescript
+type InstallSpec = {
+  id: string;           // Unique identifier for this install option
+  kind: "brew" | "node" | "go" | "uv" | "shell";
+  formula?: string;     // For brew
+  package?: string;     // For npm/go/uv
+  module?: string;      // For uv pip
+  script?: string;      // For shell
+  bins?: string[];      // Binaries this install provides
+  label?: string;       // Human-readable label
+};
+```
+
+### 2.4 Body (Markdown)
+
+After the frontmatter, the rest of the file is the skill's prompt/instructions:
+
+```markdown
+# Skill Name
+
+Brief description and context.
+
+## Commands
+
+```bash
+tool-name subcommand --flag value
+```
+
+## Workflow
+
+1. Step one
+2. Step two
+
+## Examples
+
+...
+
+## Guardrails
+
+- Safety rule 1
+- Safety rule 2
+```
+
+The body should include:
+- **Commands/Usage** — How to invoke the skill's tools
+- **Workflow** — Recommended order of operations
+- **Examples** — Real command examples
+- **Guardrails** — Safety rules and limitations
+- **References** — Links to supporting docs in the skill folder
+
+---
+
+## 3. Skill Types
+
+Skills are classified into three types based on execution method:
+
+### 3.1 Pure Prompt Skills
+
+**No external tool required.** The skill is purely instructional.
+
+```typescript
+const PROMPT_ONLY_SKILLS = new Set([
+  "filesystem",      // Shell commands for file organization
+  "computer-use",    // Instructions for using automation tools
+  "weather",         // Use web search/APIs
+  "github",          // Use gh CLI (usually pre-installed)
+  "discord",         // MCP or API usage patterns
+  "apple-notes",     // AppleScript/osascript patterns
+  "apple-reminders", // AppleScript/osascript patterns
+  "onboarding",      // Nexus internal
+]);
+```
+
+**Characteristics:**
+- Always "configured" (no verification needed)
+- Prompt is returned directly via `nexus skill run <name>`
+- Zero dependencies
+
+### 3.2 Tool-Backed Skills
+
+**Require a binary installed on the system.**
+
+```typescript
+const KNOWN_SKILL_TOOLS: Record<string, ToolSkillConfig> = {
+  gog: {
+    tool: "gog",
+    verify: "gog gmail labels list --account default",
+    requiresAuth: true,
+  },
+  eve: {
+    tool: "eve",
+    verify: "eve messages --limit 1",
+    requiresAuth: true,
+  },
+  "1password": {
+    tool: "op",
+    verify: "op whoami",
+    requiresAuth: true,
+  },
+  tmux: {
+    tool: "tmux",
+    verify: "tmux -V",
+  },
+  // ... etc
+};
+
+type ToolSkillConfig = {
+  tool: string;           // Binary name
+  verify: string;         // Command to verify it works
+  requiresAuth?: boolean; // Needs OAuth/login
+  configEnv?: string[];   // Env vars that indicate config
+};
+```
+
+**Characteristics:**
+- `nexus skill run <name> -- args` passes args to the tool
+- Verification runs the verify command
+- Gateway captures stdout/stderr/exit code
+
+### 3.3 Script-Backed Skills
+
+**Run via an interpreter (node, python, etc).**
+
+```typescript
+const SCRIPT_SKILLS: Record<string, ScriptSkillConfig> = {
+  "brave-search": {
+    runner: "node",
+    script: "scripts/search.mjs",
+    requiredEnv: ["BRAVE_API_KEY"],
+  },
+  "openai-image-gen": {
+    runner: "python",
+    script: "scripts/gen.py",
+    requiredEnv: ["OPENAI_API_KEY"],
+  },
+};
+
+type ScriptSkillConfig = {
+  runner: string;        // Interpreter binary
+  script: string;        // Relative path from skill dir
+  requiredEnv?: string[];// Required env vars
+};
+```
+
+**Characteristics:**
+- `nexus skill run <name> -- args` runs `runner script args`
+- Working directory is the skill folder
+- Requires both interpreter and env vars
+
+### 3.4 Connector Classification
+
+**Orthogonal to type:** Any skill can also be a "connector" if it requires external credentials:
+
+| Classification | Needs | Examples |
+|---------------|-------|----------|
+| **Pure Prompt** | Nothing | filesystem, weather |
+| **Tool** | Binary only | tmux, ffmpeg |
+| **Tool + Connector** | Binary + OAuth/API | gog, eve, 1password |
+| **Script + Connector** | Interpreter + API key | brave-search, openai-image-gen |
+
+Connectors are important for the capability taxonomy because they represent the "locked" capabilities that require user action to enable.
+
+---
+
+## 4. Per-Skill State
+
+### 4.1 Storage Location
+
+**Decision: Per-skill folders (not single file)**
+
+```
+~/nexus/state/
+└── nexus/
+    └── skills/
+        ├── manifest.json          # Discovery manifest
+        ├── gog/
+        │   ├── state.json
+        │   └── usage.log
+        ├── eve/
+        │   ├── state.json
+        │   └── usage.log
+        └── filesystem/
+            ├── state.json
+            └── usage.log
+```
+
+**Why per-skill folders?**
+- **Isolation**: Skill state is self-contained
+- **Git-friendliness**: Can track individual skills
+- **Partial reads**: Don't load entire state file for one skill
+- **Future extensibility**: Can add more per-skill files (custom config, etc)
+
+### 4.2 State Schema (`state.json`)
+
+```typescript
+type SkillState = {
+  version: 1;
+  
+  // Execution metadata (from KNOWN_SKILL_TOOLS or detected)
+  tool?: string;              // CLI binary name
+  verify?: string;            // Verification command
+  type?: "tool" | "script" | "prompt";
+  
+  // Runtime state (updated by gateway)
+  configured: boolean;        // Has verification passed?
+  configuredAt?: string;      // ISO timestamp of first success
+  lastVerified?: string;      // ISO timestamp of last verify attempt
+  lastUsed?: string;          // ISO timestamp of last execution
+  lastError?: string;         // Last error message (truncated)
+  
+  // Computed stats (from usage log)
+  totalInvocations?: number;
+  successRate?: number;       // 0-1
+  avgDurationMs?: number;
+};
+```
+
+**Example:**
+```json
+{
+  "version": 1,
+  "tool": "gog",
+  "verify": "gog gmail labels list --account default",
+  "type": "tool",
+  "configured": true,
+  "configuredAt": "2026-01-10T15:30:00Z",
+  "lastVerified": "2026-01-14T08:00:00Z",
+  "lastUsed": "2026-01-14T12:05:00Z",
+  "lastError": null,
+  "totalInvocations": 47,
+  "successRate": 0.957,
+  "avgDurationMs": 1234
+}
+```
+
+### 4.3 Usage Log (`usage.log`)
+
+**Format:** JSON Lines (append-only)
+
+```typescript
+type UsageLogEntry = {
+  ts: string;                 // ISO timestamp
+  type: "tool" | "script" | "prompt";
+  args?: string[];            // Command arguments (for tools/scripts)
+  exit?: number;              // Exit code
+  ms: number;                 // Duration in milliseconds
+  error?: string;             // Error message (truncated to 200 chars)
+  tool?: string;              // Tool binary that was invoked
+};
+```
+
+**Example:**
+```json
+{"ts":"2026-01-14T12:05:00Z","type":"tool","args":["gmail","messages","list","--limit","5"],"exit":0,"ms":1234,"tool":"gog"}
+{"ts":"2026-01-14T12:10:00Z","type":"tool","args":["calendar","events"],"exit":1,"ms":500,"error":"rate limit exceeded","tool":"gog"}
+{"ts":"2026-01-14T12:15:00Z","type":"prompt","ms":5}
+```
+
+**Log Rotation:**
+- Keep last 5,000 entries OR 2MB, whichever is smaller
+- Prune on write if size exceeds threshold
+- Keep most recent entries
+
+---
+
+## 5. Skill Discovery & Indexing
+
+### 5.1 Discovery Sources
+
+Skills are loaded from multiple sources with precedence:
+
+```
+Source Priority (lowest to highest):
+1. extra dirs     - config.skills.load.extraDirs
+2. bundled        - nexus-core/skills/
+3. managed        - ~/.nexus/skills/ or MANAGED_SKILLS_DIR
+4. workspace      - ~/nexus/skills/
+```
+
+Higher precedence sources override lower ones (by skill name).
+
+### 5.2 Manifest (`manifest.json`)
+
+The manifest is a cache of discovered skills for fast lookup:
+
+```typescript
+type SkillsManifest = {
+  version: 1;
+  generatedAt: string;        // ISO timestamp
+  skills: Record<string, ManifestEntry>;
+};
+
+type ManifestEntry = {
+  name: string;
+  description: string;
+  source: "nexus-bundled" | "nexus-managed" | "nexus-workspace" | "nexus-extra";
+  filePath: string;           // Absolute path to SKILL.md
+  
+  // From nexus metadata
+  emoji?: string;
+  os?: string[];
+  requires?: {
+    bins?: string[];
+    anyBins?: string[];
+    env?: string[];
+    config?: string[];
+  };
+  type?: "tool" | "script" | "prompt";
+  tool?: string;              // For tool-backed skills
+  
+  // Install info
+  hasInstall?: boolean;
+};
+```
+
+**Regeneration:**
+- On `nexus skills refresh`
+- On first run after nexus update
+- When skill folder mtime changes
+
+### 5.3 Filtering
+
+At runtime, skills are filtered before presentation:
+
+```typescript
+function shouldIncludeSkill(skill: ManifestEntry, config: NexusConfig): boolean {
+  // 1. Check explicit disable in config
+  if (config.skills.entries[skill.name]?.enabled === false) return false;
+  
+  // 2. Check OS compatibility
+  if (skill.os?.length && !skill.os.includes(process.platform)) return false;
+  
+  // 3. Check bundled allowlist
+  if (skill.source === "nexus-bundled" && config.skills.allowBundled) {
+    if (!config.skills.allowBundled.includes(skill.name)) return false;
+  }
+  
+  // 4. Skip binary/env checks for "always" skills
+  if (skill.always) return true;
+  
+  // 5. Check required bins
+  if (skill.requires?.bins?.some(bin => !hasBinary(bin))) return false;
+  
+  // 6. Check anyBins (at least one)
+  if (skill.requires?.anyBins?.length) {
+    if (!skill.requires.anyBins.some(bin => hasBinary(bin))) return false;
+  }
+  
+  // 7. Check required env vars
+  for (const env of skill.requires?.env ?? []) {
+    if (!process.env[env] && !config.skills.entries[skill.name]?.apiKey) {
+      return false;
+    }
+  }
+  
+  // 8. Check required config paths
+  for (const path of skill.requires?.config ?? []) {
+    if (!isConfigPathTruthy(config, path)) return false;
+  }
+  
+  return true;
+}
+```
+
+### 5.4 Listing Categories
+
+When presenting skills, they should be grouped:
+
+```
+✅ READY (configured, working)
+   - Skills where state.configured === true
+
+⚠️  NEEDS SETUP (requires configuration)
+   - Tool exists but verification failed
+   - Missing env vars / API keys
+   - OAuth not completed
+
+⏳ NOT INSTALLED (binary missing)
+   - Required binary not in PATH
+   - Has install instructions
+
+💤 DISABLED (explicitly disabled)
+   - config.skills.entries[name].enabled === false
+```
+
+---
+
+## 6. CLI Integration
+
+### 6.1 Commands
+
+```bash
+# Discovery
+nexus skills list [--ready|--locked|--all] [--json]
+nexus skills refresh
+
+# Per-skill
+nexus skill show <name>             # Details + prompt
+nexus skill verify <name> [--force] # Check configuration
+nexus skill run <name> [-- args]    # Execute via gateway
+nexus skill stats [name]            # Usage statistics
+```
+
+### 6.2 `nexus skill run` Flow
+
+```
+1. Load skill from manifest
+   → Not found? Error with suggestions
+
+2. Determine type (tool/script/prompt)
+   → prompt? Return prompt content, log, exit
+
+3. Check binary exists (for tool/script)
+   → Missing? Show install instructions, exit 1
+
+4. Check configured (first-run verification)
+   → Not configured? Run verify command
+   → Verify fails? Show setup instructions, exit 1
+   → Verify succeeds? Update state, continue
+
+5. Execute tool/script with args
+   → Capture stdout/stderr/exit code
+   → Track duration
+
+6. Log invocation to usage.log
+
+7. Update state.json
+   → lastUsed, totalInvocations, successRate
+
+8. Return output
+   → Print stdout/stderr
+   → Exit with tool's exit code
+```
+
+---
+
+## 7. Implementation Notes
+
+### 7.1 Current vs Planned State Location
+
+**Current implementation:**
+- `~/nexus/state/skill-state.json` — single file with all skills
+- `~/nexus/state/skill-usage.log` — single log file
+
+**Planned (per STATE_ARCHITECTURE.md):**
+- `~/nexus/state/nexus/skills/{skill}/state.json`
+- `~/nexus/state/nexus/skills/{skill}/usage.log`
+
+**Migration needed:** The existing `skill-state.ts` and `skill-usage.ts` need updating to use per-skill folders.
+
+### 7.2 Static Mappings Location
+
+Currently in `skill-tools.ts`:
+- `KNOWN_SKILL_TOOLS` — hardcoded tool configs
+- `SCRIPT_SKILLS` — hardcoded script configs
+- `PROMPT_ONLY_SKILLS` — hardcoded set
+
+**Future improvement:** Move these into SKILL.md frontmatter or per-skill config, so skills are fully self-describing. For now, the static mappings work and can be extended.
+
+### 7.3 Adding a New Skill
+
+1. Create `skills/{name}/SKILL.md` with frontmatter
+2. Add to `KNOWN_SKILL_TOOLS`, `SCRIPT_SKILLS`, or `PROMPT_ONLY_SKILLS` in `skill-tools.ts`
+3. Run `nexus skills refresh` to update manifest
+4. Run `nexus skill verify {name}` to test
+
+---
+
+## 8. Complete SKILL.md Examples
+
+### 8.1 Tool-Backed (gog)
+
+```yaml
+---
+name: gog
+description: Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, People, and Tasks.
+homepage: https://gogcli.sh
+metadata: {"nexus":{"emoji":"📧","requires":{"bins":["gog"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/gogcli","bins":["gog"],"label":"Install gog (brew)"}]}}
+---
+
+# gog
+
+Google Workspace CLI. Requires OAuth setup (see `docs/setup.md`).
+
+## Quick Start
+
+```bash
+gog gmail search "is:unread" --max 10
+gog calendar events --json
+```
+
+...
+```
+
+### 8.2 Script-Backed (brave-search)
+
+```yaml
+---
+name: brave-search
+description: Web search and content extraction via Brave Search API.
+homepage: https://brave.com/search/api
+metadata: {"nexus":{"emoji":"🦁","requires":{"bins":["node"],"env":["BRAVE_API_KEY"]},"primaryEnv":"BRAVE_API_KEY"}}
+---
+
+# Brave Search
+
+```bash
+node {baseDir}/scripts/search.mjs "query" --content
+```
+
+...
+```
+
+### 8.3 Pure Prompt (filesystem)
+
+```yaml
+---
+name: filesystem
+description: Scan, analyze, and organize your filesystem.
+metadata: {"nexus":{"emoji":"📁","bundled":true,"priority":"high","os":["darwin","linux"]}}
+---
+
+# Filesystem Organization Skill
+
+Analyze and organize the user's home directory with safety-first principles.
+
+## Safety Rules
+
+1. **Never delete without explicit approval**
+2. **Dry run by default**
+...
+```
+
+---
+
+## 9. Advanced Concepts (Future)
+
+### 9.1 Abstract vs Concrete Dependencies
+
+Skills can declare abstract dependencies for portability:
+
+```yaml
+# Concrete (current approach)
+requires:
+  tools: [gog]
+  connectors: [google]
+
+# Abstract (future approach)
+requires:
+  capabilities:
+    - email_sender      # gog, outlook, sendgrid could satisfy
+    - calendar_read     # gog, apple-calendar could satisfy
+```
+
+Connectors and tools would implement interfaces:
+
+```yaml
+# In gog's SKILL.md
+implements:
+  - email_sender
+  - email_reader
+  - calendar_read
+  - calendar_write
+  - drive_access
+```
+
+**Benefit:** User can swap implementations. "I need email" doesn't mean "I need Google."
+
+**Status:** Deferred. For now, use concrete dependencies.
+
+### 9.2 Skill Crystallization (Dex Pattern)
+
+For repeated tasks, skills can be **crystallized** into deterministic scripts:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  EXPLORATION (uses LLM)                                         │
+│  Agent figures out how to accomplish task                       │
+│  Records every command, request, response                       │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│  CRYSTALLIZATION                                                │
+│  Extract successful path as shell script                        │
+│  Templatize personal info as variables                          │
+│  Build dependency graph                                         │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│  EXPLOITATION (no LLM needed)                                   │
+│  Run crystallized script directly                               │
+│  Massive cost savings for repeated tasks                        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**State extension for crystallized skills:**
+
+```typescript
+type SkillState = {
+  // ... existing fields ...
+  
+  // Crystallization (future)
+  crystallized?: {
+    scriptPath: string;         // Path to shell script
+    crystallizedAt: string;     // When crystallized
+    variables: string[];        // Required variables
+    fingerprint: string;        // Hash of tool outputs for validation
+    degraded?: boolean;         // True if errors detected
+  };
+};
+```
+
+**Adaptive forgetting:** If a crystallized skill starts failing (fingerprint mismatch, error spike), mark it as `degraded` and fall back to LLM exploration.
+
+**Status:** Deferred. Focus on core skill system first.
+
+### 9.3 Fingerprinting / Verification
+
+Each tool's verify command produces output. Hash this for fingerprinting:
+
+```typescript
+type SkillState = {
+  // ... existing fields ...
+  
+  // Fingerprinting (future)
+  fingerprint?: {
+    verifyOutputHash: string;   // SHA256 of verify command output
+    capturedAt: string;         // When fingerprint taken
+  };
+};
+```
+
+**Uses:**
+- Detect when underlying API changes (new version, deprecated fields)
+- Security: detect if MCP server has been swapped/compromised
+- Trigger re-verification when fingerprint mismatches
+
+**Status:** Deferred. Consider for security-sensitive deployments.
+
+### 9.4 Variable Templatization
+
+For shareable skills, personal info should be parameterized:
+
+```bash
+# Hard-coded (not shareable)
+gog gmail search "from:mom@gmail.com"
+
+# Templatized (shareable)
+gog gmail search "from:${CONTACT_MOM_EMAIL}"
+```
+
+Skills would declare required variables:
+
+```yaml
+metadata:
+  nexus:
+    variables:
+      - name: CONTACT_MOM_EMAIL
+        description: "Email address of your mom"
+        type: string
+```
+
+**Status:** Deferred. For now, skills are templates that agents fill in contextually.
+
+### 9.5 Observability / Analytics Extension
+
+Extended usage log for training data:
+
+```typescript
+type UsageLogEntry = {
+  // ... existing fields ...
+  
+  // Extended (future)
+  model?: string;             // Which model was used
+  modelVersion?: string;      // Model version
+  promptTokens?: number;      // Input tokens
+  completionTokens?: number;  // Output tokens
+  temperature?: number;       // Model temperature
+  
+  // For crystallization
+  sessionId?: string;         // Group related calls
+  parentCall?: number;        // For dependency tracking
+};
+```
+
+**Uses:**
+- "Which model does best for Gmail operations?"
+- Training data for fine-tuning
+- Cost attribution per skill
+
+**Status:** Deferred. Consider for enterprise analytics.
+
+---
+
+## 10. Open Questions Resolved
+
+| Question | Decision |
+|----------|----------|
+| Single file vs per-skill folders? | **Per-skill folders** — better isolation, git-friendly |
+| Where does tool/verify config live? | **skill-tools.ts** for now, migrate to SKILL.md later |
+| How to handle unknown skills? | Return prompt content with warning, log as unknown |
+| Should we track args in logs? | **Yes** — full args, user controls their own logs |
+| Log rotation? | 5,000 entries or 2MB, prune oldest |
+| Skills vs Tools vs Connectors? | **Three layers** — skills are prompts, tools have state, connectors are auth |
+| Abstract dependencies? | **Deferred** — use concrete for now, add interfaces later |
+| Skill crystallization? | **Deferred** — interesting optimization for repeated tasks |
+
+### 9.6 Resources / Context Bundles
+
+Skills can include supporting resources:
+
+```
+skills/gog/
+├── SKILL.md                # Main prompt
+├── docs/
+│   ├── setup.md           # Setup guide
+│   └── portability.md     # Moving to new machine
+├── references/
+│   ├── oauth-flow.md      # OAuth documentation
+│   └── api-limits.md      # Rate limits info
+└── examples/
+    ├── search-queries.md  # Example queries
+    └── calendar-sync.md   # Calendar sync patterns
+```
+
+Resources are bundled with skills when distributed. The SKILL.md can reference them:
+
+```markdown
+## Setup
+See `docs/setup.md` for initial configuration.
+
+## References
+- OAuth flow: `references/oauth-flow.md`
+- API limits: `references/api-limits.md`
+```
+
+**Status:** Already supported. Skills can include any supporting files.
+
+---
+
+## 11. Summary
+
+### File Locations
+
+| Component | Location |
+|-----------|----------|
+| Skill definition | `~/nexus/skills/{name}/SKILL.md` |
+| Skill resources | `~/nexus/skills/{name}/docs/`, `references/`, etc. |
+| Skill state | `~/nexus/state/nexus/skills/{name}/state.json` |
+| Skill usage log | `~/nexus/state/nexus/skills/{name}/usage.log` |
+| Skills manifest | `~/nexus/state/nexus/skills/manifest.json` |
+| Static tool mappings | `nexus-core/src/agents/skill-tools.ts` |
+| Core loader | `nexus-core/src/agents/skills.ts` |
+| State management | `nexus-core/src/agents/skill-state.ts` |
+| Usage tracking | `nexus-core/src/agents/skill-usage.ts` |
+| Gateway runner | `nexus-core/src/agents/skill-runner.ts` |
+
+### Conceptual Model
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      SKILL ECOSYSTEM                            │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   SKILL (.md)          TOOL (binary)        CONNECTOR (auth)   │
+│   ┌─────────────┐      ┌─────────────┐      ┌─────────────┐    │
+│   │ Prompt      │ ──→  │ gog, eve,   │ ──→  │ Google OAuth│    │
+│   │ Stateless   │      │ tmux, etc.  │      │ Credentials │    │
+│   │ Distributable│      │ Stateful    │      │ Stateless   │    │
+│   └─────────────┘      └─────────────┘      └─────────────┘    │
+│                                                                 │
+│   Types:                Types:               Lives in:          │
+│   • Pure prompt         • CLI binary         credentials/       │
+│   • Tool-backed         • Script                                │
+│   • Script-backed       • Native tool                           │
+│   • Connector-backed                                            │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Key Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| **Per-skill state folders** | Isolation, git-friendly, extensible |
+| **Three conceptual layers** | Skills (prompts), Tools (binaries), Connectors (auth) |
+| **Skills are stateless** | Runtime state tracks execution, not skill data |
+| **Static mappings** in code | Simple now, migrate to SKILL.md frontmatter later |
+| **Gateway pattern** | All execution via `nexus skill run` for observability |
+| **Automatic logging** | No agent reporting required, capture everything |
+| **Deferred: abstract deps** | Use concrete dependencies now, add interfaces later |
+| **Deferred: crystallization** | Interesting optimization for repeated workflows |
+
+### Future Directions
+
+1. **Abstract interfaces** — Skills declare "need email" not "need gog"
+2. **Skill crystallization** — Compile successful workflows to scripts
+3. **Fingerprinting** — Detect API changes and compromised tools
+4. **Variable templatization** — Shareable skills with parameterized personal info
+5. **Extended analytics** — Model performance tracking, training data export
+
+---
+
+*This document is the authoritative specification for the Nexus skill system.*