# Skills Documentation Analysis for The Grid

**Document Analyzed:** `/Users/jacweath/grid/docs/claude-code-reference/04-skills.md`
**Analysis Date:** 2026-01-23
**Grid Version:** 1.7.x

---

## Executive Summary

The Claude Code Skills system represents a significant evolution in how Claude can be extended with custom capabilities. The Grid currently implements its commands using the legacy `~/.claude/commands/` structure, but Claude Code has unified commands and skills into a single system. This analysis identifies **12 key opportunities** for The Grid to leverage skills features it currently does not use, potentially improving performance, user experience, and architectural clarity.

**Key Finding:** The Grid is underutilizing the skills system. While Grid commands work (since commands map to skills), several powerful frontmatter options and architectural patterns are not being leveraged.

---

## 1. Skills vs Commands: What Grid Needs to Know

### Current Grid Architecture
```
~/.claude/commands/grid/
├── quick.md
├── mc.md
├── status.md
├── debug.md
├── refine.md
├── model.md
├── branch.md
├── budget.md
├── daemon.md
├── help.md
├── init.md
├── program_disc.md
├── resume.md
├── update.md
└── README.md
```

### Skills Architecture (Recommended Migration)
```
~/.claude/skills/grid/
├── SKILL.md              # Main Grid entry point
├── quick/
│   └── SKILL.md
├── mc/
│   └── SKILL.md
├── status/
│   └── SKILL.md
├── debug/
│   ├── SKILL.md
│   ├── templates/
│   │   └── session-template.md
│   └── scripts/
│       └── create-session.sh
└── refine/
    ├── SKILL.md
    ├── templates/
    │   └── persona-template.yaml
    └── examples/
        └── refinement-plan.md
```

### Key Difference: Directory Structure

| Aspect | Commands (Current) | Skills (Recommended) |
|--------|-------------------|---------------------|
| File location | Single `.md` file | Directory with `SKILL.md` + assets |
| Supporting files | None | Templates, examples, scripts |
| Organization | Flat | Hierarchical |

**Opportunity:** Skills allow bundling templates, examples, and scripts with each command. Grid's debug, refine, and quick commands could benefit from bundled assets.

---

## 2. Frontmatter Features Grid Is NOT Using

### Currently Used by Grid
```yaml
---
name: grid:quick
description: Execute ad-hoc tasks without full planning ceremony
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Task
  - AskUserQuestion
---
```

### Available but UNUSED

#### 2.1 `context: fork` (HIGH PRIORITY)
```yaml
---
name: grid:refine
context: fork
agent: Explore
---
```

**What it does:** Runs the skill in a forked subagent context with a fresh context window.

**Grid Impact:**
- `/grid:mc` explicitly manages spawning via Task() - but `context: fork` could do this automatically
- `/grid:debug` spawns Debugger agents manually - could use fork
- `/grid:refine` spawns multiple inspectors - each could be a forked skill

**Opportunity:** Reduce MC's orchestration overhead by using native fork behavior.

#### 2.2 `disable-model-invocation: true` (MEDIUM PRIORITY)
```yaml
---
name: grid:mc
disable-model-invocation: true
---
```

**What it does:** Prevents Claude from automatically loading this skill. User must invoke explicitly.

**Grid Impact:**
- `/grid:mc` should ONLY run when explicitly invoked
- `/grid:daemon` should ONLY run when explicitly invoked
- `/grid:update` should NEVER auto-trigger

**Current Risk:** Claude might try to auto-invoke Grid commands based on description matching, potentially causing unwanted behavior.

**Recommended Commands for `disable-model-invocation: true`:**
- `grid:mc` (central orchestrator - user must choose)
- `grid:daemon` (background mode - explicit only)
- `grid:update` (destructive npm publish - explicit only)
- `grid:init` (creates directories - explicit only)

#### 2.3 `user-invocable: false` (MEDIUM PRIORITY)
```yaml
---
name: grid:internal-spawn-planner
user-invocable: false
---
```

**What it does:** Hides skill from `/` menu but Claude can still use it internally.

**Grid Impact:** Grid has internal operations that shouldn't be user-visible:
- Internal planner spawning logic
- Internal recognizer verification
- Wave execution orchestration

**Opportunity:** Create internal-only skills for Grid's agent spawning patterns that Claude can use but users don't see cluttering the menu.

#### 2.4 `argument-hint` (LOW PRIORITY)
```yaml
---
name: grid:debug
argument-hint: "[bug description]"
---
```

**What it does:** Shows hint during autocomplete.

