skillar 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +194 -2
  3. package/dist/analysis/finding.js +190 -0
  4. package/dist/analysis/tree.js +157 -0
  5. package/dist/analysis/usage.js +394 -0
  6. package/dist/api/flows.js +285 -0
  7. package/dist/api/routes.js +192 -0
  8. package/dist/api/security.js +86 -0
  9. package/dist/api/sse.js +55 -0
  10. package/dist/api/static.js +33 -0
  11. package/dist/catalog/fields.js +159 -0
  12. package/dist/catalog/index.js +133 -0
  13. package/dist/catalog/scanner.js +204 -0
  14. package/dist/catalog/uri.js +43 -0
  15. package/dist/catalog/watcher.js +59 -0
  16. package/dist/cli/config-writer.js +255 -0
  17. package/dist/cli/doctor.js +268 -0
  18. package/dist/cli/eval.js +64 -0
  19. package/dist/cli/export-import.js +68 -0
  20. package/dist/cli/init.js +272 -0
  21. package/dist/cli/main.js +165 -0
  22. package/dist/cli/open.js +24 -0
  23. package/dist/cli/serve.js +147 -0
  24. package/dist/config.js +92 -0
  25. package/dist/dashboard/assets/app.js +354 -0
  26. package/dist/dashboard/assets/chunk-5DFWNJC2.js +1 -0
  27. package/dist/dashboard/assets/chunk-S6B2HJQA.js +17 -0
  28. package/dist/dashboard/assets/styles.css +542 -0
  29. package/dist/dashboard/index.html +15 -0
  30. package/dist/fs-watchdog.js +35 -0
  31. package/dist/herdr/client.js +205 -0
  32. package/dist/herdr/sync.js +342 -0
  33. package/dist/ingest/attribution.js +80 -0
  34. package/dist/ingest/hooks.js +168 -0
  35. package/dist/ingest/identity.js +4 -0
  36. package/dist/ingest/mcp-recorder.js +41 -0
  37. package/dist/ingest/otlp-traces.js +106 -0
  38. package/dist/ingest/otlp.js +314 -0
  39. package/dist/ingest/pipeline.js +119 -0
  40. package/dist/ingest/redact.js +36 -0
  41. package/dist/ingest/runtimes.js +25 -0
  42. package/dist/mcp/dispatch.js +54 -0
  43. package/dist/mcp/http.js +112 -0
  44. package/dist/mcp/legacy.js +61 -0
  45. package/dist/mcp/pagination.js +17 -0
  46. package/dist/mcp/protocol.js +121 -0
  47. package/dist/mcp/skills-extension.js +77 -0
  48. package/dist/mcp/stdio-proxy.js +108 -0
  49. package/dist/mcp/tools.js +59 -0
  50. package/dist/packs/claude-code.js +176 -0
  51. package/dist/packs/codex.js +207 -0
  52. package/dist/packs/cursor.js +97 -0
  53. package/dist/packs/gajae.js +7 -0
  54. package/dist/packs/gemini.js +90 -0
  55. package/dist/packs/json-config.js +55 -0
  56. package/dist/packs/omo.js +154 -0
  57. package/dist/packs/openclaw.js +132 -0
  58. package/dist/packs/registry.js +13 -0
  59. package/dist/search/fts.js +61 -0
  60. package/dist/search/fusion.js +50 -0
  61. package/dist/search/guidance.js +7 -0
  62. package/dist/search/index.js +74 -0
  63. package/dist/search/lexical.js +69 -0
  64. package/dist/server.js +267 -0
  65. package/dist/store/automation.js +18 -0
  66. package/dist/store/db.js +134 -0
  67. package/dist/store/execution.js +157 -0
  68. package/dist/store/export.js +269 -0
  69. package/dist/store/index.js +14 -0
  70. package/dist/store/migrations/002_tracing.sql +94 -0
  71. package/dist/store/migrations/003_tracing_indexes.sql +11 -0
  72. package/dist/store/migrations/004_load_reconciliation.sql +50 -0
  73. package/dist/store/migrations/005_execution_boundaries.sql +6 -0
  74. package/dist/store/migrations/006_recording_order.sql +72 -0
  75. package/dist/store/queries.js +643 -0
  76. package/dist/store/schema.sql +96 -0
  77. package/dist/store/workflow.js +250 -0
  78. package/dist/store/writes.js +315 -0
  79. package/dist/types.js +1 -0
  80. package/dist/version.js +19 -0
  81. package/dist/workflow/compare.js +68 -0
  82. package/dist/workflow/routes.js +100 -0
  83. package/dist/workflow/spec.js +40 -0
  84. package/docs/execution-ownership.md +98 -0
  85. package/docs/mcp-conformance.md +156 -0
  86. package/docs/skill-tracing.md +294 -0
  87. package/package.json +48 -4
  88. package/packs/claude-code/README.md +5 -0
  89. package/packs/claude-code/settings.template.json +34 -0
  90. package/packs/codex/README.md +8 -0
  91. package/packs/codex/config.template.toml +12 -0
  92. package/packs/cursor/hooks.example.json +8 -0
  93. package/packs/cursor/mcp.example.json +8 -0
  94. package/packs/gajae/extension/discovery.md +5 -0
  95. package/packs/gajae/extension/index.js +52 -0
  96. package/packs/gemini/settings.example.json +16 -0
  97. package/packs/hook-post.mjs +37 -0
  98. package/packs/omo/extension/discovery.md +5 -0
  99. package/packs/omo/extension/index.js +52 -0
  100. package/packs/openclaw/.codex-plugin/plugin.json +11 -0
  101. package/packs/openclaw/.mcp.json +12 -0
  102. package/packs/openclaw/hooks/skillar-discovery/HOOK.md +8 -0
  103. package/packs/openclaw/hooks/skillar-discovery/handler.js +30 -0
  104. package/packs/openclaw/index.mjs +55 -0
  105. package/packs/openclaw/openclaw.plugin.json +22 -0
  106. package/packs/openclaw/package.json +11 -0
  107. package/packs/openclaw/skillar.json +1 -0
  108. package/src/store/migrations/002_tracing.sql +94 -0
  109. package/src/store/migrations/003_tracing_indexes.sql +11 -0
  110. package/src/store/migrations/004_load_reconciliation.sql +50 -0
  111. package/src/store/migrations/005_execution_boundaries.sql +6 -0
  112. package/src/store/migrations/006_recording_order.sql +72 -0
  113. package/src/store/schema.sql +96 -0
  114. package/src/store/task-types.json +15 -0
