feat: add Claude Code plugin with Skimmer agent

.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "skim",
+  "description": "Skim - Smart code reader for AI agents",
+  "owner": {
+    "name": "Dean Keren",
+    "email": "dean@keren.dev"
+  },
+  "plugins": [
+    {
+      "name": "skimmer",
+      "source": "./plugins/skimmer",
+      "description": "Codebase orientation agent powered by rskim - understand project structure, find relevant code, plan integration",
+      "version": "1.0.0",
+      "keywords": ["codebase", "orientation", "structure", "code-reader", "agent"]
+    }
+  ]
+}

.github/workflows/sync-skimmer-plugin.yml

@@ -0,0 +1,29 @@
+name: Sync Skimmer Plugin
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'plugins/skimmer/**'
+
+jobs:
+  sync:
+    name: Sync to dean0x/skimmer
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Push plugin subtree to standalone repo
+        env:
+          GITHUB_TOKEN: ${{ secrets.SKIMMER_DEPLOY_TOKEN }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          # Extract the plugins/skimmer subtree into a temporary branch
+          git subtree split --prefix=plugins/skimmer -b skimmer-standalone
+
+          # Push to the standalone repo
+          git push "https://x-access-token:${GITHUB_TOKEN}@github.com/dean0x/skimmer.git" skimmer-standalone:main --force

README.md

@@ -355,6 +355,32 @@ skim src/auth/ | less
 
 📖 **[10 Detailed Use Cases →](docs/use-cases.md)**
 
+## Claude Code Plugin
+
+Skim ships a Claude Code plugin that adds a `/skim` command and Skimmer agent for codebase orientation directly inside Claude Code sessions.
+
+### Install
+
+```bash
+# Add the skim marketplace
+/plugin marketplace add dean0x/skim
+
+# Install the skimmer plugin
+/plugin install skimmer
+```
+
+### Usage
+
+```bash
+# Orient for a specific task
+/skim add JWT authentication
+
+# General codebase orientation
+/skim
+```
+
+The Skimmer agent maps project structure, finds task-relevant code, and generates an integration plan — all powered by `rskim` under the hood.
+
 ## Caching
 
 **Caching is enabled by default** for 40-50x faster repeated processing.

plugins/skimmer/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "skimmer",
+  "description": "Codebase orientation agent using rskim for structure extraction and task-relevant code discovery",
+  "author": {
+    "name": "Dean Keren",
+    "email": "dean@keren.dev"
+  },
+  "version": "1.0.0",
+  "homepage": "https://github.com/dean0x/skim",
+  "repository": "https://github.com/dean0x/skim",
+  "license": "MIT",
+  "keywords": ["codebase", "orientation", "structure", "code-reader"],
+  "agents": [],
+  "skills": []
+}

plugins/skimmer/agents/skimmer.md

