claude-scope 1.0.1 → 1.1.0

package/.claude/skills/scope/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: scope
+description: Configure claude-scope status line widgets for Claude Code. Use when user wants to customize widgets, change theme, reorder elements, or modify display style.
+user-invocable: true
+allowed-tools: Read, Edit
+argument-hint: [configuration change in natural language]
+---
+
+# Claude Scope Configuration Skill
+
+Help users configure their claude-scope status line widgets.
+
+## Configuration Path
+
+**Config file:** `~/.claude-scope/config.json`
+
+## Workflow
+
+1. **Read** current config from `~/.claude-scope/config.json`
+2. **Understand** what the user wants to change
+3. **Edit** the config using the Edit tool
+4. **Confirm** changes to the user
+
+Changes apply automatically on the next status line render cycle.
+
+## Quick Reference
+
+### Config Structure
+
+```json
+{
+  "version": "1.0.0",
+  "theme": "monokai",
+  "lines": {
+    "0": [{ "id": "model", "style": "balanced", "colors": {...} }],
+    "1": [{ "id": "git", "style": "balanced", "colors": {...} }]
+  }
+}
+```
+
+- `lines` is an object where keys are line numbers ("0", "1", "2", etc.)
+- Each line contains an array of widget configurations
+- Widgets render left-to-right within each line
+- Empty lines should be empty arrays `[]`
+
+### Available Widgets (16)
+
+| Widget ID | Description | Typical Line |
+|-----------|-------------|--------------|
+| `cwd` | Current working directory | 0 |
+| `model` | Claude model name (e.g., "Claude Opus 4.5") | 0 |
+| `context` | Context window usage with progress bar | 0 |
+| `cost` | Session cost in USD | 0 |
+| `duration` | Session elapsed time | 0 |
+| `lines` | Lines added/removed during session | 0 |
+| `git` | Current git branch and changes | 1 |
+| `git-tag` | Latest git tag | 1 |
+| `config-count` | CLAUDE.md, rules, MCPs, hooks counts | 1 |
+| `cache-metrics` | Cache hit rate and cost savings | 1 |
+| `active-tools` | Running and completed Claude tools | 2 |
+| `dev-server` | Dev server status (Nuxt, Next, Vite) | 2 |
+| `docker` | Docker container count and status | 2 |
+| `sysmon` | System metrics (CPU, RAM, Disk, Network) | 3 |
+| `poker` | Random poker hand (easter egg) | 4 |
+| `empty-line` | Blank separator line | any |
+
+### Available Themes (17)
+
+`monokai` (default), `nord`, `dracula`, `catppuccin-mocha`, `tokyo-night`,
+`vscode-dark-plus`, `github-dark-dimmed`, `dusty-sage`, `muted-gray`,
+`slate-blue`, `professional-blue`, `rose-pine`, `semantic-classic`,
+`solarized-dark`, `one-dark-pro`, `cyberpunk-neon`, `gray`
+
+### Available Styles
+
+| Style | Description |
+|-------|-------------|
+| `balanced` | Clean, balanced with labels (default) |
+| `compact` | Minimal, condensed |
+| `playful` | Fun with emojis |
+| `verbose` | Full text labels |
+| `technical` | Raw values, no formatting |
+| `labeled` | Explicit prefix labels |
+| `minimal` | Most compact, no labels |
+
+## Common Operations
+
+### Swap widgets within a line
+
+Read config, change the order of widget objects in the line's array.
+
+**Example:** Swap model and context on line 0:
+```json
+// Before
+"0": [{ "id": "model", ... }, { "id": "context", ... }]
+// After
+"0": [{ "id": "context", ... }, { "id": "model", ... }]
+```
+
+### Swap entire lines
+
+Exchange the arrays between two line keys.
+
+**Example:** Swap line 0 and line 1 contents.
+
+### Add a widget
+
+Add a widget object to the target line array. Use existing widgets in config as template for the `colors` field.
+
+**Example:** Add docker widget to line 2:
+```json
+{ "id": "docker", "style": "balanced", "colors": { "label": "...", "count": "...", "running": "...", "stopped": "..." } }
+```
+
+### Remove a widget
+
+Remove the widget object from the line array. Don't leave empty objects.
+
+### Move widget to different line
+
+1. Remove widget object from source line
+2. Add widget object to target line
+
+### Change theme
+
+Update the `"theme"` field value.
+
+**Important:** Changing theme also requires updating all `colors` fields in every widget.
+**Recommendation:** For full theme changes, suggest user run:
+```bash
+npx claude-scope quick-config
+```
+This provides an interactive menu with live preview.
+
+### Change widget style
+
+Update the `"style"` field for the target widget.
+
+### Change all styles at once
+
+Update `"style"` field for every widget in config to the same value.
+
+## Full Documentation
+
+For detailed information about widgets, styles, colors, and themes, read the full documentation:
+
+- **Main reference:** AI-CONFIG-GUIDE.md in claude-scope repository
+- **All widgets with examples:** docs/WIDGETS.md
+- **Theme system:** docs/THEME-SYSTEM.md
+- **Architecture:** docs/ARCHITECTURE.md
+
+## Important Rules
+
+1. **Never break JSON structure** - validate before saving
+2. **Preserve required fields** - keep `version` and `$aiDocs` fields
+3. **Empty lines must be `[]`** - don't remove line keys, use empty arrays
+4. **ANSI color format** - colors use `\u001b[38;2;R;G;Bm` escape codes
+5. **Use existing colors as template** - when adding widgets, copy colors from similar existing widgets
+
+## Example User Requests
+
+| User says | Action |
+|-----------|--------|
+| "Swap first and second line" | Exchange lines "0" and "1" arrays |
+| "Add docker widget" | Add docker widget to appropriate line |
+| "Remove cost widget" | Remove cost widget from its line |
+| "Make everything compact" | Change all widget styles to "compact" |
+| "Use Dracula theme" | Update theme field (suggest quick-config for colors) |
+| "Move git to first line" | Remove git from current line, add to line 0 |
+| "Show current config" | Read and display the config file |