**Grid Impact:** Improves discoverability:
- `/grid:quick` -> `[task description]`
- `/grid:debug` -> `[bug description]`
- `/grid:refine` -> `[visual|e2e|personas]`
- `/grid:model` -> `[quality|balanced|budget|custom]`

#### 2.5 `model` (HIGH PRIORITY)
```yaml
---
name: grid:quick
model: claude-sonnet-4-20250514
---
```

**What it does:** Specifies which model to use when skill is active.

**Grid Impact:**
- `/grid:model` currently writes to `.grid/config.json` and MC reads it
- Native `model` frontmatter could handle this automatically
- Different Grid commands could default to different models

**Opportunity:** Simplify model routing by using native skill model selection.

#### 2.6 `agent` (HIGH PRIORITY)
```yaml
---
name: grid:refine
context: fork
agent: grid-visual-inspector
---
```

**What it does:** Specifies which subagent configuration to use when `context: fork` is set.

**Grid Impact:**
- Grid agents are in `~/.claude/agents/grid-*.md`
- Native `agent` field could reference these directly
- Eliminates need for MC to read and inline agent content

**Opportunity:** Direct agent references instead of manual file reading.

#### 2.7 `hooks` (EXPLORATORY)
```yaml
---
name: grid:debug
hooks:
  pre-run:
    command: "mkdir -p .grid/debug"
  post-run:
    command: "echo 'Debug session complete'"
---
```

**What it does:** Hooks scoped to skill lifecycle.

**Grid Impact:**
- `/grid:init` does setup manually
- `/grid:debug` creates session directories
- Hooks could automate pre/post operations

---

## 3. Context Handling: The Fork Pattern

### Current Grid Pattern
```python
# In mc.md - MC reads agent file and inlines it
PLANNER_AGENT = read("~/.claude/agents/grid-planner.md")

Task(
  prompt=f"""
{PLANNER_AGENT}

<context>
{inlined_context}
</context>

Execute the plan.
""",
  subagent_type="general-purpose",
  description="Planner"
)
```

### Skills Fork Pattern
```yaml
---
name: grid:plan
context: fork
agent: grid-planner
allowed-tools: Read, Grep, Glob
---

Plan the user's request: $ARGUMENTS
```

**Key Insight:** With `context: fork` and `agent`, the skill system handles:
1. Creating a fresh context window
2. Loading the agent configuration
3. Running in isolation
4. Returning results to parent

**Grid Benefit:** MC could become thinner. Instead of manually orchestrating spawns, MC could invoke Grid sub-skills that use native forking.

### Architecture Proposal: Skill-Based Spawning

```
User: /grid "build a blog"
  │
  └─> /grid (MC skill)
        │
        ├─> /grid:internal-plan (forked, agent: grid-planner)
        │     └─> Returns plan
        │
        ├─> /grid:internal-execute (forked, agent: grid-executor)
        │     └─> Returns completion
        │
        └─> /grid:internal-verify (forked, agent: grid-recognizer)
              └─> Returns verification
```

---

## 4. Invocation Patterns: Better Ways to Invoke Grid Capabilities

### Current: Namespace via Colon
```
/grid
/grid:quick
/grid:status
/grid:debug
```

**Verdict:** This is good. Keep it.

### Enhancement: Argument Substitution
```yaml
---
name: grid:debug
---

Debug session: $ARGUMENTS

$ARGUMENTS is replaced with everything after the command.
```

**Current Grid Pattern:**
```markdown
## USAGE

`/grid:debug "description of bug"`
```

**Improved Pattern:**
```yaml
---
name: grid:debug
argument-hint: "[bug description]"
---

Start debug investigation for: $ARGUMENTS
```

**Benefit:** Cleaner, more native argument handling.

### Enhancement: Dynamic Context Injection
```yaml
---
name: grid:status
---

## Current Grid State
!`cat .grid/STATE.md 2>/dev/null || echo "No active session"`

## Recent Activity
!`ls -la .grid/phases/ 2>/dev/null | head -10`
```

**What it does:** The `` !`command` `` syntax runs shell commands before the skill content is sent to Claude.

**Grid Impact:**
- `/grid:status` could pre-load state automatically
- `/grid:resume` could pre-load checkpoint data
- Reduces manual Read operations

### Enhancement: Session Variables
```yaml
---
name: grid:session-logger
---

Log activity to: .grid/logs/${CLAUDE_SESSION_ID}.log
```

**Grid Impact:** Could use for:
- Session-specific scratchpads
- Debug session continuity
- Cost tracking per session

---

## 5. User-Invocable vs System: Skill Visibility Controls

### Visibility Matrix

