@onlooker-community/ecosystem 0.2.1 → 0.3.1

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "ecosystem",
       "source": "./",
       "description": "Fill this out",
-      "version": "0.2.1",
+      "version": "0.3.1",
       "author": {
         "name": "Onlooker Community"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "TODO fill this out",
   "author": {
     "name": "Onlooker Community",

package/.github/workflows/release.yml

@@ -12,6 +12,7 @@ permissions:
   contents: write
   pull-requests: write
   issues: write
+  id-token: write
 
 jobs:
   release-please:
@@ -48,7 +49,8 @@ jobs:
       - name: Publish to npm
         if: ${{ steps.release.outputs.releases_created == 'true' }}
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_CONFIG_PROVENANCE: true
         run: |
+          npm install -g npm@latest
           npm ci
-          npm publish --access public
+          npm publish --access=public

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.2.1"
+  ".": "0.3.1"
 }

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.3.1](https://github.com/onlooker-community/ecosystem/compare/v0.3.0...v0.3.1) (2026-05-22)
+
+
+### Bug Fixes
+
+* **ci:** use HTTPS repository URL for npm provenance ([a7e8927](https://github.com/onlooker-community/ecosystem/commit/a7e89275c5a025a8afee009853265b717091f6ca))
+
+## [0.3.0](https://github.com/onlooker-community/ecosystem/compare/v0.2.1...v0.3.0) (2026-05-21)
+
+
+### Features
+
+* **hooks:** track skill usage via skill.invoked events ([23fff0f](https://github.com/onlooker-community/ecosystem/commit/23fff0f0bfad8ab91788d8c45a0457d099d2e870))
+
+
+### Chores
+
+* update GitHub Actions permissions to include id-token ([ca18e61](https://github.com/onlooker-community/ecosystem/commit/ca18e61571b173d1aa6e69cf9031d2daaae1ff72))
+* update npm publish configuration in release workflow ([261fa2d](https://github.com/onlooker-community/ecosystem/commit/261fa2d5c9d656ce74f52193be615b860bc78075))
+
 ## [0.2.1](https://github.com/onlooker-community/ecosystem/compare/v0.2.0...v0.2.1) (2026-05-21)
 
 

package/hooks/hooks.json

@@ -18,6 +18,26 @@
             "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/agent-spawn-tracker.sh"
           }
         ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/skill-usage-tracker.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptExpansion": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/skill-usage-tracker.sh"
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",
@@ -9,7 +9,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git:https://github.com/onlooker-community/ecosystem.git"
+    "url": "https://github.com/onlooker-community/ecosystem"
   },
   "homepage": "https://github.com/onlooker-community/ecosystem#readme",
   "bugs": {
@@ -19,7 +19,7 @@
     "onlooker-install": "install.sh"
   },
   "dependencies": {
-    "@onlooker-community/schema": "^1.3.0"
+    "@onlooker-community/schema": "^1.4.0"
   },
   "scripts": {
     "postinstall": "echo '\\n  onlooker-ecosystem installed!\\n  Run: npx onlooker-install typescript\\n  Docs: https://github.com/onlooker-community/ecosystem\\n'",

package/scripts/hooks/skill-usage-tracker.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Onlooker Skill Usage Tracker
+# Invoked by UserPromptExpansion (slash commands) and PreToolUse (matcher: Skill).
+#
+# Records canonical skill.invoked events to:
+#   ~/.onlooker/session-history/<session_id>.jsonl
+#   ~/.onlooker/logs/onlooker-events.jsonl
+#
+# Usage:
+#   echo "$INPUT" | skill-usage-tracker.sh
+
+set -uo pipefail # No -e: never block skill invocation
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/validate-path.sh"
+source "$SCRIPT_DIR/../lib/onlooker-schema.sh"
+source "$SCRIPT_DIR/../lib/tool-history.sh"
+source "$SCRIPT_DIR/../lib/skill-usage.sh"
+
+hook_register "skill-usage-tracker" "Skill Usage Tracker" "Records skill.invoked canonical events"
+
+INPUT=$(cat)
+
+HOOK_EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // "UserPromptExpansion"')
+hook_set_context "$INPUT" "$HOOK_EVENT"
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+turn_state_export "$SESSION_ID"
+
+# PreToolUse Skill hooks must approve the tool call
+if [[ "$HOOK_EVENT" == "PreToolUse" ]]; then
+	TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+	if [[ "$TOOL_NAME" != "Skill" ]]; then
+		hook_success
+		exit 0
+	fi
+fi
+
+RECORD=$(skill_usage_build_record "$INPUT")
+if [[ -n "$RECORD" ]]; then
+	skill_usage_append "$SESSION_ID" "$RECORD" || hook_failure "Failed to append session history"
+	onlooker_append_event "$RECORD" || hook_failure "Failed to append global event log"
+fi
+
+if [[ "$HOOK_EVENT" == "PreToolUse" ]]; then
+	SKILL_NAME=$(echo "$RECORD" | jq -r '.payload.skill_name // empty' 2>/dev/null)
+	jq -n --arg msg "Skill tracked${SKILL_NAME:+: $SKILL_NAME}" '{ "decision": "approve", "reason": $msg }'
+fi
+
+hook_success
+exit 0

package/scripts/lib/onlooker-event.mjs

@@ -8,6 +8,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import {
   createEvent,
+  SKILL_INVOKED,
   TOOL_AGENT_COMPLETE,
   TOOL_AGENT_SPAWN,
   TOOL_FILE_EDIT,
@@ -78,11 +79,80 @@ function extractPath(toolInput, toolResponse) {
   return toolInput?.file_path ?? toolInput?.path ?? toolResponse?.filePath ?? toolResponse?.path ?? undefined;
 }
 
+function stripUndefined(obj) {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined && v !== null && v !== ''));
+}
+
+function parseTurnNumber() {
+  const raw = process.env.ONLOOKER_TURN_NUMBER;
+  if (raw == null || raw === '') return undefined;
+  const n = Number.parseInt(String(raw), 10);
+  return Number.isFinite(n) && n >= 1 ? n : undefined;
+}
+
 /**
- * Map Claude Code PostToolUse / PostToolUseFailure hook input to a canonical event.
- * Returns null when the tool is not mapped to a schema event type.
+ * Map UserPromptExpansion or PreToolUse (Skill) hook input to skill.invoked.
+ * Returns null when the hook input is not a skill invocation.
+ */
+export function mapSkillHookInput(hookInput, options) {
+  const { onlookerDir, plugin, runtime = 'claude-code', adapter_id = 'ecosystem.hooks' } = options;
+  const hookEvent = hookInput?.hook_event_name;
+  const sessionId = hookInput?.session_id ?? 'unknown';
+
+  let payload;
+
+  if (hookEvent === 'UserPromptExpansion') {
+    const skillName = hookInput?.command_name;
+    if (!skillName) return null;
+    payload = stripUndefined({
+      skill_name: skillName,
+      invocation_source: 'slash_command',
+      command_args: hookInput?.command_args,
+      command_source: hookInput?.command_source,
+      expansion_type: hookInput?.expansion_type,
+      turn_number: parseTurnNumber(),
+    });
+  } else if (hookEvent === 'PreToolUse' && hookInput?.tool_name === 'Skill') {
+    const toolInput = hookInput?.tool_input ?? {};
+    const skillName =
+      toolInput.skill ?? toolInput.skill_name ?? toolInput.name ?? toolInput.command ?? toolInput.skill_id;
+    if (!skillName) return null;
+    const args = toolInput.args ?? toolInput.command_args;
+    payload = stripUndefined({
+      skill_name: String(skillName),
+      invocation_source: 'tool',
+      command_args: typeof args === 'string' ? args : args != null ? JSON.stringify(args) : undefined,
+      turn_number: parseTurnNumber(),
+    });
+  } else {
+    return null;
+  }
+
+  const event = buildCanonicalEvent({
+    onlookerDir,
+    runtime,
+    adapter_id,
+    plugin,
+    session_id: sessionId,
+    event_type: SKILL_INVOKED,
+    payload,
+  });
+
+  const result = validate(event);
+  if (!result.valid) {
+    return { valid: false, errors: result.errors, event_type: SKILL_INVOKED };
+  }
+  return { valid: true, event: result.event };
+}
+
+/**
+ * Map Claude Code hook input to a canonical event.
+ * Returns null when the hook input is not mapped to a schema event type.
  */
 export function mapHookInputToCanonical(hookInput, options) {
+  const skillMapped = mapSkillHookInput(hookInput, options);
+  if (skillMapped) return skillMapped;
+
   const { onlookerDir, plugin, runtime = 'claude-code', adapter_id = 'ecosystem.hooks' } = options;
 
   const toolName = hookInput?.tool_name;

package/scripts/lib/onlooker-schema.sh

@@ -25,6 +25,7 @@ onlooker_event_from_hook() {
 	fi
 
 	printf '%s' "$hook_input" | ONLOOKER_DIR="$ONLOOKER_DIR" ONLOOKER_PLUGIN_NAME="$ONLOOKER_PLUGIN_NAME" \
+		ONLOOKER_TURN_NUMBER="${ONLOOKER_TURN_NUMBER:-}" \
 		node "$_ONLOOKER_EVENT_JS" emit-from-hook 2>/dev/null
 }
 

package/scripts/lib/skill-usage.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Skill usage helpers — canonical session JSONL via @onlooker-community/schema.
+#
+# Source after validate-path.sh and onlooker-schema.sh:
+#   source "$CLAUDE_PLUGIN_ROOT/scripts/lib/validate-path.sh"
+#   source "$CLAUDE_PLUGIN_ROOT/scripts/lib/onlooker-schema.sh"
+#   source "$CLAUDE_PLUGIN_ROOT/scripts/lib/skill-usage.sh"
+#   source "$CLAUDE_PLUGIN_ROOT/scripts/lib/tool-history.sh"
+
+# Build a canonical skill.invoked event from hook stdin (empty when unmapped).
+# Usage: record=$(skill_usage_build_record "$INPUT")
+skill_usage_build_record() {
+	local input_json="${1:-}"
+	onlooker_event_from_hook "$input_json"
+}
+
+# Append a canonical skill event to session history (reuses tool-history flock).
+# Usage: skill_usage_append "$SESSION_ID" "$event_json"
+skill_usage_append() {
+	tool_history_append "$1" "$2"
+}

package/test/bats/config.bats

@@ -38,6 +38,29 @@ setup_file() {
   [ "$status" -eq 0 ]
 }
 
+@test "hooks.json Skill matcher references skill-usage-tracker" {
+  run jq -e '.hooks.PreToolUse[2].matcher == "Skill"' "${REPO_ROOT}/hooks/hooks.json"
+  [ "$status" -eq 0 ]
+
+  local hook_cmd
+  hook_cmd=$(jq -r '.hooks.PreToolUse[2].hooks[0].command' "${REPO_ROOT}/hooks/hooks.json")
+  [[ "$hook_cmd" == *skill-usage-tracker.sh ]]
+
+  local script_path="${hook_cmd//\$CLAUDE_PLUGIN_ROOT/$REPO_ROOT}"
+  script_path="${script_path//\"/}"
+  run test -x "$script_path"
+  [ "$status" -eq 0 ]
+}
+
+@test "hooks.json UserPromptExpansion references skill-usage-tracker" {
+  run jq -e '.hooks.UserPromptExpansion[0].matcher == ""' "${REPO_ROOT}/hooks/hooks.json"
+  [ "$status" -eq 0 ]
+
+  local hook_cmd
+  hook_cmd=$(jq -r '.hooks.UserPromptExpansion[0].hooks[0].command' "${REPO_ROOT}/hooks/hooks.json")
+  [[ "$hook_cmd" == *skill-usage-tracker.sh ]]
+}
+
 @test "hooks.json PostToolUse references tool-history-tracker" {
   run jq -e '.hooks.PostToolUse[0].matcher == "*"' "${REPO_ROOT}/hooks/hooks.json"
   [ "$status" -eq 0 ]

package/test/bats/skill-usage-tracker.bats

@@ -0,0 +1,76 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  load_validate_path
+  # shellcheck source=../../scripts/lib/onlooker-schema.sh
+  source "${REPO_ROOT}/scripts/lib/onlooker-schema.sh"
+  # shellcheck source=../../scripts/lib/tool-history.sh
+  source "${REPO_ROOT}/scripts/lib/tool-history.sh"
+  # shellcheck source=../../scripts/lib/skill-usage.sh
+  source "${REPO_ROOT}/scripts/lib/skill-usage.sh"
+  export CLAUDE_PLUGIN_ROOT="${REPO_ROOT}"
+}
+
+@test "skill_usage_build_record maps UserPromptExpansion to skill.invoked" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/user-prompt-expansion-skill.json"
+  local record
+  record=$(skill_usage_build_record "$(cat "$fixture")")
+  echo "$record" | jq -e \
+    '.schema_version == "1.0"
+     and .event_type == "skill.invoked"
+     and .payload.skill_name == "code-review"
+     and .payload.invocation_source == "slash_command"
+     and .payload.command_args == "src/main.ts"
+     and .payload.expansion_type == "slash_command"
+     and .session_id == "skill-session-001"' \
+    >/dev/null
+  echo "$record" | onlooker_validate_event
+}
+
+@test "skill_usage_build_record maps PreToolUse Skill to skill.invoked" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/pre-tool-use-skill.json"
+  local record
+  record=$(skill_usage_build_record "$(cat "$fixture")")
+  echo "$record" | jq -e \
+    '.event_type == "skill.invoked"
+     and .payload.skill_name == "code-review"
+     and .payload.invocation_source == "tool"
+     and .payload.command_args == "src/main.ts"' \
+    >/dev/null
+  echo "$record" | onlooker_validate_event
+}
+
+@test "skill-usage-tracker appends slash command skill to session JSONL" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/user-prompt-expansion-skill.json"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/skill-session-001.jsonl"
+  rm -f "$history_file" "${history_file}.lock"
+
+  run bash -c "cat '${fixture}' | '${REPO_ROOT}/scripts/hooks/skill-usage-tracker.sh' 2>/dev/null"
+  [ "$status" -eq 0 ]
+  [ -f "$history_file" ]
+  tail -n 1 "$history_file" | jq -e '.event_type == "skill.invoked"' >/dev/null
+  tail -n 1 "$history_file" | onlooker_validate_event
+}
+
+@test "skill-usage-tracker approves PreToolUse Skill and records event" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/pre-tool-use-skill.json"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/skill-session-001.jsonl"
+  rm -f "$history_file" "${history_file}.lock"
+
+  run bash -c "cat '${fixture}' | '${REPO_ROOT}/scripts/hooks/skill-usage-tracker.sh' 2>/dev/null"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.decision == "approve"' >/dev/null
+  tail -n 1 "$history_file" | jq -e '.payload.invocation_source == "tool"' >/dev/null
+}
+
+@test "skill-usage-tracker mirrors skill.invoked to global events log" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/user-prompt-expansion-skill.json"
+  : >"$ONLOOKER_EVENTS_LOG"
+
+  cat "$fixture" | "${REPO_ROOT}/scripts/hooks/skill-usage-tracker.sh" >/dev/null 2>&1
+
+  tail -n 1 "$ONLOOKER_EVENTS_LOG" | jq -e '.event_type == "skill.invoked"' >/dev/null
+  tail -n 1 "$ONLOOKER_EVENTS_LOG" | onlooker_validate_event
+}

package/test/fixtures/hook-inputs/pre-tool-use-skill.json

@@ -0,0 +1,11 @@
+{
+  "session_id": "skill-session-001",
+  "cwd": "/project",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Skill",
+  "tool_use_id": "skill-use-001",
+  "tool_input": {
+    "skill": "code-review",
+    "args": "src/main.ts"
+  }
+}

package/test/fixtures/hook-inputs/user-prompt-expansion-skill.json

@@ -0,0 +1,10 @@
+{
+  "session_id": "skill-session-001",
+  "cwd": "/project",
+  "hook_event_name": "UserPromptExpansion",
+  "expansion_type": "slash_command",
+  "command_name": "code-review",
+  "command_args": "src/main.ts",
+  "command_source": "plugin",
+  "prompt": "/code-review src/main.ts"
+}

package/test/node/schema-events.test.mjs

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import { test } from 'node:test';
 import { fileURLToPath } from 'node:url';
 import { validate } from '@onlooker-community/schema';
-import { buildCanonicalEvent, mapHookInputToCanonical } from '../../scripts/lib/onlooker-event.mjs';
+import { buildCanonicalEvent, mapHookInputToCanonical, mapSkillHookInput } from '../../scripts/lib/onlooker-event.mjs';
 
 const REPO_ROOT = join(fileURLToPath(new URL('../..', import.meta.url)));
 const FIXTURES = join(REPO_ROOT, 'test/fixtures/hook-inputs');
@@ -44,6 +44,34 @@ test('mapHookInputToCanonical maps PostToolUseFailure Bash to tool.shell.exec',
   assert.equal(validate(mapped.event).valid, true);
 });
 
+test('mapSkillHookInput maps UserPromptExpansion to skill.invoked', () => {
+  const hookInput = loadFixture('user-prompt-expansion-skill.json');
+  const tmpDir = join(REPO_ROOT, 'test/tmp-schema-events');
+  const mapped = mapSkillHookInput(hookInput, {
+    onlookerDir: tmpDir,
+    plugin: 'onlooker',
+  });
+
+  assert.equal(mapped.valid, true);
+  assert.equal(mapped.event.event_type, 'skill.invoked');
+  assert.equal(mapped.event.payload.skill_name, 'code-review');
+  assert.equal(mapped.event.payload.invocation_source, 'slash_command');
+  assert.equal(validate(mapped.event).valid, true);
+});
+
+test('mapSkillHookInput maps PreToolUse Skill to skill.invoked', () => {
+  const hookInput = loadFixture('pre-tool-use-skill.json');
+  const tmpDir = join(REPO_ROOT, 'test/tmp-schema-events');
+  const mapped = mapSkillHookInput(hookInput, {
+    onlookerDir: tmpDir,
+    plugin: 'onlooker',
+  });
+
+  assert.equal(mapped.valid, true);
+  assert.equal(mapped.event.payload.invocation_source, 'tool');
+  assert.equal(validate(mapped.event).valid, true);
+});
+
 test('buildCanonicalEvent assigns monotonic file-backed sequence', () => {
   const tmpDir = mkdtempSync(join(tmpdir(), 'onlooker-seq-'));
   const a = buildCanonicalEvent({