package/README.md

@@ -130,24 +130,37 @@ npx -y claude-scope@latest quick-config
 
 ## ⚙️ Configuration
 
-### 🤖 AI-Powered Customization
+### 🤖 /scope — AI-Powered Configuration
 
-**claude-scope is built to work with AI!** Just ask Claude:
+**claude-scope** includes a built-in Claude Code skill for effortless configuration. Just type `/scope` or ask naturally:
 
+<div align="center">
+  <img src="assets/scope-skill.png" alt="/scope skill demo" width="600"/>
+  <br/>
+  <sub>Configure widgets with natural language — no manual editing needed</sub>
+</div>
+
+<br/>
+
+**Use the `/scope` command:**
+```
+/scope swap line 0 and line 1
+/scope add docker widget to line 2
+/scope change theme to dracula
+/scope make all widgets compact
+```
+
+**Or just ask Claude naturally:**
 ```
-"Add the docker widget to line 3"
-"Switch theme to nord"
-"Make it more playful"
-"Show only model and context"
-"Add system monitoring"
+"Move git widget to the first line"
+"Switch to nord theme"
+"Show me current config"
+"Remove the cost widget"
 ```
 
-Claude automatically edits `~/.claude-scope/config.json` — changes take effect instantly.
+The skill is installed automatically with the package — no setup required!
 
-**How it works:**
-- Config contains `$aiDocs` field linking to [AI-CONFIG-GUIDE.md](AI-CONFIG-GUIDE.md)
-- AI understands all 15 widgets, 12 styles, and 17 themes
-- Natural language → instant configuration
+Changes apply instantly on the next status line update.
 
 ### 📝 Manual Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-scope",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Claude Code plugin for session status and analytics",
   "license": "MIT",
   "type": "module",
@@ -10,10 +10,13 @@
   },
   "files": [
     "dist/claude-scope.cjs",
+    ".claude/skills/",
+    "scripts/install-skill.sh",
     "README.md",
     "LICENSE.md"
   ],
   "scripts": {
+    "postinstall": "bash scripts/install-skill.sh 2>/dev/null || true",
     "prepack": "npm run build",
     "build": "npm run build:tsc && npm run build:bundle",
     "build:tsc": "tsc",

package/scripts/install-skill.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+# Install claude-scope skill to user's Claude Code skills directory
+# This script runs automatically via npm postinstall hook
+
+set -e
+
+SKILL_NAME="scope"
+TARGET_DIR="$HOME/.claude/skills/$SKILL_NAME"
+
+# Determine source directory (relative to this script's location)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SOURCE_DIR="$SCRIPT_DIR/../.claude/skills/$SKILL_NAME"
+
+# Gracefully skip if source doesn't exist (e.g., during development)
+if [ ! -d "$SOURCE_DIR" ]; then
+  echo "Note: Skill source not found at $SOURCE_DIR"
+  echo "Skipping skill installation (this is normal during development)."
+  exit 0
+fi
+
+# Check if SKILL.md exists in source
+if [ ! -f "$SOURCE_DIR/SKILL.md" ]; then
+  echo "Note: SKILL.md not found in $SOURCE_DIR"
+  echo "Skipping skill installation."
+  exit 0
+fi
+
+# Create target directory (overwrites existing if present)
+echo "Installing claude-scope skill..."
+mkdir -p "$TARGET_DIR"
+
+# Copy all skill files
+cp -r "$SOURCE_DIR"/* "$TARGET_DIR/"
+
+echo "✓ Skill installed to $TARGET_DIR"
+echo "  Use /scope in Claude Code to configure widgets"
+echo "  Or just ask Claude about widget configuration - it will understand!"