rebuild-plugin

.gitignore

@@ -1,3 +1,5 @@
+node_modules/
 *.log
 .DS_Store
 .env
+dist/

CLAUDE.md

@@ -1,88 +1,66 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code when working with code in this repository.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 ## Project Overview
 
-SkillPulse is a Claude Code plugin that tracks skill usage analytics passively via hooks.
+SkillPulse is a Claude Code plugin that tracks skill usage analytics. It consists of:
+- **MCP Server** (`src/index.js`) — Exposes tools for logging and querying skill usage
+- **Pulse Skill** (`skills/pulse/`) — CLI interface for viewing usage statistics
+- **Analytics Storage** — `~/.claude/skills/pulse.jsonl` (JSONL format: `{"skill":"name","ts":1234567890,"outcome":"success"}`)
 
-**Cross-platform:** Works on Windows, macOS, and Linux.
+## Development Commands
 
-## Plugin Structure
+```bash
+# Run the MCP server (for testing)
+npm start
 
+# Run with file watching during development
+npm run dev
 ```
-skillpulse/
-├── .claude-plugin/
-│   └── plugin.json          # Plugin manifest
-├── hooks/
-│   └── hooks.json           # PostToolUse hook for passive tracking
-├── scripts/
-│   ├── track.js             # Hook script that logs skill usage (Node.js)
-│   ├── rotate.js            # Data rotation script
-│   ├── export.js            # Export script (JSON/CSV)
-│   └── reset.js             # Reset script
-├── skills/
-│   └── pulse/
-│       └── SKILL.md         # Skill that powers /skillpulse:pulse
-└── README.md
-```
-
-## How It Works
-
-### Passive Tracking (Hook)
 
-The `hooks/hooks.json` defines a `PostToolUse` hook that fires after every `Read` tool call.
+## Architecture
 
-`scripts/track.js` receives:
-- `CLAUDE_TOOL_INPUT` — JSON input of the Read tool (contains file path)
-- `CLAUDE_HUMAN_TURN` — Last user message (to detect explicit skill invocation)
-- `CLAUDE_PLUGIN_DATA` — Plugin's writable data directory
+### MCP Server (`src/index.js`)
+The server runs on stdio and exposes three tools:
 
-If the read file ends with `SKILL.md`, it logs the usage to `${CLAUDE_PLUGIN_DATA}/pulse.jsonl`.
+| Tool | Purpose |
+|------|---------|
+| `log_pulse` | Log skill usage to analytics file |
+| `get_skill_stats` | Query usage stats by period (24h/7d/30d/all) |
+| `list_skills` | Enumerate installed skills from `~/.claude/skills/` |
 
-### Analytics File Format
-
-```json
-{"skill":"careful","ts":1711234567,"trigger":"auto"}
-{"skill":"freeze","ts":1711234568,"trigger":"explicit"}
-```
+**Note:** There's a mismatch in the code: `tools/list` defines `log_pulse` but `tools/call` handles `log_skill_usage`. This should be unified.
 
-- `skill` — Name of the skill (directory name)
-- `ts` — Unix timestamp
-- `trigger` — "auto" (Claude loaded it) or "explicit" (user invoked via `/skill`)
+### Pulse Skill (`skills/pulse/`)
+- `SKILL.md` — Skill metadata and documentation
+- `skill.json` — Package metadata
+- `bin/pulse.sh` — Bash script that reads `pulse.jsonl` and renders ASCII stats
 
-### The Skill: /skillpulse:pulse
+### Plugin Manifest (`plugin.json`)
+Defines the MCP server and skill components for Claude Code to load.
 
-`skills/pulse/SKILL.md` is a user-invocable skill that:
-1. Reads `${CLAUDE_PLUGIN_DATA}/pulse.jsonl`
-2. Filters by time period (24h/7d/30d/all)
-3. Scans for all installed skills
-4. Outputs usage statistics with hot/cold breakdown
+## Analytics File Format
 
-## Testing Locally
+Stored at `~/.claude/skills/pulse.jsonl`:
 
-```bash
-claude --plugin-dir ./skillpulse
+```json
+{"skill":"careful","ts":1711234567,"outcome":"success","pid":12345}
+{"skill":"freeze","ts":1711234568,"outcome":"success","pid":12345}
 ```
 
-Then:
-1. Trigger a few skills (Claude will read their SKILL.md files)
-2. Run `/skillpulse:pulse` to verify data flows
+## Key Directories
 
-## Running Tests
+| Path | Purpose |
+|------|---------|
+| `src/` | MCP server implementation |
+| `skills/pulse/` | User-facing CLI skill |
+| `~/.claude/skills/` | Where Claude Code installs skills |
 
-```bash
-node --test scripts/*.test.js
-```
+## Skill Integration Pattern
 
-## Install Flow (for users)
+Other skills can self-track by appending to `pulse.jsonl`:
 
 ```bash
-/plugin install github:doanbactam/skillpulse
-```
-
-Then use:
-```
-/skillpulse:pulse
-/skillpulse:pulse 30d
+echo "{\"skill\":\"$(basename $0)\",\"ts\":$(date +%s)}" >> ~/.claude/skills/pulse.jsonl
 ```