skillar 0.2.0 → 0.2.1

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 (2) hide show
  1. package/README.md +123 -67
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,76 +1,58 @@
1
- # skillar
1
+ <h1 align="center">skillar</h1>
2
+ <p align="center"><strong>Find your local skills. See how your agents use them.</strong></p>
3
+ <p align="center"><a href="https://github.com/changeroa/skillar/blob/main/README.md">Project overview</a> · <a href="https://github.com/changeroa/skillar/blob/main/README.ko.md">한국어</a></p>
4
+ <p align="center">
5
+ <a href="https://www.npmjs.com/package/skillar"><img src="https://img.shields.io/npm/v/skillar?color=c44b2b&amp;label=npm" alt="npm version"></a>
6
+ <a href="https://github.com/changeroa/skillar/blob/main/local/package.json"><img src="https://img.shields.io/badge/Node.js-%E2%89%A524.15-333333" alt="Node.js 24.15 or newer"></a>
7
+ <a href="https://github.com/changeroa/skillar/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-333333" alt="MIT license"></a>
8
+ </p>
9
+ <p align="center"><img src="https://raw.githubusercontent.com/changeroa/skillar/main/docs/assets/gisul-workshop.png" width="960" alt="An articulated arm selects an instruction card from a cabinet and brings it to a workbench. Black ink and vermilion on warm ivory."></p>
2
10
 
