{"id":49416138,"url":"https://github.com/revo1290/cc-skill-trace","last_synced_at":"2026-04-29T03:04:37.362Z","repository":{"id":351822173,"uuid":"1212646881","full_name":"revo1290/cc-skill-trace","owner":"revo1290","description":"Skill invocation debugger \u0026 visualizer for Claude Code — see which skills fired, when, and why","archived":false,"fork":false,"pushed_at":"2026-04-25T08:38:33.000Z","size":127,"stargazers_count":1,"open_issues_count":15,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T10:25:47.658Z","etag":null,"topics":["anthropic","claude","claude-code","skills"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/revo1290.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-16T15:31:52.000Z","updated_at":"2026-04-25T08:38:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/revo1290/cc-skill-trace","commit_stats":null,"previous_names":["revo1290/cc-skill-trace"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/revo1290/cc-skill-trace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revo1290%2Fcc-skill-trace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revo1290%2Fcc-skill-trace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revo1290%2Fcc-skill-trace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revo1290%2Fcc-skill-trace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/revo1290","download_url":"https://codeload.github.com/revo1290/cc-skill-trace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revo1290%2Fcc-skill-trace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32408447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T02:37:21.628Z","status":"ssl_error","status_checked_at":"2026-04-29T02:36:50.947Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","claude","claude-code","skills"],"created_at":"2026-04-29T03:04:36.784Z","updated_at":"2026-04-29T03:04:37.339Z","avatar_url":"https://github.com/revo1290.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cc-skill-trace\n\n**Skill invocation debugger \u0026 visualizer for Claude Code**\n\nSee which Claude Code skills fired, when, and why — in your terminal or in an interactive browser dashboard.\n\n[![CI](https://github.com/revo1290/cc-skill-trace/actions/workflows/ci.yml/badge.svg)](https://github.com/revo1290/cc-skill-trace/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/cc-skill-trace)](https://www.npmjs.com/package/cc-skill-trace)\n[![npm downloads](https://img.shields.io/npm/dm/cc-skill-trace)](https://www.npmjs.com/package/cc-skill-trace)\n[![Node.js](https://img.shields.io/node/v/cc-skill-trace)](https://nodejs.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n---\n\n## Terminal Dashboard\n\nRun `cc-skill-trace show` to get an instant view:\n\n```\n════════════════════════════════════════════════════════════════════════════════\n  🔍 cc-skill-trace ─ Skill Invocation Debugger\n────────────────────────────────────────────────────────────────────────────────\n\n    12 invocations     9 🤖 auto     3 👤 user     4 unique skills\n\n  🤖 Auto-trigger  ████████████████████████░░░░░░  75%\n\n────────────────────────────────────────────────────────────────────────────────\n\n  📊 Skills\n\n  commit       ████████████████████████  8x  6auto · 2user\n  review-pr    ████████████░░░░░░░░░░░░  3x  2auto · 1user\n  security     ████░░░░░░░░░░░░░░░░░░░░  1x  1auto · 0user\n\n────────────────────────────────────────────────────────────────────────────────\n\n  🕐 Recent invocations  (newest first)\n\n  ● 14:34:55  commit     🤖 auto  \"tests passed, please open a PR\"\n  ● 14:31:07  commit     🤖 auto  \"commit this change\"\n  ● 14:28:44  review-pr  👤 user  \"/review-pr 123\"\n\n────────────────────────────────────────────────────────────────────────────────\n  cc-skill-trace report  → interactive browser dashboard\n════════════════════════════════════════════════════════════════════════════════\n```\n\n---\n\n## Installation\n\n```bash\nnpm install -g cc-skill-trace\n```\n\n### Install from source\n\n```bash\ngit clone https://github.com/revo1290/cc-skill-trace.git\ncd cc-skill-trace\nnpm install \u0026\u0026 npm run build\nnpm link\n```\n\n---\n\n## Setup\n\n```bash\n# Register the capture hook + /skill-trace skill in Claude Code\ncc-skill-trace install\n\n# Restart Claude Code\n```\n\nThat's it. Every subsequent skill invocation is captured automatically.\n\n### Uninstall\n\n```bash\ncc-skill-trace uninstall           # remove from global settings\ncc-skill-trace uninstall --project # remove from project settings\n```\n\n### Use inside Claude Code (as a plugin)\n\nType `/skill-trace` in the Claude Code chat to open the dashboard and have Claude explain why each skill was auto-triggered.\n\n---\n\n## CLI Reference\n\n### Dashboard \u0026 Viewing\n\n```bash\n# Terminal dashboard (default)\ncc-skill-trace show\n\n# Live-tail: refresh every 2s (Ctrl+C to exit)\ncc-skill-trace show --follow\n\n# Backfill from past session logs, then show\ncc-skill-trace show --scan\n\n# Compact one-line list\ncc-skill-trace show --compact\n\n# JSON output (pipe-friendly for scripting)\ncc-skill-trace show --json\n\n# Filter options\ncc-skill-trace show --skill commit\ncc-skill-trace show --since 2026-04-01\ncc-skill-trace show --since 2026-04-01 --before 2026-04-30\ncc-skill-trace show --session \u003csession-id\u003e\ncc-skill-trace show -n 100          # show last 100 events (default: 50)\n```\n\n### Skill Discovery\n\n```bash\n# List all unique skills with auto/user counts\ncc-skill-trace list-skills       # or: cc-skill-trace ls\n\n# Filter by date or backfill first\ncc-skill-trace ls --since 2026-04-01\ncc-skill-trace ls --scan --json  # machine-readable\n```\n\n### Statistics\n\n```bash\n# Aggregated daily activity + top sessions\ncc-skill-trace stats\n\n# Filter stats to a specific skill or date range\ncc-skill-trace stats --skill commit --since 2026-04-01\ncc-skill-trace stats --scan   # backfill first\n```\n\n### Browser Report\n\n```bash\n# Generate interactive HTML report and open in browser\ncc-skill-trace report\n\n# Save to custom path without opening\ncc-skill-trace report -o ~/reports/skills.html --no-open\n\n# Filter and scan first\ncc-skill-trace report --since 2026-04-01 --scan\n```\n\n### Export\n\n```bash\n# Export all events as JSON (stdout — pipe-friendly)\ncc-skill-trace export\n\n# Export as CSV\ncc-skill-trace export --format csv\n\n# Save to file\ncc-skill-trace export --format csv -o events.csv\n\n# Filter before exporting\ncc-skill-trace export --since 2026-04-01 --skill commit\n```\n\n### Backfill (Retroactive Scan)\n\n```bash\n# Scan ~/.claude/projects/**/*.jsonl and import past invocations\ncc-skill-trace scan\n\n# Scan only recent sessions\ncc-skill-trace scan --since 2026-04-01\n\n# Clear and rescan from scratch\ncc-skill-trace scan --clear\n```\n\n### Data Management\n\n```bash\n# Clear all events\ncc-skill-trace clear\n\n# Remove events older than 30 days (keep recent)\ncc-skill-trace clear --older-than 30d\ncc-skill-trace clear --older-than 7d\n```\n\n### Hook Management\n\n```bash\n# Install hook + skill\ncc-skill-trace install             # global (~/.claude/settings.json)\ncc-skill-trace install --project   # project (.claude/settings.json)\n\n# Remove hook\ncc-skill-trace uninstall\ncc-skill-trace uninstall --project\n```\n\n---\n\n## How it works\n\n### 1. Real-time capture (PreToolUse hook)\n\n`cc-skill-trace install` adds the following to `~/.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [{\n      \"matcher\": \"Skill\",\n      \"hooks\": [{ \"type\": \"command\", \"command\": \"cc-skill-trace hook-capture\" }]\n    }]\n  }\n}\n```\n\nEvery time a skill is invoked, `hook-capture` fires and appends an event to `~/.cc-skill-trace/events.jsonl`.\nIt always returns `{}` and **never blocks Claude Code**.\n\n\u003e **Note:** Real-time events captured by `hook-capture` do not include `triggerMessage` (the preceding user message). Run `cc-skill-trace scan` to backfill trigger messages from session logs.\n\n### 2. Retroactive scan\n\n`~/.claude/projects/**/*.jsonl` session logs are parsed to extract past skill invocations, including the user message that preceded each one (the \"trigger\").\n\n### 3. Claude Code skill (`/skill-trace`)\n\nInstalling `~/.claude/skills/skill-trace/SKILL.md` lets you call `/skill-trace` from the Claude Code chat.\nClaude runs the dashboard and interprets the results — explaining why an auto-trigger rate is high, which skills fire unexpectedly, and how to narrow skill descriptions.\n\n---\n\n## Environment Variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `CC_PROJECTS_DIR` | `~/.claude/projects` | Override the scan directory for session logs |\n| `CC_DEBUG` | _(unset)_ | Set to `1` to enable debug logging in `hook-capture` (written to stderr) |\n| `CC_SCAN_CONCURRENCY` | `8` | Number of session files to read in parallel during scan |\n\n---\n\n## Programmatic API\n\nUse cc-skill-trace as a Node.js library:\n\n```typescript\nimport { readEvents, extractAllInvocations, buildHtmlReport } from \"cc-skill-trace\";\nimport type { SkillInvocationEvent } from \"cc-skill-trace\";\n\n// Read stored events\nconst events: SkillInvocationEvent[] = await readEvents();\n\n// Scan session logs\nconst past = await extractAllInvocations({ since: \"2026-04-01\" });\n\n// Generate an HTML report string\nconst html = buildHtmlReport(events);\n```\n\n**Exported API:**\n\n| Export | Description |\n|---|---|\n| `readEvents(dir?)` | Read events from the store |\n| `appendEvent(event, dir?)` | Append a single event |\n| `clearEvents(dir?)` | Clear the event store |\n| `pruneEvents(beforeIso, dir?)` | Remove events older than ISO date |\n| `extractAllInvocations(opts?)` | Scan all session logs |\n| `extractInvocationsFromFile(path)` | Scan a single session file |\n| `buildStats(events)` | Aggregate events by skill |\n| `buildHtmlReport(events)` | Generate standalone HTML string |\n| `STORE_DIR` | Default store directory path |\n| `EVENTS_FILE` | Default events file path |\n\n---\n\n## Data storage\n\n```\n~/.cc-skill-trace/\n└── events.jsonl   # stored locally only — nothing is sent externally\n```\n\nEach line is a JSON object matching `SkillInvocationEvent`:\n\n```typescript\ninterface SkillInvocationEvent {\n  id: string;           // unique event ID\n  timestamp: string;    // ISO 8601\n  sessionId: string;    // Claude Code session ID\n  skillName: string;    // e.g. \"commit\", \"review-pr\"\n  skillArgs?: string;   // slash command arguments\n  source: \"user\" | \"claude\" | \"unknown\";\n  triggerMessage?: string;  // user message that preceded this invocation\n  cwd?: string;\n  gitBranch?: string;\n}\n```\n\n---\n\n## Requirements\n\n- Node.js 18 or later\n- Claude Code (with skill support)\n\n---\n\n## Releasing a new version\n\nReleases are fully automated via GitHub Actions (`release.yml`).\n\n1. Go to **Actions → Release → Run workflow** on GitHub.\n2. Enter the new version number (e.g. `0.12.0`).\n3. The workflow will: bump `package.json`, open a release PR, create a signed tag, publish to npm with provenance, and create a GitHub Release.\n\n---\n\n## License\n\nMIT © [revo1290](https://github.com/revo1290)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frevo1290%2Fcc-skill-trace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frevo1290%2Fcc-skill-trace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frevo1290%2Fcc-skill-trace/lists"}