Skillar

What is Skillar about?

Skillar provides a personal MCP skill registry that discovers existing SKILL.md directories on a developer's machine, captures searches and file reads performed by coding agents, and presents the activity in a local web dashboard. The system runs as a background daemon listening on 127.0.0.1:8799 and stores all data in SQLite, keeping everything private unless the user chooses to expose it via a self‑hosted Cloudflare Worker registry.

How to use Skillar?

1. Install the CLI

   npm install -g skillar   # or use npx for a one‑off run
   

2. Initialize – Detect runtimes, create launch agents (macOS) or systemd units (Linux), and start the daemon:

   skillar init            # preview first with --dry-run if desired
   

3. Open the dashboard

   skillar open            # launches the local UI in the default browser
   

4. Interact via MCP – Agents call the standard search_skills and resources/read endpoints; Skillar returns ranked candidates and records the read as evidence.
5. Manage – Use skillar doctor, skillar export/import, skillar eval, and rollback commands to maintain or troubleshoot the installation.

Key features of Skillar

• Zero‑copy indexing of existing skill roots; no file modifications required.
• MCP‑compliant daemon listening on loopback, protected by a bearer token.
• SQLite storage for prompts, searches, reads, and timestamps with configurable retention and redaction levels.
• Local dashboard showing search quality, session flow, and activity heat‑maps.
• Multi‑runtime support (Claude Code, Codex, Gemini CLI, Cursor, OmO, Gajae Code, OpenClaw) with automatic detection.
• Privacy‑first defaults – data never leaves the host unless the optional Cloudflare Worker registry is self‑hosted.
• CLI utilities for backup, restore, evaluation, and service management.
• Self‑hosting templates for a Node.js registry and Cloudflare Worker that implement SEP‑2640 Skills Extension.

Use cases of Skillar

• Personal knowledge base for developers who maintain multiple SKILL.md libraries across projects.
• Agent observability – trace which skills an AI coding assistant consulted during a code‑generation session.
• Team skill sharing – host a private Cloudflare Worker registry to distribute curated skill bundles within an organization.
• Compliance audits – retain searchable logs of skill reads with optional redaction for secret handling.
• Performance tuning – evaluate search relevance (skillar eval) and adjust capture levels or indexing strategy.

Frequently Asked Questions

Q: Do I need an internet connection? A: No. All indexing, searching, and storage happen locally. The optional Cloudflare Worker is only needed for remote team distribution.

Q: Can I run the daemon in the foreground? A: Yes. Use skillar init --no-service then skillar serve to start it manually.

Q: How is sensitive data protected? A: The daemon stores data in a SQLite file with permissions 0600. Capture can be set to redacted or metadata to mask or omit the actual text.

Q: Which runtimes are supported out of the box? A: Claude Code, Codex, Gemini CLI, Cursor, OmO, Gajae Code, and OpenClaw. Additional runtimes can be added via plugins.

Q: How do I migrate from the previous gisool package? A: Follow the migration guide (docs/migration-skillar.md) – it explains backup, removal of the old global command, and handoff to the new skillar package.

Q: Can I disable remote registry integration? A: Yes. Run skillar init --disable-remote to prevent runtimes from attempting remote skill registration.

Connect the SKILL.md folders already on your machine to your coding agents. skillar searches them over MCP, records what each session searched and read, and makes that history visible in a local dashboard.

Index in place · Read on demand · Keep history local

Quick start · Supported runtimes · Privacy · CLI & configuration

Hosting the site or Workers yourself? Use the deployment templates and private configuration setup.

Quick start

macOS or Linux · Node.js 24.15+

Upgrading from gisool? Read the migration guide before installing. Both packages own the gisool command; a direct global install collides. Follow the stop, backup, and package-handoff steps rather than using --force.

For a fresh installation:

npm install -g skillar
skillar init --dry-run    # preview config and service changes; write nothing
skillar init              # connect detected runtimes and install the background service
skillar open              # open the local dashboard

init installs a LaunchAgent on macOS or a systemd user unit on Linux. The daemon listens on 127.0.0.1:8799. Prefer a foreground process? Run skillar init --no-service, then skillar serve.

Already using skillar? skillar doctor checks your installation. For a source checkout, see development setup.

From a skill folder to a session trace

Step	What happens
Discover	Index existing skill roots without copying or editing their files. Agents search with search_skills and receive ranked candidates.
Read	The host reads the chosen SKILL.md and supporting files through standard MCP resources/read. Reading is evidence, not permission to execute.
Trace	Inspect sessions, search candidates, skill reads, task → skill → outcome flows, and activity by weekday and hour in the dashboard.