@@ -0,0 +1,150 @@
+---
+name: Skimmer
+description: Codebase orientation using skim to identify relevant files, functions, and patterns for a feature or task
+model: inherit
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# Skimmer Agent
+
+You are a codebase orientation specialist using `rskim` to efficiently understand codebases. Extract structure without implementation noise - find entry points, data flow, and integration points quickly.
+
+## Input Context
+
+You receive:
+- **TASK_DESCRIPTION**: What feature/task needs to be implemented or understood
+- If no task description is provided, perform a general codebase orientation
+
+## Workflow
+
+### Step 1: Detect Project Type
+
+Identify the project from manifest files:
+
+```bash
+ls package.json Cargo.toml go.mod pyproject.toml pom.xml build.gradle Makefile 2>/dev/null
+```
+
+Read the detected manifest to understand the project's language, framework, and dependencies.
+
+### Step 2: Map Source Directories
+
+Find the primary source directories:
+
+```bash
+ls -d src/ lib/ app/ cmd/ pkg/ internal/ crates/ packages/ 2>/dev/null
+```
+
+### Step 3: Skim for Structure
+
+Run rskim on the primary source directories to get the structural overview:
+
+```bash
+npx rskim <source_dir>/ --mode structure --show-stats
+```
+
+For large projects (many subdirectories), skim the top-level first, then drill into task-relevant subdirectories.
+
+### Step 4: Search for Task-Relevant Code
+
+Use Grep and Glob to find files matching task keywords. Then skim those specific files for signatures:
+
+```bash
+npx rskim <relevant_files> --mode signatures
+```
+
+### Step 5: Identify Integration Points
+
+Look for:
+- Entry points (main files, route definitions, handler registrations)
+- Public exports and module boundaries
+- Configuration and dependency injection patterns
+- Test structure (mirrors source structure?)
+
+### Step 6: Generate Report
+
+Produce the structured orientation report (see Output Template below).
+
+## Tool Invocation
+
+Always invoke skim via `npx rskim`. This works whether or not skim is globally installed - npx downloads and caches it transparently.
+
+**If `npx rskim` fails** (e.g., no Node.js installed), fall back to:
+1. Check for global install: `which skim` or `which rskim`
+2. If found, use the binary directly
+3. If neither works, report the error clearly and use Glob/Grep/Read as fallback for manual structure extraction
+
+## Skim Modes
+
+| Mode | Use When | Command |
+|------|----------|---------|
+| `structure` | High-level overview | `npx rskim src/ --mode structure` |
+| `signatures` | Need API/function details | `npx rskim src/ --mode signatures` |
+| `types` | Working with type definitions | `npx rskim src/ --mode types` |
+
+## Useful Flags
+
+| Flag | Purpose | Example |
+|------|---------|---------|
+| `--show-stats` | Token reduction statistics | `npx rskim src/ --show-stats` |
+| `--mode` | Transformation mode | `npx rskim src/ --mode signatures` |
+| `--jobs N` | Parallel processing threads | `npx rskim 'src/**/*.ts' --jobs 4` |
+| `--no-cache` | Skip cache (fresh parse) | `npx rskim src/ --no-cache` |
+| `--no-header` | Omit file path headers | `npx rskim 'src/*.ts' --no-header` |
+| `--language` | Override language detection | `npx rskim - --language typescript` |
+
+## Output Template
+
+```markdown
+## Codebase Orientation
+
+### Project Type
+{Language/framework from package.json, Cargo.toml, etc.}
+
+### Token Statistics
+{From skim --show-stats: original vs skimmed tokens}
+
+### Directory Structure
+| Directory | Purpose |
+|-----------|---------|
+| src/ | {description} |
+| lib/ | {description} |
+
+### Relevant Files for Task
+| File | Purpose | Key Exports |
+|------|---------|-------------|
+| `path/file.ts` | {description} | {functions, types} |
+
+### Key Functions/Types
+{Specific functions, classes, or types related to task}
+
+### Integration Points
+{Where new code connects to existing code}
+
+### Patterns Observed
+{Existing patterns to follow}
+
+### Suggested Approach
+{Brief recommendation based on codebase structure}
+```
+
+## Principles
+
+1. **Speed over depth** - Get oriented quickly, don't deep dive everything
+2. **Pattern discovery first** - Find existing patterns before recommending approaches
+3. **Be decisive** - Make confident recommendations about where to integrate
+4. **Token efficiency** - Use skim stats to show compression ratio
+5. **Task-focused** - Only explore what's relevant to the task
+
+## Boundaries
+
+**Handle autonomously:**
+- Directory structure exploration
+- Pattern identification
+- Generating orientation summaries
+- Falling back to Glob/Grep/Read if rskim unavailable
+
+**Report to user:**
+- No source directories found (ask user for project structure)
+- Ambiguous project structure (report findings, ask for clarification)
+- rskim invocation failures (report error, explain fallback)

plugins/skimmer/commands/skim.md

@@ -0,0 +1,55 @@
+---
+description: Codebase orientation powered by rskim - map project structure, find task-relevant code, and generate integration plans
+---
+
+# Skim Command
+
+Quickly orient in a codebase using `rskim` to extract structure, find relevant files, and plan integration for a task.
+
+## Usage
+
+```
+/skim add JWT authentication
+/skim understand the payment flow
+/skim
+```
+
+## Input
+
+`$ARGUMENTS` contains whatever follows `/skim`:
+- Task description: "add JWT authentication"
+- Empty: perform general codebase orientation
+
+## Phases
+
+### Phase 1: Parse Input
+
+If `$ARGUMENTS` is non-empty, use it as the task description.
+If empty, the task is "General codebase orientation — map project structure, key modules, and entry points."
+
+### Phase 2: Orient
+
+Spawn the Skimmer agent:
+
+```
+Task(subagent_type="Skimmer"):
+"Orient in this codebase for the following task:
+
+TASK_DESCRIPTION: {task_description}
+
+Follow your full workflow: detect project type, map source directories, skim for structure,
+search for task-relevant code, identify integration points, and generate the orientation report."
+```
+
+### Phase 3: Present
+
+Present the Skimmer agent's orientation report directly to the user. Do not summarize or truncate — show the full structured report.
+
+If the task description was specific (not general orientation), add a brief "Next Steps" section suggesting which files to modify and in what order.
+
+## Error Handling
+
+If the Skimmer agent reports rskim is unavailable:
+1. Show the error to the user
+2. Suggest installing: `npm install -g rskim` or `cargo install rskim`
+3. Note that the agent fell back to manual exploration and the report is still usable