skill-trace
crackcode09/skill-trace
skill-trace — searchable viewer for Claude Code skill entries across all projects. Auto-starts on session begin.
Instalação
npx convez-ai crackcode09/skill-trace1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
// the problem
Claude Code developers write valuable lessons into docs/skills.md files — but those entries stay siloed per project. When starting a new project or hitting a problem you've solved before, there's no way to search across all your accumulated knowledge. Lessons written in one project are invisible when working in another.
// the solution
A SessionStart hook automatically launches a local web server on port 38888. On startup, it parses ~/.claude/global-skills.md into an in-memory search index. A PostToolUse hook syncs new entries from any project into that global file the moment you write them.
The viewer is already running before the first keystroke of the session — zero friction.
// architecture
Claude Code session starts
│
▼
SessionStart hook → start-viewer.ps1 / start-viewer.sh
│
├── Port 38888 occupied + HTTP probe passes → skip (already running)
│
└── node viewer/server.js
│
├── parseMd() → ~/.claude/global-skills.md → in-memory array
├── fs.watch → auto-resync on file change (500ms debounce)
├── PID file → ~/.claude/global-skills.pid
└── :38888
├── GET / → 3-column viewer UI
├── GET /api/skills → substring search across all fields
└── POST /api/sync → manual re-parse
On any Write/Edit to docs/skills.md:
PostToolUse hook → sync-skills.ps1 → append to global-skills.md
→ fs.watch picks up change → array resyncs
// capture flow
// install
Option A — Claude Code plugin install (recommended)
/plugin marketplace add crackcode09/skill-trace
/plugin install skill-trace@skill-trace
Hooks are configured automatically. Start a new session and the viewer is running.
Option B — Manual clone
# Windows
git clone https://github.com/crackcode09/skill-trace "$env:USERPROFILE\.claude\skills\skill-trace"
# macOS / Linux
git clone https://github.com/crackcode09/skill-trace ~/.claude/skills/skill-trace
2. Add the hooks to ~/.claude/settings.json (manual install only)
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "powershell -ExecutionPolicy Bypass -NonInteractive -File \"C:\\Users\\YOUR_NAME\\.claude\\skills\\skill-trace\\hooks\\scripts\\sync-skills.ps1\"",
"timeout": 15
}]
}
],
"SessionStart": [
{
"matcher": "startup",
"hooks": [{
"type": "command",
"command": "powershell -ExecutionPolicy Bypass -NonInteractive -WindowStyle Hidden -File \"C:\\Users\\YOUR_NAME\\.claude\\skills\\skill-trace\\hooks\\scripts\\start-viewer.ps1\"",
"timeout": 30
}]
}
]
}
}
Replace
YOUR_NAMEwith your Windows username. On macOS/Linux, usestart-viewer.shinstead.
3. Start a new Claude Code session
The viewer starts automatically. Open http://localhost:38888 to confirm.
// usage
Add entries to docs/skills.md in any project:
## 2026-06-10 — HTMX partial detection
**Problem:** Routes that serve both full pages and HTMX partials need to
detect which is being requested.
**Solution:** Check the `hx-request` header — HTMX sets it on every
partial request.
**Takeaway:** Always check `req.headers['hx-request']` before rendering
a full layout vs. a fragment.
The PostToolUse hook fires on every save, appends to ~/.claude/global-skills.md, and the viewer resyncs within 500ms. Search with /gskills from inside Claude Code, or open http://localhost:38888 in a browser.
// viewer
Search across title, problem, solution, and takeaway. Filter by project. Click any entry for the full detail pane.
// tech stack
| Layer | Technology | Detail |
|---|---|---|
| Server | Node.js built-ins only | http, fs, path, os — zero npm dependencies |
| Search | In-memory Array.filter() | Substring match, fast enough for < 1000 entries |
| UI | Vanilla JS + CSS | Single HTML file, no framework, no build step |
| Live sync | fs.watch + 500ms debounce | Auto-resyncs when global-skills.md changes |
| Hooks | PowerShell + Bash | Windows: .ps1 · macOS/Linux: .sh |
| Storage | Flat Markdown | ~/.claude/global-skills.md — readable without the app |
// key decisions
// roadmap
| Version | Feature | Status |
|---|---|---|
| v1.2.0 | Zero-dep server, Mac/Linux support, skill-trace rename | ✅ shipped |
| v1.3.0 | PreToolUse hook — auto-inject relevant skills into Claude's context | planned |
| v2.0.0 | Team sync — shared repo or API backend, multi-developer | planned |
// files
skill-trace/
├── viewer/
│ ├── server.js # Node.js HTTP server (port 38888) — zero deps
│ ├── package.json # dependencies: {}
│ └── public/
│ └── index.html # 3-column viewer UI
├── hooks/
│ ├── hooks.json
│ └── scripts/
│ ├── sync-skills.ps1 # PostToolUse: append to global-skills.md
│ ├── start-viewer.ps1 # SessionStart: Windows viewer startup
│ └── start-viewer.sh # SessionStart: macOS/Linux viewer startup
├── skills/
│ └── gskills/
│ └── SKILL.md # /gskills slash command
├── .claude-plugin/
│ └── plugin.json
├── LICENSE
├── CHANGELOG.md
└── README.md
// contributing
The codebase is intentionally simple — viewer/server.js is ~110 lines with no dependencies. A new contributor can read the whole server in 5 minutes.
- Fork the repo
- Add your entry format support, search improvements, or platform-specific hook scripts
- Test:
node viewer/server.js— verifyGET /api/skillsreturns entries - Open a PR
// license
MIT — see LICENSE
skill-trace v1.2.0 · 2026-06-10 · MIT