Capture can also observe skills used natively when runtime hooks or telemetry report them. Skill tracing explains attribution, evidence limits, and the herdr requirement for pane/session tracing. Core MCP serving and session collection continue if herdr is unavailable.

Supported runtimes

Runtime	--runtime ID
Claude Code	claude-code
Codex	codex
Gemini CLI	gemini
Cursor	cursor
OmO	omo
Gajae Code	gajae
OpenClaw	openclaw

init detects installed runtimes. Select a subset with skillar init --runtime codex,claude-code. Packs configure MCP and runtime-specific telemetry or capture hooks; capture coverage varies by runtime.

Both MCP revision 2026-07-28 and the legacy initialize handshake are supported. Skill bodies require a host resource reader. See protocol and compatibility for headers, stdio, and legacy transport limits.

Privacy and storage

The local daemon stores prompts, searches, loads, and supporting-file reads in SQLite. It listens on loopback only, protects MCP, ingest, and API requests with a local bearer token, and does not upload captured telemetry. The dashboard uses a local authenticated cookie. Connected agents and their model providers handle data separately.

Choose what to retain in ~/.skillar/config.json:

Setting	Behavior
captureLevel: "full"	Store captured text as sent (default).
captureLevel: "redacted"	Mask recognized secrets and truncate text to 2,048 characters; this does not guarantee every secret is removed.
captureLevel: "metadata"	Keep text digests and lengths, without the text.
retentionDays	Delete old sessions; null keeps history.

Fresh installs use ~/.skillar/; SKILLAR_HOME selects another home. Existing legacy homes and databases are reused according to the migration rules.

Path in the selected home	Purpose
config.json	Port, capture level, retention, and skill roots
token	Local bearer token, mode 0600
skillar.db	Skill index, sessions, events, and loads; existing gisool.db stays in place
logs/daemon.log	Daemon log
backups/	Per-run configuration backups for rollback

Keep your setup portable

skillar doctor                                  # check daemon, service, index, capture, and herdr
skillar doctor --json
skillar init --rollback                         # undo the newest init run
skillar init --rollback --all                    # undo every run
skillar export ~/skillar-backup                  # settings only
skillar export ~/skillar-backup --with-history   # include sessions, events, and loads
skillar import ~/skillar-backup --dry-run        # preview; existing keys are kept
skillar eval                                    # measure search quality

Use skillar open --print to print the dashboard URL without opening a browser. See the CLI guide for import, service management, settings, and protocol details.

Documentation

Guide	Use it for
Local CLI & MCP	Installation, commands, settings, and protocol reference
Upgrade & compatibility	Safe package handoff, legacy homes, commands, and identities
Skill tracing	Capture coverage, herdr joins, attribution, and evidence limits
Architecture	Daemon, storage, ingest, and API design

Remote registry and team distribution

The local CLI needs no hosted registry. This repository also contains a separate Node.js registry (server/, stdio or Streamable HTTP) and a Cloudflare Worker (worker/) for authenticated distribution from private R2 immutable releases. They implement the SEP-2640 Skills Extension.

The former personal Cloudflare deployment was retired on 2026-10-29. Historical addresses are not maintained endpoints; organization deployments are separate external resources. Self-hosting requires your own configuration and release validation. skillar init --disable-remote can disable a remote registration in connected runtimes.

Runtime	Integration
Codex	Self-hosted team HTTPS + OAuth plugin · Codex client
oh-my-openagent / OmO 5 (omo-ai)	OAuth stdio bridge and discovery extension
Gajae Code (gjc)	OAuth stdio bridge and workflow integration
OpenClaw	OAuth stdio bridge and bootstrap discovery hook

The Worker uses SKILLS_BUCKET, a reader SKILLAR_BEARER_TOKEN, and a separate SKILLAR_PUBLISH_TOKEN for publication. server/ops/ contains new-install templates, not live credentials or proof of an active deployment.

Deployment, immutable release format, rollback, and production gates · Self-hosted team setup · Historical session handoff

Contributing

With Node.js 24 and npm, run node scripts/verify.mjs from the checkout to perform the same locked installs, builds, tests, search and plugin checks, and Worker dry-runs as CI. It does not deploy or publish content.

License

Skillar is open source: server/ and worker/ use AGPL-3.0-only; the local CLI (local/), client integrations (clients/), and other project files remain MIT under the root license.

server/ and worker/ are AGPL-3.0-only from the commit introducing LICENSING.md forward. Copies obtained earlier, including earlier released versions, keep their MIT terms; existing MIT permissions cannot be revoked. See the licensing map for scope and details.

The name comes from 기술 — Korean for skill, craft, or technique.