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

package/skills/{onboarding → guides/onboarding}/docs/CLI_GRAMMAR_SKILLS.md

@@ -1,12 +1,16 @@
 # CLI Grammar: Skills, Tools, Connectors, Guides
 
 > Defines the nexus CLI interface for entity discovery, verification, and execution.
-> 
+>
+> **Legacy note:** The current CLI uses `nexus skill list|info|use|verify` and
+> does not execute skills through the CLI. This document is pending a full refresh
+> to match the core CLI spec.
+>
 > **Scope:** This document covers skill-related commands only. Credentials and onboarding are defined separately.
 
 ## Design Principles
 
-1. **Unified discovery, type-specific actions** - Use `nexus skill` for common operations (list, show, verify, run). Use type-specific commands for actions unique to that type.
+1. **Unified discovery, type-specific actions** - Use `nexus skill` for common operations (list, info, use, verify). Use type-specific commands for actions unique to that type.
 
 2. **Progressive disclosure** - `nexus skill list` shows everything. Filters and type-specific commands reveal more detail.
 
@@ -135,22 +139,22 @@ To fix:
   Run 'nexus connector setup google-oauth'
 ```
 
-#### `nexus skill run <name> [args...]`
+#### `nexus skill use <name>`
 
-Execute a skill through the gateway. All invocations are logged.
+Return the SKILL.md guide for a skill. All usages are logged.
 
 ```bash
-nexus skill run gog gmail search "is:unread"    # Run tool with args
-nexus skill run filesystem                       # Output guide prompt
-nexus skill run computer-use                     # Output guide prompt
-nexus skill run gog --timeout 30000              # Custom timeout
-nexus skill run gog --json                       # JSON output wrapper
-nexus skill run gog --no-verify                  # Skip auto-verification
+nexus skill use gog            # Output tool guide
+nexus skill use filesystem     # Output guide prompt
+nexus skill use computer-use   # Output guide prompt
+
+# After reading the guide, run the tool directly:
+gog gmail search "is:unread"
 ```
 
 **Behavior by type:**
-- **Tool**: Executes binary with args, streams stdout/stderr
-- **Connector**: Outputs setup guide (or runs setup script if available)
+- **Tool**: Outputs usage/installation guide
+- **Connector**: Outputs setup guide
 - **Guide**: Outputs the prompt/instructions
 
 #### `nexus skill stats [name]`
@@ -329,11 +333,11 @@ Used by tools:
 
 ### `nexus guide` - Guide-Specific Operations
 
-Guides are mostly accessed via `nexus skill show/run`, but have one specific command.
+Guides are mostly accessed via `nexus skill info/use`, but have one specific command.
 
 #### `nexus guide use <name>`
 
-Shortcut to output a guide's prompt (same as `nexus skill run <name>` for guides).
+Shortcut to output a guide's prompt (same as `nexus skill use <name>` for guides).
 
 ```bash
 nexus guide use computer-use          # Output the guide
@@ -345,9 +349,9 @@ nexus guide use filesystem            # Output the guide
 ## Entity Resolution
 
 When a name is provided, nexus searches in order:
-1. `tools/<name>/SKILL.md`
-2. `connectors/<name>/SKILL.md`
-3. `guides/<name>/SKILL.md`
+1. `skills/tools/<name>/SKILL.md`
+2. `skills/connectors/<name>/SKILL.md`
+3. `skills/guides/<name>/SKILL.md`
 4. Legacy `skills/<name>/SKILL.md` (during migration)
 
 If ambiguous (same name in multiple locations), prefer the explicit type command:
@@ -360,7 +364,7 @@ nexus connector show myname
 
 ## State Tracking
 
-All `nexus skill run` invocations are logged to:
+All `nexus skill use` invocations are logged to:
 ```
 ~/nexus/state/nexus/skills/<name>/
 ├── state.json     # configured, lastUsed, lastVerified, errors
@@ -402,7 +406,8 @@ nexus skill list --provides email --locked
 nexus skill verify gog
 
 # Use gog
-nexus skill run gog gmail search "is:unread" --max 5
+nexus skill use gog
+gog gmail search "is:unread" --max 5
 ```
 
 ### User setting up a new tool
@@ -421,7 +426,8 @@ nexus connector setup google-oauth
 nexus skill verify gog
 
 # Use it