3
- [Upgrade and compatibility notes](https://github.com/changeroa/skillar/blob/main/docs/migration-skillar.md).
4
- skillar is a local skill router. One daemon on `127.0.0.1` indexes the `SKILL.md` folders already on your machine,
5
- serves them over MCP through `search_skills` and standard `resources/read`, records which skills
6
- each agent session searched, loaded, and read, and shows that history in a local dashboard.
11
+ skillar is a local skill router for coding agents. One daemon on `127.0.0.1` indexes your existing `SKILL.md` folders, serves them over MCP, and records searches and reads in a local dashboard. Skill files stay in place.
7
12
 
8
- Capture packs cover Claude Code, Codex, Gemini CLI, Cursor, OmO, Gajae Code, and OpenClaw.
9
- MCP connections accept revision 2026-07-28 and, for older clients, the legacy `initialize` handshake
10
- (revisions 2024-11-05 through 2025-11-25, e.g. clients built on `@modelcontextprotocol/sdk` 1.x). Reading skill
11
- bodies needs a host resource reader. Packs configure endpoints and capture hooks only.
13
+ [Install](#install) · [Connect your agents](#connect-your-agents) · [Settings](#settings) · [MCP reference](#skills-over-mcp)
12
14
 
13
- ## Skills over MCP
14
-
15
- The server implements stable SEP-2640: `server/discover` advertises `tools`, `resources`, and
16
- `extensions["io.modelcontextprotocol/skills"]`. `search_skills` is the only tool. Use it to choose a candidate,
17
- then read the returned `SKILL.md` URI through the host's resource reader on this server. Relative references
18
- resolve against the skill root (the directory containing `SKILL.md`); supporting files are read only as needed.
19
- `skills/list` and `skills/get` provide verbatim frontmatter and complete per-file SHA-256/size manifests.
20
- The optional directory-read feature is not advertised; directories can be inferred from the manifest.
21
-
22
- Every request, including `server/discover`, carries `params._meta` with
23
- `io.modelcontextprotocol/protocolVersion: "2026-07-28"` and
24
- `io.modelcontextprotocol/clientCapabilities: {}`. Include `io.modelcontextprotocol/clientInfo`
25
- with `{name, version}` for runtime attribution. HTTP additionally requires `MCP-Protocol-Version`,
26
- `Mcp-Method`, and (for tool calls and resource reads) `Mcp-Name`, matching the body.
27
- Use `Accept: application/json, text/event-stream` and the bearer token.
28
- Modern requests need no initialization handshake or protocol session; GET and DELETE on `/mcp` return 405.
29
- The stdio proxy forwards modern requests unchanged.
15
+ ## Install
30
16
 
31
- ### Legacy clients (before 2026-07-28)
17
+ Requires **Node.js 24.15+** on **macOS or Linux**.
32
18
 
33
- The server is dual-era. A request without modern `_meta` and without a modern `MCP-Protocol-Version` header
34
- is served under legacy semantics: `initialize` negotiates the requested revision (or answers `2025-11-25`
35
- for unknown ones) with the same capabilities and instructions as `server/discover`. Over HTTP it returns an
36
- `Mcp-Session-Id` whose only state is `clientInfo` for runtime attribution; unknown session IDs (e.g. after a
37
- daemon restart) are served anonymously instead of rejected. Over stdio the proxy keeps `clientInfo` for the
38
- process. Legacy results omit `resultType`, `ttlMs`, `cacheScope`, and the `serverInfo` `_meta`; legacy HTTP
39
- errors are JSON-RPC errors with status 200. `ping` and an empty `resources/templates/list` are answered.
40
- The deprecated HTTP+SSE transport (GET stream) is not offered, so 2024-11-05 clients connect over stdio.
19
+ > **Existing gisool installation?** Follow the [safe migration guide](https://github.com/changeroa/skillar/blob/main/docs/migration-skillar.md) **before installing**. The packages share the `gisool` executable, so a direct global install fails with `EEXIST`. Preserve your state and perform the controlled package handoff; do not use `--force`.
41
20
 
42
- All cacheable results include `resultType: "complete"`, `ttlMs: 60000`, and `cacheScope: "private"`.
43
- List methods use opaque `cursor`/`nextCursor` pagination. The search tool uses its own `offset`/`limit`.
44
- Tool schemas use JSON Schema 2020-12. Search is limited to 120 invocations per minute per daemon.
21
+ For a fresh installation:
45
22
 
46
- The catalog rejects invalid Agent Skills names/frontmatter and skills above 512 files or 16 MiB.
47
- Manifests include dotfiles, dependencies, and nested skills. Skills containing symlinks or other non-regular
48
- entries are rejected rather than served incompletely. Duplicate names are retained at distinct URIs so
49
- hosts can disambiguate their configured roots.
23
+ ```sh
24
+ npm install -g skillar
25
+ skillar init --dry-run # review configuration and service changes
26
+ skillar init # connect detected runtimes and start the background service
27
+ skillar open # view the local dashboard
28
+ ```
50
29
 
51
- A `resources/read` of a published `SKILL.md` is recorded as a dashboard `load` observation; other files
52
- produce `read_file` observations. These do **not** activate skills, confer approval, or grant execution permissions.
53
- Hosts own origin binding, integrity verification, consent, and activation. To join reads to a search, send
54
- its `trace_id` as `_meta["app.skillar/traceId"]`; ordinary vendor session metadata also preserves attribution.
55
- No prior read or connection is required. A changed file fails closed until the catalog refreshes; the host
56
- refreshes `skills/get` and verifies against the new manifest before use.
30
+ The package installs `skillar` and the compatibility command `gisool`. For source installation, see [Develop](#develop).
57
31
 
58
- For Codex builds with gated modern support, enable `features.mcp_2026_07_28` for third-party HTTP servers;
59
- the separate hosted Apps flag does not apply to skillar. Client-wide experimental flags are not edited by the pack.
32
+ ## What you get
60
33
 
61
- **Privacy: everything stays on this machine.** The daemon listens on `127.0.0.1` only, every MCP, ingest, and API
62
- request needs the local bearer token, and nothing is sent to any remote service. Prompts, search queries, and skill
63
- usage are stored in a SQLite database under `~/.skillar/`.
34
+ | Capability | How it works |
35
+ | --- | --- |
36
+ | Local discovery | `search_skills` returns ranked candidates from skill roots already on your machine. |
37
+ | On-demand reads | Hosts read the chosen `SKILL.md` and supporting files with MCP `resources/read`. |
38
+ | Session history | Review searches, loads, supporting reads, native-use observations, and dashboard flows. |
39
+ | Reversible setup | Preview configuration changes, keep per-run backups, and roll back with `init`. |
64
40
 
65
- ## Install
41
+ ## Supported runtimes
66
42
 
67
- Requires Node.js 24.15 or newer on macOS or Linux.
43
+ | Runtime | `--runtime` ID |
44
+ | --- | --- |
45
+ | Claude Code | `claude-code` |
46
+ | Codex | `codex` |
47
+ | Gemini CLI | `gemini` |
48
+ | Cursor | `cursor` |
49
+ | OmO | `omo` |
50
+ | Gajae Code | `gajae` |
51
+ | OpenClaw | `openclaw` |
68
52
 
69
- ```sh
70
- npm --prefix local ci && npm --prefix local run build && npm link ./local
71
- ```
53
+ Packs configure MCP endpoints and runtime-specific telemetry or capture hooks. Capture coverage varies by runtime; the [tracing guide](https://github.com/changeroa/skillar/blob/main/local/docs/skill-tracing.md) documents what is observed and the herdr requirement for pane/session tracing.
72
54
 
73
- This puts the `skillar` command on your `PATH`.
55
+ Both modern MCP revision **2026-07-28** and the legacy `initialize` handshake are supported. Reading skill bodies requires a host resource reader. See the [protocol reference](#skills-over-mcp) for compatibility and transport limits.
74
56
 
75
57
  ## Connect your agents
76
58
 
@@ -80,8 +62,8 @@ Preview what would change, without writing anything:
80
62
  skillar init --dry-run
81
63
  ```
82
64
 
83
- The dry run prints a diff for every runtime config skillar would touch (MCP registration, OpenTelemetry export to the
84
- daemon, capture hooks) and the service it would install. Then apply it:
65
+ The dry run prints a diff for each runtime configuration it would change and the service it would install.
66
+ Depending on the runtime, changes include MCP registration, telemetry export, or capture hooks. Then apply it:
85
67
 
86
68
  ```sh
87
69
  skillar init # every detected runtime
@@ -113,6 +95,14 @@ skillar open # opens the browser
113
95
  skillar open --print # prints the URL only
114
96
  ```
115
97
 
98
+ Manage the background service:
99
+
100
+ ```sh
101
+ skillar service status
102
+ skillar service install
103
+ skillar service remove
104
+ ```
105
+
116
106
  Check the installation:
117
107
 
118
108
  ```sh
@@ -131,7 +121,7 @@ skillar eval --cases cases.json --json
131
121
 
132
122
  herdr is required for skill tracing; `skillar doctor` checks its socket connection. skillar joins agent sessions
133
123
  to panes and compares observed skill use with registered workflows without restricting agents.
134
- See [Skill tracing](docs/skill-tracing.md) for capture details, attribution limits, and the orchestrator protocol.
124
+ See [Skill tracing](https://github.com/changeroa/skillar/blob/main/local/docs/skill-tracing.md) for capture details, attribution limits, and the orchestrator protocol.
135
125
 
136
126
  ## Export and import
137
127
 
@@ -148,7 +138,9 @@ Import never overwrites existing settings. Run `skillar init` afterwards to conn
148
138
 
149
139
  ## Settings
150
140
 
151
- `~/.skillar/config.json` (created on first run, mode 0600; `SKILLAR_HOME` moves the whole directory):
141
+ `~/.skillar/config.json` (created on first run, mode 0600). `SKILLAR_HOME` selects a different home; it does not move existing data. Legacy home/database selection follows the [migration guide](https://github.com/changeroa/skillar/blob/main/docs/migration-skillar.md#local-state-and-configuration).
142
+
143
+ Example settings:
152
144
 
153
145
  ```json
154
146
  {
@@ -162,7 +154,7 @@ Import never overwrites existing settings. Run `skillar init` afterwards to conn
162
154
 
163
155
  - `captureLevel` controls how prompt and search text is stored:
164
156
  - `full` (default): the text as sent.
165
- - `redacted`: secrets (tokens, keys, passwords) are masked and the text is cut to 2048 characters.
157
+ - `redacted`: recognized secrets (tokens, keys, passwords) are masked and the text is cut to 2048 characters.
166
158
  - `metadata`: no text at all, only its SHA-256 digest and length. The dashboard shows "prompt not captured".
167
159
  - `retentionDays`: `null` keeps history forever; a number deletes sessions older than that many days at startup and
168
160
  once a day.
@@ -176,20 +168,84 @@ Restart the daemon after editing the config.
176
168
 
177
169
  | Path | Purpose |
178
170
  | --- | --- |
179
- | `~/.skillar/config.json` | settings above |
171
+ | `~/.skillar/config.json` | settings above (paths below show a fresh installation) |
180
172
  | `~/.skillar/token` | bearer token (0600) shared with the runtime configs |
181
- | `~/.skillar/skillar.db` | SQLite store: skills index, sessions, events, loads |
173
+ | `~/.skillar/skillar.db` | SQLite store: skills index, sessions, events, loads; legacy `gisool.db` stays in place |
182
174
  | `~/.skillar/logs/daemon.log` | daemon log, rotated at 5 MB |
183
175
  | `~/.skillar/backups/` | per-run backups used by `skillar init --rollback` |
184
176
 
177
+ ## Privacy
178
+
179
+ The local daemon stores its index and telemetry locally and does not upload captured telemetry. Connected agents and their model providers handle data separately. It listens on `127.0.0.1` only; MCP, ingest, and API requests require the local bearer token (the dashboard also uses a local authenticated cookie). Prompts, search queries, and skill usage are stored in the selected local SQLite store.
180
+
181
+ Capture defaults to `full`. Use the [settings](#settings) to select `redacted` or `metadata` and set retention. Redaction masks recognized secret patterns; it does not guarantee every secret is removed. Capture levels do not anonymize session IDs or paths.
182
+
183
+ ## Skills over MCP
184
+
185
+ The server implements stable SEP-2640: `server/discover` advertises `tools`, `resources`, and
186
+ `extensions["io.modelcontextprotocol/skills"]`. `search_skills` is the only tool. Use it to choose a candidate,
187
+ then read the returned `SKILL.md` URI through the host's resource reader on this server. Relative references
188
+ resolve against the skill root (the directory containing `SKILL.md`); supporting files are read only as needed.
189
+ `skills/list` and `skills/get` provide verbatim frontmatter and complete per-file SHA-256/size manifests.
190
+ The optional directory-read feature is not advertised; directories can be inferred from the manifest.
191
+
192
+ For modern requests, every call, including `server/discover`, carries `params._meta` with
193
+ `io.modelcontextprotocol/protocolVersion: "2026-07-28"` and
194
+ `io.modelcontextprotocol/clientCapabilities: {}`. Include `io.modelcontextprotocol/clientInfo`
195
+ with `{name, version}` for runtime attribution. HTTP additionally requires `MCP-Protocol-Version`,
196
+ `Mcp-Method`, and (for tool calls and resource reads) `Mcp-Name`, matching the body.
197
+ Use `Accept: application/json, text/event-stream` and the bearer token.
198
+ Modern requests need no initialization handshake or protocol session; GET and DELETE on `/mcp` return 405.
199
+ The stdio proxy forwards modern requests unchanged.
200
+
201
+ ### Legacy clients (before 2026-07-28)
202
+
203
+ The server is dual-era. A request without modern `_meta` and without a modern `MCP-Protocol-Version` header
204
+ is served under legacy semantics: `initialize` negotiates the requested revision (or answers `2025-11-25`
205
+ for unknown ones) with the same capabilities and instructions as `server/discover`. Over HTTP it returns an
206
+ `Mcp-Session-Id` whose only state is `clientInfo` for runtime attribution; unknown session IDs (e.g. after a
207
+ daemon restart) are served anonymously instead of rejected. Over stdio the proxy keeps `clientInfo` for the
208
+ process. Legacy results omit `resultType`, `ttlMs`, `cacheScope`, and the `serverInfo` `_meta`; legacy HTTP
209
+ errors are JSON-RPC errors with status 200. `ping` and an empty `resources/templates/list` are answered.
210
+ The deprecated HTTP+SSE transport (GET stream) is not offered, so 2024-11-05 clients connect over stdio.
211
+
212
+ All cacheable results include `resultType: "complete"`, `ttlMs: 60000`, and `cacheScope: "private"`.
213
+ List methods use opaque `cursor`/`nextCursor` pagination. The search tool uses its own `offset`/`limit`.
214
+ Tool schemas use JSON Schema 2020-12. Search is limited to 120 invocations per minute per daemon.
215
+
216
+ The catalog rejects invalid Agent Skills names/frontmatter and skills above 512 files or 16 MiB.
217
+ Manifests include dotfiles, dependencies, and nested skills. Skills containing symlinks or other non-regular
218
+ entries are rejected rather than served incompletely. Duplicate names are retained at distinct URIs so
219
+ hosts can disambiguate their configured roots.
220
+
221
+ A `resources/read` of a published `SKILL.md` is recorded as a dashboard `load` observation; other files
222
+ produce `read_file` observations. These do **not** activate skills, confer approval, or grant execution permissions.
223
+ Hosts own origin binding, integrity verification, consent, and activation. To join reads to a search, send
224
+ its `trace_id` as `_meta["app.skillar/traceId"]`; ordinary vendor session metadata also preserves attribution.
225
+ No prior read or connection is required. A changed file fails closed until the catalog refreshes; the host
226
+ refreshes `skills/get` and verifies against the new manifest before use.
227
+
228
+ For Codex builds with gated modern support, enable `features.mcp_2026_07_28` for third-party HTTP servers;
229
+ the separate hosted Apps flag does not apply to skillar. Client-wide experimental flags are not edited by the pack.
230
+
185
231
  ## Develop
186
232
 
233
+ From a repository checkout (run these at the repository root):
234
+
187
235
  ```sh
236
+ npm --prefix local ci
188
237
  npm --prefix local run build
238
+ npm link ./local # make the built CLI available locally
189
239
  npm --prefix local run typecheck
190
240
  npm --prefix local test # unit tests plus test/e2e, which spawns the real daemon in a sandbox HOME
191
241
  node local/bench/search.mjs --check
192
242
  node local/bench/mcp-mutations.mjs # each regression is injected in memory; files stay unchanged
193
243
  ```
194
244
 
195
- Architecture: [docs/skillar.md](../docs/skillar.md).
245
+ Architecture: [daemon and storage design](https://github.com/changeroa/skillar/blob/main/docs/skillar.md).
246
+
247
+ ## More documentation
248
+
249
+ [Project overview](https://github.com/changeroa/skillar/blob/main/README.md) · [Upgrade & compatibility](https://github.com/changeroa/skillar/blob/main/docs/migration-skillar.md) · [MIT license](https://github.com/changeroa/skillar/blob/main/LICENSE)
250
+
251
+ The former personal Cloudflare deployment is retired. The local CLI needs no hosted service; separate registry and organization deployment context is covered in the [project documentation](https://github.com/changeroa/skillar/blob/main/README.md#remote-registry-and-team-distribution).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "skillar",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "private": false,
5
5
  "description": "Local skill router for coding agents: search your skills, trace how agents use them, and see the flow.",
6
6
  "license": "MIT",