| Command | User Should See? | Claude Should Auto-Invoke? | Recommended Setting |
|---------|------------------|---------------------------|---------------------|
| `/grid` | Yes | No | `disable-model-invocation: true` |
| `/grid:quick` | Yes | Yes (when task is simple) | Default |
| `/grid:mc` | No (internal) | No | `user-invocable: false`, `disable-model-invocation: true` |
| `/grid:status` | Yes | Yes | Default |
| `/grid:debug` | Yes | Yes (when bug mentioned) | Default |
| `/grid:refine` | Yes | Yes (after build) | Default |
| `/grid:model` | Yes | No | `disable-model-invocation: true` |
| `/grid:budget` | Yes | No | `disable-model-invocation: true` |
| `/grid:daemon` | Yes | No | `disable-model-invocation: true` |
| `/grid:update` | Yes | No | `disable-model-invocation: true` |
| `/grid:init` | Yes | No | `disable-model-invocation: true` |
| `/grid:resume` | Yes | Yes (when resuming) | Default |
| `/grid:branch` | Yes | No | `disable-model-invocation: true` |
| `/grid:help` | Yes | Yes | Default |

### Internal-Only Skills (New)

These should be `user-invocable: false`:
- `grid:internal-spawn-planner`
- `grid:internal-spawn-executor`
- `grid:internal-spawn-recognizer`
- `grid:internal-spawn-visual`
- `grid:internal-spawn-e2e`

---

## Quick Wins (Implement This Week)

### 1. Add `disable-model-invocation: true` to Sensitive Commands
**Effort:** 5 minutes per file
**Impact:** Prevents accidental auto-invocation

Files to update:
- `/grid:mc`
- `/grid:daemon`
- `/grid:update`
- `/grid:init`
- `/grid:model`
- `/grid:budget`
- `/grid:branch`

### 2. Add `argument-hint` to All Commands
**Effort:** 2 minutes per file
**Impact:** Better autocomplete experience

```yaml
---
name: grid:quick
argument-hint: "[task description]"
---
```

### 3. Add Dynamic Context Injection to Status
**Effort:** 15 minutes
**Impact:** Status loads faster, less manual reading

```yaml
---
name: grid:status
---

## Grid State
!`cat .grid/STATE.md 2>/dev/null || echo "No active Grid session"`

## Active Phases
!`ls .grid/phases/ 2>/dev/null | head -5`
```

---

## Architecture Changes (Implement This Month)

### 1. Migrate to Skills Directory Structure

```
~/.claude/skills/grid/
├── SKILL.md                    # Main /grid entry
├── quick/SKILL.md
├── status/SKILL.md
├── debug/
│   ├── SKILL.md
│   └── templates/
│       └── session.md
├── refine/
│   ├── SKILL.md
│   ├── visual/SKILL.md         # context: fork, agent: grid-visual-inspector
│   ├── e2e/SKILL.md            # context: fork, agent: grid-e2e-exerciser
│   └── personas/SKILL.md       # context: fork, agent: grid-persona-simulator
└── internal/
    ├── spawn-planner/SKILL.md  # user-invocable: false
    ├── spawn-executor/SKILL.md
    └── spawn-recognizer/SKILL.md
```

**Benefit:** Cleaner organization, bundled assets, internal skills hidden from users.

### 2. Leverage Native Fork for Agent Spawning

**Current (mc.md):**
```python
PLANNER = read("~/.claude/agents/grid-planner.md")
Task(prompt=f"{PLANNER}\n\n{context}", ...)
```

**Proposed (using skills):**
```yaml
# ~/.claude/skills/grid/internal/spawn-planner/SKILL.md
---
name: grid:internal-spawn-planner
context: fork
agent: grid-planner
user-invocable: false
allowed-tools: Read, Grep, Glob, Write
---

$ARGUMENTS
```

MC then invokes:
```
/grid:internal-spawn-planner "Create plan for: {user_request}"
```

**Benefit:**
- MC doesn't need to read agent files
- Native context isolation
- Cleaner orchestration

### 3. Model Selection via Skill Frontmatter

**Current:** Write to `.grid/config.json`, MC reads it, passes to Task()

**Proposed:** Each skill declares its model preference

```yaml
# /grid:quick - fast execution, use Sonnet
---
name: grid:quick
model: claude-sonnet-4-20250514
---

# /grid:refine:visual - needs vision, use Opus
---
name: grid:refine:visual
model: claude-opus-4-5-20251101
context: fork
---
```

**Benefit:** Model selection is declarative, not imperative.

---

## Specific Recommendations

### For /grid:mc (Master Control)
```yaml
---
name: grid:mc
description: The Grid's Master Control - central orchestrator
disable-model-invocation: true
allowed-tools:
  - Read
  - Glob
  - Grep
  - Skill  # NEW: Can invoke other Grid skills
---
```