-nexus skill run gog gmail search "is:unread"
+nexus skill use gog
+gog gmail search "is:unread"
 ```
 
 ### Checking what needs configuration

package/skills/{onboarding → guides/onboarding}/docs/GOAL_STATE_ARCHITECTURE.md

@@ -47,14 +47,14 @@ System works without full configuration. Pure prompt-only skills work immediatel
 **Characteristics**:
 - **Static content** - Rarely changes, contains protocols not state
 - **Nexus-managed** - Created by `nexus init`, can be repopulated if deleted
-- **Points to nexus CLI** - Agent's first action is always `nexus skills status`
+- **Points to nexus CLI** - Agent's first action is always `nexus status`
 - **Contains**: Identity file pointers, safety rules, memory protocols, gateway instructions
 
 **Key Instruction**:
 ```markdown
 ## First Action - Always
 Before doing ANYTHING else, run:
-nexus skills status
+nexus status
 
 This tells you who you are, what you can do, and what to do next.
 ```
@@ -108,25 +108,22 @@ home/
 state/
 ├── nexus/
 │   ├── gateway.json       # Gateway configuration
-│   ├── skills/            # Per-skill state and usage logs
-│   │   ├── manifest.json
-│   │   └── {skill}/
-│   │       ├── state.json
-│   │       └── usage.log
 │   └── onboarding/
 │       ├── progress.json
 │       └── wizard.json
+├── skills/                # Per-skill state and usage logs
+│   ├── manifest.json
+│   └── {skill}/
+│       ├── state.json
+│       └── usage.log
 ├── credentials/           # Centralized credentials tree
 ├── user/
-│   └── identity/
-│       └── PROFILE.md     # User profile
+│   └── IDENTITY.md        # User profile
 └── agents/
     └── {agent}/
-        ├── identity/
-        │   ├── IDENTITY.md
-        │   ├── SOUL.md
-        │   └── MEMORY.md
-        └── config.json
+        ├── IDENTITY.md
+        ├── SOUL.md
+        └── MEMORY.md
 ```
 
 ### skills/ (Nexus-Owned)
