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.
- package/README.md +123 -67
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,76 +1,58 @@
|
|
|
1
|
-
|
|
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&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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
17
|
+
Requires **Node.js 24.15+** on **macOS or Linux**.
|
|
32
18
|
|
|
33
|
-
|
|
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
|
-
|
|
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
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
62
|
-
|
|
63
|
-
|
|
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
|
-
##
|
|
41
|
+
## Supported runtimes
|
|
66
42
|
|
|
67
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
84
|
-
|
|
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
|
|
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: [
|
|
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).
|