@@ -0,0 +1,294 @@
1
+ # Skill tracing
2
+
3
+ skillar joins agent telemetry to herdr panes and compares observed skill use with an orchestrator's intended
4
+ workflow. Analysis is computed from stored events when a report is read. It observes; it does not judge with
5
+ an LLM, restrict skill choices, or send input to panes.
6
+
7
+ ## Requirements
8
+
9
+ herdr is required. Start herdr and run `skillar doctor` (or `skillar doctor --json`). The `herdr` check discovers
10
+ the socket through `herdr status server` and sends a ping; `SKILLAR_HERDR_SOCKET` overrides socket discovery.
11
+ A missing herdr command, unavailable socket, or invalid ping reply fails the check with `herdr_unavailable`;
12
+ doctor exits 1 if any check fails.
13
+
14
+ If herdr is unreachable, the daemon keeps collecting sessions and serving MCP and existing views. New panes
15
+ and sessions requiring live discovery are not linked until sync reconnects and reconciles. Previously stored
16
+ pane/session links and reports remain available, including with `SKILLAR_HERDR=off`. A session skill report
17
+ can be read without a herdr link. Workspaces also shows these sessions as **outside herdr**; herdr being
18
+ unavailable does not hide ingested sessions from the flows list.
19
+
20
+ ## What is collected
21
+
22
+ These fields were observed in captures of Claude Code 2.1.273 and Codex CLI 0.162.1 on October 14, 2026.
23
+ The table describes what skillar keeps, not every field those agents export.
24
+
25
+ | Agent / channel | Records kept | Available measurements and identity |
26
+ | --- | --- | --- |
27
+ | Claude Code logs | `claude_code.api_request` | Model, input/output and cache read/creation tokens, reported USD cost, duration, TTFT, request ID, optional skill name; `session.id` and `prompt.id`. |
28
+ | Claude Code logs | `claude_code.tool_result` | Tool name, captured arguments, success, duration, input/result byte counts, `tool_use_id`, `prompt.id`. Skill-file reads can also produce native-skill observations. No result-content field was observed. |
29
+ | Claude Code logs | `claude_code.skill_activated`, `claude_code.user_prompt` | Skill name, trigger/source and turn key; prompt text when exported, otherwise unavailable text with reported length when present. |
30
+ | Codex logs | `codex.sse_event` with `event.kind=response.completed` | Model, input/output, cached/cache-write, reasoning and total tokens, TTFT when reported; `conversation.id`. No reported USD cost. Other SSE events are ignored. |
31
+ | Codex logs | `codex.tool_result` | Tool name, captured `arguments`, success, duration, `call_id`, conversation and log span context. Captured tool results lacked a turn key; output content is not retained by this mapper. |
32
+ | Codex logs | `codex.skill_invocation`, `codex.user_prompt`, `codex.conversation_starts` | Skill name, scope/type and `turn.id`; exported prompts and conversation identity; session start. |
33
+ | Codex traces | Joinable spans only | A span must carry `turn_id`, `turn.id`, or `call_id`, plus trace ID, span ID and name. Stored fields are those IDs, parent span ID, runtime, conversation ID, turn/call keys, start/end times and receive time. Other attributes and keyless spans are dropped. |
34
+
35
+ Logs enter through `POST /ingest/otlp/v1/logs`; traces through `POST /ingest/otlp/v1/traces` (OTLP/HTTP JSON).
36
+ Both acknowledge with 202 before storage. The Codex pack configures both exporters and disables metrics.
37
+ The Claude pack configures logs, prompt/tool details and capture hooks, not a trace exporter or enhanced
38
+ telemetry beta. Claude traces from the verification experiment are not a pack requirement.
39
+
40
+ `codex.api_request` is deliberately ignored: the captured records have neither a session nor a timestamp
41
+ identity for attribution. Hook lifecycle, tool-decision and connection noise is also ignored; unknown log
42
+ event names are counted rather than stored. skillar MCP searches, `SKILL.md` loads and supporting-file reads
43
+ are separate observations, not tool-result guesses.
44
+
45
+ ## Pane and turn joins
46
+
47
+ The tree is workspace > tab > pane > session > turn > skill span > tool/model calls. A pane can contain
48
+ successive sessions. Sync subscribes globally to herdr topology events and opens a separate
49
+ `pane.agent_status_changed` stream with the required `pane_id` for each live pane from snapshots or
50
+ pane-creation reconciliation. Closing a pane or removing it from its workspace closes that stream
51
+ (herdr subscriptions are socket-scoped). Reconnection restores subscriptions from a fresh snapshot.
52
+
53
+ Reported identity wins: a usable herdr `agent_session` ID matches a session's runtime session ID or
54
+ conversation ID. These links retain their `herdr:` source. Without usable identity, any agent, including
55
+ OmO, can be inferred from an exact nonempty cwd match and a session start within the pane's lifetime.
56
+ Agent/runtime matches take precedence over shell panes, including when a matching pane is occupied:
57
+ concurrent work does not fall back to the shell. Multiple equally eligible panes remain unlinked rather
58
+ than being guessed from recency. A detected mismatching runtime causes abstention when none matches;
59
+ only a unique unknown-runtime pane without conflicting agent evidence can be inferred as a fallback.
60
+ Reported links reserve their panes and sessions before inference.
61
+ Each inferred session gets only one pane. A newer explicit SessionStart in the same unambiguous pane ends
62
+ the earlier session's reservation at the successor's start; ambiguous same-cwd panes are not resolved this way.
63
+ Inferred links are labelled `inferred:cwd_time`, not reported.
64
+
65
+ Still-open panes qualify for discovery regardless of age. Unchanged linked history is retained on later
66
+ passes; new/unlinked sessions, touched active sessions and changed same-cwd topology are reconsidered.
67
+ An old open pane's entire completed session history is not deleted and recreated on every reconcile.
68
+
69
+ The Claude pack installs both SessionStart and SessionEnd hooks using the same `hook-post.mjs` command.
70
+ A SessionEnd becomes a `session_end` event and sets `sessions.ended_at` to its event timestamp. A herdr
71
+ `pane.exited`, pane status reporting `agent:null`, or a snapshot showing a previously detected agent removed also ends
72
+ linked open sessions. Historical links survive these end signals, but no longer reserve the pane forever.
73
+ An idle or `done` interactive agent is not a process exit.
74
+
75
+ ### Registered execution scope
76
+
77
+ Registered flows use the inclusive event window `[registeredMs, endedMs]`; an open flow has no end bound.
78
+ The list's membership, detail tree, finding, usage and step comparison all use that window, including panes
79
+ explicitly mapped to steps on another tab. Unmapped panes in the registered workspace/tab remain visible as
80
+ unplanned work. A linked session belongs when it starts or has events in the window; an unmatched reported
81
+ identity belongs only when first seen within it. Implicit `ws:` workspace reports retain full pane history.
82
+
83
+ A session continuing across executions appears in each execution with only that execution's events.
84
+ `executionScope.overlaps` labels `startedBefore` and `continuesAfter` per session. Original turn identity is
85
+ preserved even when a turn crosses registration; turn/span durations and session bounds are clipped to the
86
+ execution. Activations, searches, calls, later-missed skills and correction prompts outside the window do not
87
+ contribute. A skill activated only before registration is not credited as an activation in the new run.
88
+ Ending A and running B on the same pane does not add B's sessions, turns, skills or costs to A.
89
+
90
+ Turn/event `basis` explains membership:
91
+
92
+ | Basis | Meaning |
93
+ | --- | --- |
94
+ | `reported` | An explicit turn key, such as Claude `prompt.id` or Codex `turn.id`; Codex `codex.turn_input` spans supply reported turn boundaries. |
95
+ | `span_join` | A tool call joins a span with one unambiguous turn key through `call_id` or exact trace/span context. |
96
+ | `inferred_time` | A keyless event falls into the latest preceding turn; unmatched prompts create synthetic turns. |
97
+
98
+ Nearby hook and telemetry prompt observations are paired within five seconds to avoid duplicate turns.
99
+ Events without a usable boundary stay in `unassignedEvents`. Conversation ID or trace ID alone is not
100
+ proof of turn membership.
101
+
102
+ A load or native activation opens a skill span until the turn ends. Skills accumulate within the turn and
103
+ reset at the next turn. Calls are attributed as `reported` when a model call names its skill, `single` when
104
+ one skill is active, `co_active` when several are active, or `no_skill`. Co-active calls can appear in more
105
+ than one skill span; these are observations of shared activity, not exclusive causation or additive billing.
106
+
107
+ ## Orchestrator protocol
108
+
109
+ Use the daemon port from `~/.skillar/config.json` (default 8799) and the bearer token from `~/.skillar/token`.
110
+ With `SKILLAR_HOME`, use that directory instead. The following examples use `jq` to construct JSON.
111
+ Use actual workspace, tab and pane IDs returned by herdr, not their display positions.
112
+
113
+ ```sh
114
+ SKILLAR_HOME="${SKILLAR_HOME:-$HOME/.skillar}"
115
+ PORT=$(jq -r '.port // 8799' "$SKILLAR_HOME/config.json")
116
+ BASE="http://127.0.0.1:${PORT:-8799}"
117
+ TOKEN=$(cat "$SKILLAR_HOME/token")
118
+ ```
119
+
120
+ 1. Before opening panes, register a spec with `POST /api/workflows`:
121
+
122
+ ```sh
123
+ curl -fsS -X POST "$BASE/api/workflows" \
124
+ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
125
+ --data '{"name":"task-workflow","steps":[
126
+ {"id":"build","skills":["programming","debugging"],"together":true,
127
+ "expectTools":["Edit","Bash"],"doneWhen":"Implementation verified"}
128
+ ]}'
129
+ ```
130
+
131
+ Names and step IDs are slugs of at most 64 characters: start with a letter or digit, then use letters,
132
+ digits, `.`, `_` or `-`. A spec has 1-50 unique steps, each with a required `skills` array of up to 10
133
+ names (128 characters each). `together` defaults to false: any intended skill satisfies the step;
134
+ true expects all of them. `expectTools` defaults to `[]`; `doneWhen` is optional, at most 500 characters,
135
+ and is descriptive, not an executable completion check. Unknown fields are rejected.
136
+
137
+ Equivalent parsed specs return 200 with the same version and `created:false`; changed specs return
138
+ 201 with a new version and `created:true`. The response includes `id`, `name`, `version`, `digest`
139
+ and `createdMs`. `GET /api/workflows` lists latest specs; `GET /api/workflows/:name/versions` lists
140
+ a named spec's versions, newest first (404 if unknown).
141
+
142
+ 2. Start the flow with `POST /api/flows` before dispatching work:
143
+
144
+ ```sh
145
+ RESPONSE=$(curl -sS -X POST "$BASE/api/flows" \
146
+ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
147
+ --data "$(jq -n --arg workspaceId "$HERDR_WORKSPACE_ID" --arg tabId "$HERDR_TAB_ID" \
148
+ '{workspaceId:$workspaceId,tabId:$tabId,spec:{name:"task-workflow"},label:"Task run"}')")
149
+ printf '%s\n' "$RESPONSE"
150
+ ```
151
+
152
+ A 201 response contains `id`, workspace/tab IDs, label, the resolved spec and `registeredMs`.
153
+ `spec.version` is optional; omitting it selects the latest version. `tabId` and `label` are optional;
154
+ provide the tab ID for tab-scoped orchestration. An unknown spec/version returns 404.
155
+
156
+ There is one open flow per workspace/tab pair, including the pair with no tab ID. A second start
157
+ returns 409 with `error:"flow_already_open"` and the existing `flowId` until that flow ends.
158
+ Reconcile that ID with the task ledger before reusing it; do not treat an arbitrary error as a flow ID.
159
+ Keep the successful flow ID as `FLOW_ID` in the ledger.
160
+
161
+ 3. Right after each `herdr pane split`, take the new pane ID from herdr and map it before assigning work
162
+ with `POST /api/flows/:id/steps`. Map reused panes too:
163
+
164
+ ```sh
165
+ curl -fsS -X POST "$BASE/api/flows/$FLOW_ID/steps" \
166
+ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
167
+ --data "$(jq -n --arg paneId "$PANE_ID" '{paneId:$paneId,stepId:"build"}')"
168
+ ```
169
+
170
+ The body is exactly `{paneId,stepId}`. A new mapping returns 201; repeating it returns 200 with
171
+ `created:false`. An unknown step returns 400 `unknown_step`; an unknown flow returns 404.
172
+ Tell the agent its intended skills and whether they are together or alternatives, as guidance only.
173
+
174
+ 4. After accounting for the assignments, end the flow with `POST /api/flows/:id/end`:
175
+
176
+ ```sh
177
+ curl -fsS -X POST "$BASE/api/flows/$FLOW_ID/end" \
178
+ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' --data '{}'
179
+ ```
180
+
181
+ This returns `id`, `endedMs` and `alreadyEnded`. Repeating it preserves the end time and returns
182
+ `alreadyEnded:true`. A new flow can then start on that tab. End deliberately interrupted runs too;
183
+ do not close unrelated flows.
184
+
185
+ If tracing is unavailable, continue useful orchestration and record the gap. skillar registration is
186
+ observation, not permission to run tools or enforcement of the declared skills.
187
+
188
+ ## Read reports
189
+
190
+ All these routes require the same bearer token. Reports are computed on read and include `generatedAt`.
191
+ Unknown measurements are `null`, not zero.
192
+
193
+ | Route | Result / bounds |
194
+ | --- | --- |
195
+ | `GET /api/flows` | Registered flows, herdr workspaces without a registered flow, and the `outside` group (`kind:"outside_herdr"`, label `outside herdr`), newest first. `limit` is 1-100 (default 20); use the returned `nextCursor` for paging. Optional `from`/`to` filter ordering time. |
196
+ | `GET /api/flows/:id` | Tree, per-session finding/usage, skill aggregates, spec comparison and excluded sessions. An unregistered workspace is addressed as `ws:<workspaceId>` and has no comparison. Unknown IDs return 404. |
197
+ | `GET /api/flows/outside` | Sessions without a pane link (no `pane_sessions` row or only `source:"unlinked"` rows), newest activity first, in `tree.sessions`, with finding and usage, no spec/comparison and no invented panes. Accepts `from`, `to`, `limit` (1-100, default 100), and `automated`. |
198
+ | `GET /api/sessions/:id/skill-report` | One session's tree, finding, usage and automation state, even outside herdr. Unknown or excluded sessions return 404. |
199
+ | `GET /api/skills/usage` | Per-skill totals over `[from,to)` in epoch milliseconds. Defaults to the last seven days, maximum 366 days. `detail` is 0-100 (default 20) and limits only session details; `sessionCount` and `truncated` describe that list, while skill totals cover all eligible sessions. |
200
+
201
+ Automated sessions are excluded by default. Pass `automated=include` or `automated=only`; flow comparisons
202
+ exclude the same hidden sessions. Invalid limits, ranges and automation filters return 400.
203
+
204
+ The outside group contains at most 100 eligible sessions, classified before the cap. Its counts and
205
+ `sessionIds` describe that bounded population, not a whole-history total. Activity is the latest session
206
+ start, end or event timestamp; `[from,to)` selects that activity. With no range, outside sessions use the
207
+ last seven days. The group is omitted when no eligible session exists,
208
+ and is ordered and cursor-paged alongside flows/workspaces by its newest eligible activity and stable ID
209
+ `outside`. Pass the same range and automation filter to its detail report to read the same population.
210
+
211
+ The existing `GET /api/flow` is the task-to-skill-to-outcome Sankey aggregate (`first_load` or `all_loads`),
212
+ not a registered execution. The plural `/api/flows` API is the herdr workflow tree and report surface.
213
+ Other existing routes remain separate: `GET /api/sessions`, `GET /api/sessions/:id/trace`, `GET /api/heatmap`,
214
+ `GET /api/skill-week`, `GET /api/stats`, `GET /api/skills`, `POST /api/eval-cases`, and `GET /api/events/stream`.
215
+ Capture hooks use `POST /ingest/hook/:runtime`; daemon health is `GET /healthz`.
216
+
217
+ ### Finding signals
218
+
219
+ Per-turn findings include searches, queries, candidates, abstention reasons, `usedSkills` and their
220
+ `rankInSearch`, `nativeWithoutSearch`, and `missedLater` (a skill used in a later turn of the same session
221
+ that this turn's searches did not surface). A load is ranked against the latest preceding search.
222
+ Identical `SKILL.md` digests collapse to one rank; same-named variants are not automatically the same skill.
223
+ A native name takes a rank only when it identifies one collapsed candidate group.
224
+
225
+ Labels, in precedence order:
226
+
227
+ | Label | Meaning |
228
+ | --- | --- |
229
+ | `found_top1` | A used skill ranked first. |
230
+ | `found_lower` | A used skill had a lower known rank, with no top-one use. |
231
+ | `native_without_search` | A native activation preceded any search in the turn, with no ranked use taking precedence. |
232
+ | `loaded_outside_results` | A skill was used without a matching preceding result, and no stronger label applies. |
233
+ | `searched_none_used` | Searches occurred but no skill use was observed. |
234
+ | `no_search` | Neither search nor skill use was observed. |
235
+
236
+ Abstention and native-use flags remain visible even when another label wins. These labels describe
237
+ discovery evidence, not task correctness. Their turn membership relies on the reported/joined/inferred bases above.
238
+
239
+ ### Usage signals
240
+
241
+ Each span reports `followThrough` (non-skillar tool calls after activation; zero means no action),
242
+ `skillToolCalls` (skillar MCP calls, counted separately), `toolFailures` (including failed skillar calls),
243
+ `supportingReads`, `durationMs` (activation to turn end), `llmCalls`, tokens, cost and attribution counts/share.
244
+ Supporting reads are `reported` for skillar file reads or `heuristic` for native-skill tool argument paths.
245
+ Calling a file path a supporting read does not establish that the agent followed its instructions.
246
+
247
+ Each span and each per-skill aggregate also carries an `activity` block (`version: 1`) that breaks the
248
+ `followThrough` calls down without judging them: `observations` (the same calls), `commands` (shell tool calls:
249
+ `exec_command`, `Bash`, `shell`, `local_shell`), `unresolvedExec` (Codex `exec` calls), `results`
250
+ (`success` / `failure` / `unknown` by reported status; a call without a status is unknown, never a success) and
251
+ `workExecutions`. A Codex `exec` call runs model-written code that may only dispatch the span's other tool calls or
252
+ also do work of its own, and nothing reported says which, so `workExecutions` is null while a span holds one;
253
+ otherwise it equals `observations`. An aggregate is null when any of its spans is. These are activity counts:
254
+ none of them says whether the skill was applied correctly or helped.
255
+
256
+ Token buckets retain `inputIncludesCache`: Claude input excludes cached tokens; Codex input includes them.
257
+ Fields are `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheCreationTokens`, `cacheWriteTokens`,
258
+ `reasoningTokens` and `totalTokens`. Each sums only calls reporting that field; `unknownCalls` counts the
259
+ missing measurements. A field no call reports stays null. `totalTokens` is reported, not derived.
260
+ `costUsd` is null if there are no model calls or any contributing call lacks cost; `costUnknownCalls`
261
+ counts those missing costs. Codex cost is not estimated.
262
+
263
+ `nextPromptCorrection` is explicitly a word-list heuristic on the next prompt in a later turn of the same
264
+ session: `correction`, `no_correction`, or `unknown` with `no_next_prompt` / `text_not_captured`.
265
+ It is not a quality verdict. Co-active attribution is shared and must not be read as exclusive skill credit.
266
+
267
+ ### Spec comparison
268
+
269
+ | Status | Meaning |
270
+ | --- | --- |
271
+ | `matched` | All intended skills for `together:true`, otherwise at least one; an empty intention with no observed skill also matches. |
272
+ | `partial` | Some, but not all, intended skills appeared in a together step. |
273
+ | `different` | Skills appeared, but none were intended (including a step intending no skill). |
274
+ | `no_skill_used` | Panes were mapped, but no skill use was observed despite intended skills. |
275
+ | `not_run` | No pane was mapped to the step; this does not prove that no work happened elsewhere. |
276
+
277
+ Comparison also reports `extraSkills`, `missingSkills`, `unexpectedTools` and unplanned panes.
278
+ `expectTools:[]` leaves unexpected tools empty. Extra skills do not invalidate a match.
279
+ `together` compares the skills observed across a step's mapped panes; it does not require simultaneous activation.
280
+ Differences are feedback data, never a gate on agent actions.
281
+
282
+ ## Privacy
283
+
284
+ Data stays in the local store; ingest and API requests use the local bearer token. `captureLevel` applies
285
+ to tool arguments as content, just as it does to prompt/search text:
286
+
287
+ - `full`: keep text as sent.
288
+ - `redacted`: mask recognized secret patterns and truncate to 2048 characters; this is not a guarantee that
289
+ every secret is removed.
290
+ - `metadata`: retain only the original text's SHA-256 digest and length, not its text.
291
+
292
+ Missing prompt text makes the correction heuristic unknown, and missing tool arguments removes argument-path
293
+ evidence for supporting reads. Trace storage keeps only the join whitelist described above, not arbitrary span
294
+ attributes or exported content. Capture levels are content controls, not anonymization of session IDs or paths.
package/package.json CHANGED
@@ -1,6 +1,50 @@
1
1
  {
2
2
  "name": "skillar",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "private": false,
5
+ "description": "Local skill router for coding agents: search your skills, trace how agents use them, and see the flow.",
6
+ "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/changeroa/skillar.git",
10
+ "directory": "local"
11
+ },
12
+ "homepage": "https://github.com/changeroa/skillar/tree/main/local#readme",
13
+ "files": [
14
+ "dist",
15
+ "packs",
16
+ "docs",
17
+ "src/store/schema.sql",
18
+ "src/store/migrations",
19
+ "src/store/task-types.json",
20
+ "README.md"
21
+ ],
22
+ "type": "module",
23
+ "bin": {
24
+ "skillar": "dist/cli/main.js",
25
+ "gisool": "dist/cli/main.js"
26
+ },
27
+ "engines": {
28
+ "node": ">=24.15"
29
+ },
30
+ "scripts": {
31
+ "build": "tsc -p tsconfig.json && node build-dashboard.mjs",
32
+ "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p dashboard/tsconfig.json",
33
+ "test": "node --test \"test/**/*.test.mjs\"",
34
+ "start": "node dist/cli/main.js serve"
35
+ },
36
+ "dependencies": {
37
+ "express": "^5.2.1",
38
+ "yaml": "^2.9.0",
39
+ "zod": "^4.1.11"
40
+ },
41
+ "devDependencies": {
42
+ "@types/d3-sankey": "^0.12.4",
43
+ "@types/express": "^5.0.5",
44
+ "@types/node": "^24.3.0",
45
+ "d3-sankey": "0.12.3",
46
+ "esbuild": "^0.28.2",
47
+ "preact": "^10.27.2",
48
+ "typescript": "^5.9.2"
49
+ }
50
+ }
@@ -0,0 +1,5 @@
1
+ # Claude Code capture pack
2
+
3
+ Template merged into `~/.claude/settings.json` by `skillar init`: OTel log export (`env`) plus
4
+ `PostToolUse` / `UserPromptExpansion` hooks that run `packs/hook-post.mjs`. `~/.claude.json` is never edited;
5
+ the MCP server is registered with `claude mcp add --scope user` (or printed as a manual step).
@@ -0,0 +1,34 @@
1
+ {
2
+ "env": {
3
+ "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
4
+ "OTEL_LOGS_EXPORTER": "otlp",
5
+ "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/json",
6
+ "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "http://127.0.0.1:{{PORT}}/ingest/otlp/v1/logs",
7
+ "OTEL_EXPORTER_OTLP_LOGS_HEADERS": "Authorization=Bearer {{TOKEN}}",
8
+ "OTEL_LOG_USER_PROMPTS": "1",
9
+ "OTEL_LOG_TOOL_DETAILS": "1"
10
+ },
11
+ "hooks": {
12
+ "PostToolUse": [
13
+ {
14
+ "matcher": "Skill|mcp__(skillar|gisool)__.*",
15
+ "hooks": [{ "type": "command", "command": "\"{{NODE}}\" \"{{HOOK}}\" claude-code", "timeout": 5 }]
16
+ }
17
+ ],
18
+ "SessionStart": [
19
+ {
20
+ "hooks": [{ "type": "command", "command": "\"{{NODE}}\" \"{{HOOK}}\" claude-code", "timeout": 5 }]
21
+ }
22
+ ],
23
+ "SessionEnd": [
24
+ {
25
+ "hooks": [{ "type": "command", "command": "\"{{NODE}}\" \"{{HOOK}}\" claude-code", "timeout": 5 }]
26
+ }
27
+ ],
28
+ "UserPromptExpansion": [
29
+ {
30
+ "hooks": [{ "type": "command", "command": "\"{{NODE}}\" \"{{HOOK}}\" claude-code", "timeout": 5 }]
31
+ }
32
+ ]
33
+ }
34
+ }
@@ -0,0 +1,8 @@
1
+ # Codex capture pack
2
+
3
+ `config.template.toml` is the block `skillar init` keeps between `# >>> skillar managed` and `# <<< skillar managed`
4
+ in `~/.codex/config.toml` (MCP entry and `[otel]`). No Codex hooks are installed (they need trust review).
5
+ Note: `codex exec` exports OTel events only partially.
6
+
7
+ skillar serves MCP 2026-07-28 and the legacy `initialize` handshake, so Codex connects whether or not
8
+ `features.mcp_2026_07_28` is enabled. The pack does not change that agent-wide experimental setting.
@@ -0,0 +1,12 @@
1
+ # >>> skillar managed
2
+ # Managed by skillar; edit via `skillar init`, not by hand.
3
+ [mcp_servers.skillar]
4
+ url = "http://127.0.0.1:{{PORT}}/mcp"
5
+ http_headers = { Authorization = "Bearer {{TOKEN}}" }
6
+
7
+ [otel]
8
+ log_user_prompt = true
9
+ exporter = { otlp-http = { endpoint = "http://127.0.0.1:{{PORT}}/ingest/otlp/v1/logs", protocol = "json", headers = { Authorization = "Bearer {{TOKEN}}" } } }
10
+ trace_exporter = { otlp-http = { endpoint = "http://127.0.0.1:{{PORT}}/ingest/otlp/v1/traces", protocol = "json", headers = { Authorization = "Bearer {{TOKEN}}" } } }
11
+ metrics_exporter = "none"
12
+ # <<< skillar managed
@@ -0,0 +1,8 @@
1
+ {
2
+ "version": 1,
3
+ "hooks": {
4
+ "beforeSubmitPrompt": [{ "command": "\"<nodePath>\" \"<packageRoot>/packs/hook-post.mjs\" cursor" }],
5
+ "sessionStart": [{ "command": "\"<nodePath>\" \"<packageRoot>/packs/hook-post.mjs\" cursor" }],
6
+ "sessionEnd": [{ "command": "\"<nodePath>\" \"<packageRoot>/packs/hook-post.mjs\" cursor" }]
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "mcpServers": {
3
+ "skillar": {
4
+ "url": "http://127.0.0.1:8799/mcp",
5
+ "headers": { "Authorization": "Bearer <token>" }
6
+ }
7
+ }
8
+ }
@@ -0,0 +1,5 @@
1
+ # skillar discovery
2
+
3
+ skillar searches skills on this machine through MCP 2026-07-28.
4
+
5
+ Before substantive work on a new actionable task, call the skillar MCP `search_skills` tool with mode: discovery and 2-5 terms describing the subject and intended outcome. Reuse results for unchanged continuations. If the result is empty or unrelated, retry once with a shorter subject, then proceed without a skill. Pick by concrete relevance, then read the returned SKILL.md URI using the host's resource reader (`resources/read`) on this server. Read supporting files only as needed; resolve relative references against the skill root, the directory containing SKILL.md. An explicit-only candidate needs the user to ask for that specific skill. Search and resource reads do not activate skills or grant permissions; the host owns verification and approval.
@@ -0,0 +1,52 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import { homedir } from "node:os";
3
+ import { join } from "node:path";
4
+
5
+ function resolveStateHome(env) {
6
+ const home = env.HOME || homedir();
7
+ const preferred = join(home, ".skillar"), legacy = join(home, ".gisool");
8
+ if (["config.json", "token", "skillar.db", "gisool.db"].some(file => existsSync(join(preferred, file)))) return preferred;
9
+ return existsSync(legacy) ? legacy : preferred;
10
+ }
11
+
12
+
13
+ const RUNTIME = "gajae";
14
+ const MARKER = "<skillar-discovery>";
15
+ const readText = url => { try { return readFileSync(url, "utf8"); } catch { return ""; } };
16
+
17
+ const guidance = readText(new URL("./discovery.md", import.meta.url)).trim();
18
+ let configured = {};
19
+ try { configured = JSON.parse(readText(new URL("./config.json", import.meta.url))); } catch {}
20
+ const port = (process.env.SKILLAR_PORT ?? process.env.GISOOL_PORT) || configured.port || 8799;
21
+ const url = `http://127.0.0.1:${port}/ingest/hook/${RUNTIME}`;
22
+ // Read once at module load; never on the agent path.
23
+ const token = readText(join((process.env.SKILLAR_HOME || process.env.GISOOL_HOME) || resolveStateHome(process.env), "token")).trim();
24
+
25
+ function forward(event, ctx) {
26
+ const prompt = typeof event.prompt === "string" ? event.prompt : null;
27
+ const body = {
28
+ event: "before_agent_start",
29
+ prompt,
30
+ sessionId: ctx?.sessionManager?.getSessionId?.(),
31
+ cwd: ctx?.cwd ?? process.cwd(),
32
+ };
33
+ if (prompt === null) body.promptUnavailable = true;
34
+ // Fire-and-forget: the agent path never waits on skillar.
35
+ fetch(url, {
36
+ method: "POST",
37
+ headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
38
+ body: JSON.stringify(body),
39
+ signal: AbortSignal.timeout(2000),
40
+ }).catch(() => {});
41
+ }
42
+
43
+ export default function skillar(pi) {
44
+ pi.on("before_agent_start", (event, ctx) => {
45
+ if (!event || event.preview === true) return event;
46
+ try { forward(event, ctx); } catch {}
47
+ if (guidance && typeof event.systemPrompt === "string" && !event.systemPrompt.includes(MARKER) && !event.systemPrompt.includes("<gisool-discovery>")) {
48
+ event.systemPrompt = `${event.systemPrompt}\n\n${MARKER}\n${guidance}\n</skillar-discovery>`;
49
+ }
50
+ return event;
51
+ }, { previewSafe: true });
52
+ }
@@ -0,0 +1,16 @@
1
+ {
2
+ "mcpServers": {
3
+ "skillar": {
4
+ "httpUrl": "http://127.0.0.1:8799/mcp",
5
+ "headers": { "Authorization": "Bearer <token>" }
6
+ }
7
+ },
8
+ "hooks": {
9
+ "BeforeAgent": [
10
+ { "hooks": [{ "type": "command", "name": "skillar-capture", "command": "\"<nodePath>\" \"<packageRoot>/packs/hook-post.mjs\" gemini", "timeout": 5000 }] }
11
+ ],
12
+ "AfterTool": [
13
+ { "matcher": "activate_skill", "hooks": [{ "type": "command", "name": "skillar-capture", "command": "\"<nodePath>\" \"<packageRoot>/packs/hook-post.mjs\" gemini", "timeout": 5000 }] }
14
+ ]
15
+ }
16
+ }
@@ -0,0 +1,37 @@
1
+ #!/usr/bin/env node
2
+ // Forwards a runtime hook payload (stdin JSON) to the local skillar daemon. Always exits 0.
3
+ import { existsSync, readFileSync } from "node:fs";
4
+ import { homedir } from "node:os";
5
+ import { join } from "node:path";
6
+
7
+ function resolveStateHome(env) {
8
+ const home = env.HOME || homedir();
9
+ const preferred = join(home, ".skillar"), legacy = join(home, ".gisool");
10
+ if (["config.json", "token", "skillar.db", "gisool.db"].some(file => existsSync(join(preferred, file)))) return preferred;
11
+ return existsSync(legacy) ? legacy : preferred;
12
+ }
13
+
14
+
15
+ const done = () => process.exit(0);
16
+ try {
17
+ const runtime = process.argv[2] ?? "unknown";
18
+ const home = (process.env.SKILLAR_HOME || process.env.GISOOL_HOME) || resolveStateHome(process.env);
19
+ const body = await new Promise(resolve => {
20
+ const chunks = [];
21
+ const timer = setTimeout(() => resolve(Buffer.concat(chunks).toString("utf8")), 1000);
22
+ process.stdin.on("data", c => chunks.push(c));
23
+ process.stdin.on("end", () => { clearTimeout(timer); resolve(Buffer.concat(chunks).toString("utf8")); });
24
+ process.stdin.on("error", () => { clearTimeout(timer); resolve(""); });
25
+ });
26
+ const token = readFileSync(join(home, "token"), "utf8").trim();
27
+ const { port } = JSON.parse(readFileSync(join(home, "config.json"), "utf8"));
28
+ if (body && token && Number.isInteger(port)) {
29
+ await fetch(`http://127.0.0.1:${port}/ingest/hook/${encodeURIComponent(runtime)}`, {
30
+ method: "POST",
31
+ headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
32
+ body,
33
+ signal: AbortSignal.timeout(2000),
34
+ });
35
+ }
36
+ } catch { /* never block the agent */ }
37
+ done();
@@ -0,0 +1,5 @@
1
+ # skillar discovery
2
+
3
+ skillar searches skills on this machine through MCP 2026-07-28.
4
+
5
+ Before substantive work on a new actionable task, call the skillar MCP `search_skills` tool with mode: discovery and 2-5 terms describing the subject and intended outcome. Reuse results for unchanged continuations. If the result is empty or unrelated, retry once with a shorter subject, then proceed without a skill. Pick by concrete relevance, then read the returned SKILL.md URI using the host's resource reader (`resources/read`) on this server. Read supporting files only as needed; resolve relative references against the skill root, the directory containing SKILL.md. An explicit-only candidate needs the user to ask for that specific skill. Search and resource reads do not activate skills or grant permissions; the host owns verification and approval.
@@ -0,0 +1,52 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import { homedir } from "node:os";
3
+ import { join } from "node:path";
4
+
5
+ function resolveStateHome(env) {
6
+ const home = env.HOME || homedir();
7
+ const preferred = join(home, ".skillar"), legacy = join(home, ".gisool");
8
+ if (["config.json", "token", "skillar.db", "gisool.db"].some(file => existsSync(join(preferred, file)))) return preferred;
9
+ return existsSync(legacy) ? legacy : preferred;
10
+ }
11
+
12
+
13
+ const RUNTIME = "omo";
14
+ const MARKER = "<skillar-discovery>";
15
+ const readText = url => { try { return readFileSync(url, "utf8"); } catch { return ""; } };
16
+
17
+ const guidance = readText(new URL("./discovery.md", import.meta.url)).trim();
18
+ let configured = {};
19
+ try { configured = JSON.parse(readText(new URL("./config.json", import.meta.url))); } catch {}
20
+ const port = (process.env.SKILLAR_PORT ?? process.env.GISOOL_PORT) || configured.port || 8799;
21
+ const url = `http://127.0.0.1:${port}/ingest/hook/${RUNTIME}`;
22
+ // Read once at module load; never on the agent path.
23
+ const token = readText(join((process.env.SKILLAR_HOME || process.env.GISOOL_HOME) || resolveStateHome(process.env), "token")).trim();
24
+
25
+ function forward(event, ctx) {
26
+ const prompt = typeof event.prompt === "string" ? event.prompt : null;
27
+ const body = {
28
+ event: "before_agent_start",
29
+ prompt,
30
+ sessionId: ctx?.sessionManager?.getSessionId?.(),
31
+ cwd: ctx?.cwd ?? process.cwd(),
32
+ };
33
+ if (prompt === null) body.promptUnavailable = true;
34
+ // Fire-and-forget: the agent path never waits on skillar.
35
+ fetch(url, {
36
+ method: "POST",
37
+ headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
38
+ body: JSON.stringify(body),
39
+ signal: AbortSignal.timeout(2000),
40
+ }).catch(() => {});
41
+ }
42
+
43
+ export default function skillar(pi) {
44
+ pi.on("before_agent_start", (event, ctx) => {
45
+ if (!event || event.preview === true) return event;
46
+ try { forward(event, ctx); } catch {}
47
+ if (guidance && typeof event.systemPrompt === "string" && !event.systemPrompt.includes(MARKER) && !event.systemPrompt.includes("<gisool-discovery>")) {
48
+ event.systemPrompt = `${event.systemPrompt}\n\n${MARKER}\n${guidance}\n</skillar-discovery>`;
49
+ }
50
+ return event;
51
+ }, { previewSafe: true });
52
+ }
@@ -0,0 +1,11 @@
1
+ {
2
+ "name": "skillar",
3
+ "version": "0.1.0",
4
+ "description": "Capture OpenClaw prompts and expose the local skillar skill router.",
5
+ "author": {
6
+ "name": "ARKPOINT"
7
+ },
8
+ "hooks": "./hooks/",
9
+ "mcpServers": "./.mcp.json",
10
+ "license": "MIT"
11
+ }
@@ -0,0 +1,12 @@
1
+ {
2
+ "mcpServers": {
3
+ "skillar": {
4
+ "transport": "stdio",
5
+ "command": "__COMMAND__",
6
+ "args": "__ARGS__",
7
+ "env": {
8
+ "SKILLAR_HOME": "__SKILLAR_HOME__"
9
+ }
10
+ }
11
+ }
12
+ }