@@ -135,8 +132,8 @@ state/
 
 **Characteristics**:
 - Read-only for agents (they execute, don't modify)
-- Discovered via `nexus skills status`
-- Executed via `nexus skill run`
+- Discovered via `nexus status` or `nexus skill list`
+- Accessed via `nexus skill use`
 
 ---
 
@@ -151,9 +148,9 @@ New installations have no identity configured. How does the agent know to bootst
 ### Detection Flow
 
 ```
-Agent runs: nexus skills status
+Agent runs: nexus status
     │
-    ├─► Nexus checks: Does state/agents/{agent}/identity/IDENTITY.md exist and have content?
+    ├─► Nexus checks: Do state/agents/{agent}/IDENTITY.md and state/user/IDENTITY.md exist and have content?
     │
     ├─► If NO → Return: "Identity not configured. Starting bootstrap conversation..."
     │            Include: BOOTSTRAP.md contents or instructions
@@ -170,11 +167,11 @@ The agent discovers:
 2. **Who the user is** - Name, preferences, how to address them
 3. **Shared values** - What matters, boundaries, working style
 
-Output: Agent writes to `state/agents/{agent}/identity/` and `state/user/identity/`
+Output: Agent writes to `state/agents/{agent}/` and `state/user/`
 
 ### Agent Identity Tracking
 
-**Location**: `state/agents/{agent}/identity/`
+**Location**: `state/agents/{agent}/`
 
 **Files**:
 - `IDENTITY.md` - Name, emoji, creature type, vibe
@@ -182,7 +179,7 @@ Output: Agent writes to `state/agents/{agent}/identity/` and `state/user/identit
 - `MEMORY.md` - Curated long-term memories
 
 **User Understanding**:
-The agent's understanding of the user lives in `state/user/identity/PROFILE.md`:
+The agent's understanding of the user lives in `state/user/IDENTITY.md`:
 - How to address them
 - Timezone
 - Communication preferences
@@ -207,25 +204,23 @@ Creates the following structure with sensible defaults:
 │   └── rules              # Cursor-specific config (pointer + extras)
 ├── state/
 │   ├── nexus/
-│   │   ├── skills/
-│   │   │   └── manifest.json
 │   │   └── onboarding/
 │   │       └── progress.json
+│   ├── skills/
+│   │   └── manifest.json
 │   ├── credentials/
 │   │   └── index.json
 │   ├── user/
-│   │   └── identity/
-│   │       └── PROFILE.md  # Empty template
+│   │   └── IDENTITY.md  # Empty template
 │   └── agents/
 │       └── default/
-│           └── identity/
-│               ├── IDENTITY.md  # Empty template
-│               ├── SOUL.md      # Template content
-│               └── MEMORY.md    # Empty
+│           ├── IDENTITY.md  # Empty template
+│           ├── SOUL.md      # Template content
+│           └── MEMORY.md    # Empty
 ├── home/
 │   ├── memory/            # For daily logs
 │   └── projects/          # For user's repos
-└── skills/                # Symlink to bundled skills
+└── skills/                # Skill definitions (bundled + managed)
 ```
 
 ### Automatic Setup
@@ -233,7 +228,7 @@ Creates the following structure with sensible defaults:
 - **AGENTS.md** - Populated from template, contains full protocols
 - **.cursor/rules** - Populated with pointer pattern + cursor specifics
 - **State folders** - Created with empty/template files
-- **Skills** - Symlinked to bundled skills location
+- **Skills** - Copied into `~/nexus/skills`
 
 ### Idempotent Behavior
 
@@ -255,7 +250,7 @@ Running `nexus init` on existing workspace:
 - Raw daily logs of what happened
 - Agent reads today + yesterday on session start
 
-**Long-term Memory**: `state/agents/{agent}/identity/MEMORY.md`
+**Long-term Memory**: `state/agents/{agent}/MEMORY.md`
 - Curated by agent
 - Distilled insights, not raw logs
 - Security: only loaded in main sessions (not shared contexts)
@@ -282,7 +277,7 @@ For simplicity, assume one agent per workspace:
 
 ### Agent Name Discovery
 
-When `nexus skills status` runs:
+When `nexus status` runs:
 1. Look for agents in `state/agents/`
 2. If exactly one → use that
 3. If zero → use "default"
@@ -294,7 +289,7 @@ When `nexus skills status` runs:
 
 ### Why Gateway?
 
-All skill execution flows through `nexus skill run`:
+All skill access flows through `nexus skill use`:
 - **Automatic logging** - No agent cooperation needed
 - **State tracking** - lastUsed, errors, success rate
 - **Verification** - Check configuration before first run
@@ -304,14 +299,14 @@ All skill execution flows through `nexus skill run`:
 
 ```bash
 # Status and discovery
-nexus skills status              # What's ready, what's locked, recommendations
-nexus skills status --ready      # Only configured skills
-nexus skills status --locked     # Only unconfigured skills
+nexus status                     # What's ready, what's locked, recommendations
+nexus skill list --ready         # Only configured skills
+nexus skill list --needs-setup   # Only unconfigured skills
 
 # Skill operations
 nexus skill show <name>          # Details and prompt
 nexus skill verify <name>        # Check configuration
-nexus skill run <name> [args...] # Execute through gateway
+nexus skill use <name>           # Return guide (logged)
 nexus skill stats [name]         # Usage analytics
 
 # Identity and credentials
@@ -334,7 +329,7 @@ The existing BOOTSTRAP.md and SOUL.md templates are good. Changes:
 | Current | Goal State |
 |---------|------------|
 | .cursor/rules has full instructions | Points to AGENTS.md |
-| Agent reads multiple config files | Agent queries `nexus skills status` |
+| Agent reads multiple config files | Agent queries `nexus status` |
 | Onboarding is separate skill | Built into nexus core |
 | Manual skill verification | Automatic via gateway |
 
@@ -347,9 +342,9 @@ The existing BOOTSTRAP.md and SOUL.md templates are good. Changes:
     │
 2. IDE loads .cursor/rules (or AGENTS.md)
     │
-3. Agent sees: "Run nexus skills status first"
+3. Agent sees: "Run nexus status first"
     │
-4. Agent runs: nexus skills status
+4. Agent runs: nexus status
     │
     ├─► No identity? → Nexus returns bootstrap instructions
     │                  Agent starts identity conversation
@@ -374,9 +369,9 @@ The existing BOOTSTRAP.md and SOUL.md templates are good. Changes:
 
 | Decision | Choice | Rationale |
 |----------|--------|-----------|
-| Where does identity live? | `state/agents/{agent}/identity/` | Protected from user accidents |
+| Where does identity live? | `state/agents/{agent}/` | Protected from user accidents |
 | Who owns home/? | User entirely | Clean separation |
-| How does agent know state? | `nexus skills status` | Single source of truth |
+| How does agent know state? | `nexus status` | Single source of truth |
 | What triggers bootstrap? | Nexus detects missing identity | Minimal agent responsibility |
 | AGENTS.md vs .cursorrules? | Cursor rules points to AGENTS.md | Avoid duplication |
 | Multi-agent support? | Defer, assume single agent | Simplicity first |

package/skills/{onboarding → guides/onboarding}/docs/NEXUS_SYSTEM_OVERVIEW.md

@@ -33,7 +33,7 @@
 │  │ • Memory protocols (daily logs, long-term memory, qmd)                  │    │
 │  │ • Safety rules (external vs internal actions)                           │    │
 │  │ • Social behavior (group chats, heartbeats)                             │    │
-│  │ • Gateway instructions (nexus skill run)                                │    │
+│  │ • Gateway instructions (nexus skill use)                                │    │
 │  │ • First action: run `nexus skills status`                               │    │
 │  └─────────────────────────────────────────────────────────────────────────┘    │
 │                                      │                                           │
@@ -143,7 +143,7 @@
 │                                                                                  │
 │  nexus skill show <name>          # Skill details + prompt                      │
 │  nexus skill verify <name>        # Check if configured correctly               │
-│  nexus skill run <name> [args...] # Execute through gateway (logged)            │
+│  nexus skill use <name>            # Return guide (logged)                      │
 │  nexus skill stats [name]         # Usage analytics                             │
 │                                                                                  │
 ├─────────────────────────────────────────────────────────────────────────────────┤
@@ -153,7 +153,7 @@
 │  Agent wants to use a skill                                                     │
 │       │                                                                         │
 │       ▼                                                                         │
-│  nexus skill run <name> [args...]                                               │
+│  nexus skill use <name>                                                         │
 │       │                                                                         │
 │       ├──► Is this first run? ──► YES ──► Verify skill ──► Pass? ──► Continue  │
 │       │                                              └──► Fail? ──► Show setup │
@@ -184,7 +184,7 @@ nexus status                         # Convenience alias (planned)
 nexus skills list [--ready|--locked] # Discovery
 nexus skill show <name>              # Prompt + metadata + setup
 nexus skill verify <name>            # Check configuration
-nexus skill run <name> [-- args]     # Gateway execution (logged)
+nexus skill use <name>               # Guide retrieval (logged)
 nexus skill stats [name]             # Usage analytics
 
 # Credentials + ownership

package/skills/{onboarding → guides/onboarding}/docs/SKILLS_HUB_SPEC.md

@@ -402,7 +402,7 @@ CLI integration (nexus)
 Local usage (existing):
 - `nexus skill use <name>` -> show SKILL.md (alias of show)
 - `nexus skill verify <name>`
-- `nexus skill run <name>`
+- `nexus skill use <name>`
 - `nexus skill stats [name]`
 
 Hub operations (new/extend `nexus skills`):

package/skills/{onboarding → guides/onboarding}/docs/SKILLS_SPECIFICATION.md

@@ -216,7 +216,7 @@ const PROMPT_ONLY_SKILLS = new Set([
 
 **Characteristics:**
 - Always "configured" (no verification needed)
-- Prompt is returned directly via `nexus skill run <name>`
+- Prompt is returned directly via `nexus skill use <name>`
 - Zero dependencies
 
 ### 3.2 Tool-Backed Skills
@@ -256,9 +256,9 @@ type ToolSkillConfig = {
 ```
 
 **Characteristics:**
-- `nexus skill run <name> -- args` passes args to the tool
+- `nexus skill use <name>` returns the guide
+- Tool execution happens directly (outside the CLI)
 - Verification runs the verify command
-- Gateway captures stdout/stderr/exit code
 
 ### 3.3 Script-Backed Skills
 
@@ -286,7 +286,8 @@ type ScriptSkillConfig = {
 ```
 
 **Characteristics:**
-- `nexus skill run <name> -- args` runs `runner script args`
+- `nexus skill use <name>` returns the guide
+- Script execution happens directly (outside the CLI)
 - Working directory is the skill folder
 - Requires both interpreter and env vars
 
@@ -540,11 +541,11 @@ 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 use <name>              # Return guide (logged)
 nexus skill stats [name]            # Usage statistics
 ```
 
-### 6.2 `nexus skill run` Flow
+### 6.2 `nexus skill use` Flow
 
 ```
 1. Load skill from manifest
@@ -929,7 +930,7 @@ See `docs/setup.md` for initial configuration.
 | **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 |
+| **Gateway pattern** | Guide access via `nexus skill use` 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 |

package/skills/{onboarding → guides/onboarding}/docs/SKILL_GATEWAY_DESIGN.md

@@ -12,9 +12,9 @@
 
 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
+2. **Wraps skill access** — Every guide retrieval is logged automatically
 3. **Tracks usage patterns** — Build "neural pathways" of what works
-4. **Simplifies agent instructions** — Just "use `nexus skill run X`"
+4. **Simplifies agent instructions** — Just "use `nexus skill use X`"
 
 This solves both hard problems:
 - **Problem 1 (Tracking State)**: Automatic via usage logging + execution gating
@@ -50,8 +50,8 @@ nexus skills path                             # Existing
 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
+# Skill access (NEW - THE GATEWAY)
+nexus skill use <name>               # Return SKILL.md guide
 
 # Usage statistics (NEW)
 nexus skill stats [name]             # Usage statistics (all or per-skill)
@@ -172,7 +172,7 @@ To configure this skill:
 
 ---
 
-### `nexus skill run <name> [-- args]`
+### `nexus skill use <name>`
 
 **Purpose**: The gateway. Execute a skill's tool or return its prompt.
 
@@ -180,7 +180,7 @@ To configure this skill:
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
-│ nexus skill run <name> [-- args]                                │
+│ nexus skill use <name>                                           │
 ├─────────────────────────────────────────────────────────────────┤
 │                                                                 │
 │  1. Load skill metadata                                         │
@@ -476,7 +476,7 @@ NEXUS SKILLS (47 total)
    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.
+Run 'nexus skill use <name>' to read a skill guide.
 ```
 
 **New Flags**:
@@ -492,7 +492,7 @@ Run 'nexus skill run <name>' to use a skill.
 
 1. **`src/cli/skills-cli.ts`**
    - Add `skill show <name>` subcommand
-   - Add `skill run <name>` subcommand  
+   - Add `skill use <name>` subcommand  
    - Add `skill verify <name>` subcommand
    - Add `skill stats` subcommand
    - Enhance `skills list` with status indicators
@@ -543,7 +543,7 @@ nexus skills list --ready
 nexus skill show <name>
 
 # Use a skill
-nexus skill run <name> [-- arguments]
+nexus skill use <name>
 ```
 
 If a skill isn't configured, the CLI will tell you what's needed.
@@ -558,7 +558,7 @@ If a skill isn't configured, the CLI will tell you what's needed.
 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`.
+That's the entire protocol. Everything else flows through `nexus skill use`.
 
 ---
 
@@ -581,7 +581,7 @@ nexus skills list --ready
 nexus skill show <skill-name>
 
 # Run a skill
-nexus skill run <skill-name> [-- args]
+nexus skill use <skill-name>
 ```
 
 The CLI will handle verification and logging automatically.
@@ -614,7 +614,7 @@ The existing infrastructure already symlinks skills to where Cursor can find the
 ### 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`
+- [ ] `nexus skill use <name>` in `skills-cli.ts`
   - [ ] Pure prompt handling
   - [ ] Tool execution with capture
   - [ ] First-run verification
@@ -657,7 +657,7 @@ The existing infrastructure already symlinks skills to where Cursor can find the
 
 ## Open Questions
 
-### 1. Should `skill run` capture stderr separately?
+### 1. Should `skill use` log access separately?
 
 **Current design**: Combined output (stdout + stderr to stdout)
 **Alternative**: Keep them separate, let agent see both
@@ -690,11 +690,11 @@ Example: `gog` is also known as `google`, `gmail`, etc.
 
 The gateway is successful when:
 
-1. ✅ `nexus skill run gog -- gmail messages list` executes and logs
-2. ✅ `nexus skill run filesystem` returns the prompt
+1. ✅ `nexus skill use gog` returns the guide and logs
+2. ✅ `nexus skill use 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
+5. ✅ Agent can use skills with only "nexus skill use" instructions
 6. ✅ Cursor integration works via cursor-rules
 
 ---

package/skills/{onboarding → guides/onboarding}/docs/SKILL_GATEWAY_PRD.md

@@ -13,9 +13,9 @@
 
 ## TL;DR
 
-Build a CLI gateway (`nexus skill *`) that wraps all skill execution, providing automatic usage tracking, state management, and gated discovery. This solves the "two hard problems" of onboarding: tracking state and injecting state into the agent.
+Build a CLI gateway (`nexus skill *`) that wraps skill access (guide retrieval), providing automatic usage tracking, state management, and gated discovery. This solves the "two hard problems" of onboarding: tracking state and injecting state into the agent.
 
-**Key Insight**: Instead of asking agents to report usage (unreliable), we make them execute through the gateway (automatic). The gateway becomes the single source of truth for what skills exist, which are ready, and how they're being used.
+**Key Insight**: Instead of asking agents to report usage (unreliable), we make them retrieve guides through the gateway (automatic). The gateway becomes the single source of truth for what skills exist, which are ready, and how they're being used.
 
 ---
 
@@ -25,7 +25,7 @@ Build a CLI gateway (`nexus skill *`) that wraps all skill execution, providing
 2. **Gated Discovery** — Only show skills that are ready to use
 3. **Verification on First Run** — Trust but verify, then cache the result
 4. **Observable Skill Health** — Know which skills work, which fail, usage patterns
-5. **Simple Agent Instructions** — Agent just needs to know `nexus skill run <name>`
+5. **Simple Agent Instructions** — Agent just needs to know `nexus skill use <name>`
 
 ---
 
@@ -57,7 +57,7 @@ See: [SKILL_GATEWAY_DESIGN.md](./SKILL_GATEWAY_DESIGN.md) for complete technical
 nexus skills list [--ready] [--locked]  # List skills with status
 nexus skill show <name>                  # Show skill details + prompt
 nexus skill verify <name>                # Check if skill is configured
-nexus skill run <name> [args...]         # Execute skill (logged)
+nexus skill use <name>                   # Return guide (logged)
 nexus skill stats [name]                 # Usage statistics
 nexus status                             # Quick status overview
 ```
@@ -102,10 +102,8 @@ nexus status                             # Quick status overview
   - Update per-skill state.json with result
   - Output: success/failure with details
 
-- [x] **2.3** `nexus skill run <name> [args...]` command
-  - Check if skill is prompt-only vs tool-based
-  - For tools: execute with arg passthrough
-  - Capture timing, exit code, stderr
+- [x] **2.3** `nexus skill use <name>` command
+  - Return SKILL.md content
   - Log to per-skill usage.log
   - Update per-skill state.json (lastUsed, etc.)
 
@@ -163,7 +161,7 @@ nexus status                             # Quick status overview
 
 There are skills in two locations that need reconciliation:
 - `~/nexus/skills/` (user's active skills)  
-- `~/nexus/home/projects/nexus/skills/` (core nexus repo)
+- `~/nexus/home/projects/nexus/nexus-cli/skills/` (core nexus repo)
 
 ### Tasks
 
@@ -234,14 +232,14 @@ filesystem, computer-use, weather, github, discord, coding-agent, gemini, model-
 | State file corruption | Atomic writes (write to tmp, rename) |
 | Log file grows unbounded | Prune to last 2000 entries / 2MB |
 | Gateway adds latency | Minimal overhead (just logging) |
-| Agent bypasses gateway | Agent instructions emphasize using `nexus skill run` |
+| Agent bypasses gateway | Agent instructions emphasize using `nexus skill use` |
 
 ---
 
 ## Success Criteria
 
 1. ✅ `nexus skills list --ready` shows only configured skills
-2. ✅ `nexus skill run gog gmail labels list` works and logs
+2. ✅ `nexus skill use gog` works and logs
 3. ✅ `nexus skill stats` shows usage patterns
 4. ✅ Agent can discover and use skills via gateway
 5. ✅ No manual reporting required from agent
@@ -260,7 +258,7 @@ filesystem, computer-use, weather, github, discord, coding-agent, gemini, model-
 
 ## Open Questions
 
-1. **Should failed verifications block `skill run`?**
+1. **Should failed verifications block `skill use`?**
    - Current plan: Warn but allow (user might know something we don't)
 
 2. **How to handle skills with multiple tools?**