**Key Change:** Add `Skill` to allowed-tools so MC can invoke internal Grid skills instead of using Task().

### For /grid:quick
```yaml
---
name: grid:quick
description: Execute ad-hoc tasks without full planning ceremony
argument-hint: "[task description]"
model: claude-sonnet-4-20250514
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
---
```

**Key Changes:**
- Add `argument-hint`
- Add `model` for faster execution
- Remove `Task` (quick mode stays in context)

### For /grid:debug
```yaml
---
name: grid:debug
description: Start or resume a hypothesis-driven debug session
argument-hint: "[bug description | session-id]"
context: fork
agent: grid-debugger
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
---

## Session Context
!`ls -t .grid/debug/*.md 2>/dev/null | head -5`

Debug investigation: $ARGUMENTS
```

**Key Changes:**
- Add `context: fork` and `agent` for native debugger spawning
- Add dynamic context injection for recent sessions
- Add `argument-hint`

### For /grid:refine
```yaml
---
name: grid:refine
description: Run the Refinement Swarm - visual, E2E, and persona testing
argument-hint: "[visual|e2e|personas|all]"
allowed-tools:
  - Read
  - Skill  # To invoke sub-skills
---

# Sub-skills handle the actual work
# /grid:refine:visual (context: fork, agent: grid-visual-inspector)
# /grid:refine:e2e (context: fork, agent: grid-e2e-exerciser)
# /grid:refine:personas (context: fork, agent: grid-persona-simulator)
```

**Key Change:** Refine becomes an orchestrator that invokes forked sub-skills.

### For /grid:status
```yaml
---
name: grid:status
description: Show Grid state with TRON-themed visual progress display
argument-hint: ""
allowed-tools:
  - Read
  - Glob
  - Grep
---

## Current State
!`cat .grid/STATE.md 2>/dev/null || echo "NO_ACTIVE_SESSION"`

## Phase Progress
!`find .grid/phases -name "SUMMARY.md" 2>/dev/null | wc -l` complete
!`find .grid/phases -name "PLAN.md" 2>/dev/null | wc -l` total

Display status based on above context.
```

**Key Change:** Dynamic context injection pre-loads state before skill runs.

---

## Character Budget Consideration

From documentation:
> Skill descriptions are loaded into context with a character budget (default 15,000). Run `/context` to check for excluded skills.

**Grid Impact:**
- Grid has 15+ commands
- Each description consumes budget
- Long descriptions might cause exclusions

**Recommendations:**
1. Keep descriptions concise (under 100 chars)
2. Set `SLASH_COMMAND_TOOL_CHAR_BUDGET=30000` if needed
3. Use `disable-model-invocation: true` for internal skills (they don't consume description budget)

---

## Migration Path

### Phase 1: Quick Wins (1 day)
1. Add `disable-model-invocation: true` to sensitive commands
2. Add `argument-hint` to all commands
3. Add dynamic context injection to `/grid:status`

### Phase 2: Restructure (1 week)
1. Create skills directory structure
2. Migrate commands to skills format
3. Bundle templates/examples with relevant skills

### Phase 3: Native Forking (2 weeks)
1. Create internal fork skills for agent spawning
2. Update MC to use Skill tool instead of Task for spawning
3. Test parallel execution via skill invocation

### Phase 4: Model Integration (1 week)
1. Add `model` frontmatter to skills
2. Deprecate `.grid/config.json` model tier
3. Test model routing

---

## Conclusion

The Grid is well-architected but is missing several powerful features from the Claude Code Skills system:

| Feature | Current Grid Usage | Recommended Action |
|---------|-------------------|-------------------|
| `context: fork` | Not used (manual Task spawning) | Use for all agent spawning |
| `agent` | Not used | Reference Grid agents directly |
| `disable-model-invocation` | Not used | Add to 7+ sensitive commands |
| `user-invocable: false` | Not used | Create internal-only skills |
| `argument-hint` | Not used | Add to all commands |
| `model` | Manual config | Use native frontmatter |
| Dynamic injection `!` | Not used | Use for status/resume |
| Directory structure | Flat files | Migrate to skills structure |

**Priority Ranking:**
1. **HIGH:** `disable-model-invocation` (prevents bugs)
2. **HIGH:** `context: fork` + `agent` (cleaner architecture)
3. **MEDIUM:** `argument-hint` (better UX)
4. **MEDIUM:** Dynamic injection (faster status)
5. **LOW:** Directory migration (cleaner organization)
6. **LOW:** Model frontmatter (nice to have)

The Grid can become significantly more powerful and maintainable by adopting these native skills features.

End of Line.