convez.ai
Skill
crackcode09

skill-trace

crackcode09/skill-trace

Ver no GitHub
InicialPluginScore · de 0 a 100

skill-trace — searchable viewer for Claude Code skill entries across all projects. Auto-starts on session begin.

Instalação

$npx convez-ai crackcode09/skill-trace

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 mês
Versão
v1.4.0
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

skill-trace


// 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

skill-trace 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_NAME with your Windows username. On macOS/Linux, use start-viewer.sh instead.

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

skill-trace viewer

Search across title, problem, solution, and takeaway. Filter by project. Click any entry for the full detail pane.


// tech stack

LayerTechnologyDetail
ServerNode.js built-ins onlyhttp, fs, path, os — zero npm dependencies
SearchIn-memory Array.filter()Substring match, fast enough for < 1000 entries
UIVanilla JS + CSSSingle HTML file, no framework, no build step
Live syncfs.watch + 500ms debounceAuto-resyncs when global-skills.md changes
HooksPowerShell + BashWindows: .ps1 · macOS/Linux: .sh
StorageFlat Markdown~/.claude/global-skills.md — readable without the app

// key decisions


// roadmap

VersionFeatureStatus
v1.2.0Zero-dep server, Mac/Linux support, skill-trace rename✅ shipped
v1.3.0PreToolUse hook — auto-inject relevant skills into Claude's contextplanned
v2.0.0Team sync — shared repo or API backend, multi-developerplanned

// 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.

  1. Fork the repo
  2. Add your entry format support, search improvements, or platform-specific hook scripts
  3. Test: node viewer/server.js — verify GET /api/skills returns entries
  4. Open a PR

// license

MIT — see LICENSE


skill-trace v1.2.0 · 2026-06-10 · MIT
Ver o original no GitHub

Bom para

Relacionados