Skip to content

Editors and agents

skif runs as a server for the tools you write code with. The servers and watch mode are part of the skif binary; nothing else to install. The design is recorded in ADR 0013.

The repository ships an agent skill that teaches a coding agent when and how to run skif: the lint, triage and fix loop, reading the JSON report, configuring skif.toml, migrating from sherif, syncpack and knip, and CI. It lives in skills/skif and is installed straight from GitHub. The skill runs the skif command, so install skif as well (or let the agent use npx @polylint/skif).

Any agent that reads Agent Skills, with the skills installer:

Terminal window
npx skills add polylint/skif

As a plugin, in Claude Code (in the session, not the shell):

/plugin marketplace add polylint/skif
/plugin install skif@skif

or, from Claude Code 2.1.275 on, /plugin install skif --marketplace polylint/skif in one step.

Codex:

Terminal window
codex plugin marketplace add polylint/skif
codex plugin add skif@skif

Factory Droid:

Terminal window
droid plugin marketplace add https://github.com/polylint/skif
droid plugin install skif@skif

GitHub Copilot CLI:

Terminal window
copilot plugin marketplace add polylint/skif
copilot plugin install skif@skif

The plugin holds the skill and registers the MCP server as skif, started with npx -y @polylint/skif@<version> mcp, where <version> is the release the plugin documents. The server needs Node.js 22 or later with npm on PATH, not an install of skif; its first start downloads the npm package. Without npm the server fails to start and the skill still works. The plugin’s version is the skif release it documents, so a plugin manager that updates on a version change picks up each release, and its server with it. The design is recorded in ADR 0013.

skif mcp is a Model Context Protocol server on stdio. Each tool runs one command with --format json and returns the document it prints, as structured content and as compact JSON text. An argument is the flag of the same name (max_show_issues is --max-show-issues), parsed by the command line itself, so a bad value gets the command’s own message.

Tool Command Arguments
lint skif path (default .), recursive, config, no_config, include, exclude, workspace, production, strict, no_js, max_show_issues; fix, fix_unsafe, fix_type, select, allow_remove_files plan fixes as --dry-run does and add fix.changes
explain_usage skif explain-usage file, export, or dependency with package; path (default .), production, config, no_config
config skif config path, recursive, explain with package, config, no_config; without explain it is --show
list_rules skif rules none

Paths, file included, are relative to the directory the server was started in, so start it in the repository. Problems in the project are the report, not an error. A command that exits 2 gives a result flagged isError: the JSON error document with its kind and message, or, when roots of a recursive run failed, the report with its errors. The server never writes a file: to apply fixes, run skif --fix.

The server handles one call at a time: a lint of a large monorepo holds every later request until it finishes, and cancelling a call does not stop it. A message longer than 64 MiB is refused.

Claude Code:

Terminal window
claude mcp add skif -- skif mcp

Clients configured with an mcpServers object, such as Cursor’s .cursor/mcp.json and Claude Desktop (VS Code’s .vscode/mcp.json names the object servers):

{
"mcpServers": {
"skif": { "command": "skif", "args": ["mcp"] }
}
}

With the npm package and no global install, use "command": "npx", "args": ["-y", "@polylint/skif", "mcp"]; the plugin registers this form, pinned to its release. The server speaks the protocol revisions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

skif --watch [PATH] lints, then lints again whenever a file below the root changes, until you press Ctrl-C. Every other lint flag applies to each run. With human output on a terminal the screen is cleared before each run; with --format json stdout holds one JSON document per run. Several --format FORMAT=FILE reports can be written per run; the watcher ignores the files it writes itself (those and --output), so they do not start another run.

The watcher checks the files below the root every 200 milliseconds (longer in a repository whose scan takes longer), skips node_modules, .git and target, and honours .gitignore, so build output does not trigger a run. A run starts once the tree has been quiet for 100 milliseconds, so a branch switch or a formatter that touches many files causes one run. Each check walks the tree and reads the size and modification time of every file, so it costs more in a large repository; the interval stretches to twice the time a scan takes, which keeps the watcher to at most about a third of one core. When the configuration cannot be read, the error is printed and the watcher keeps going, so the next save of skif.toml runs again. --watch cannot be combined with --fix or --fix-unsafe.

With --performance or SKIF_TIMINGS=1, the phase timings of each run are written to stderr when the run ends. skif lsp and skif mcp with SKIF_TIMINGS=1 write them after each message or request.

Parsing source files is the largest part of a JavaScript analysis. skif keeps the parse result of each file under a key of its file name, its text and the parser’s version, so an unchanged file is not parsed again and a changed file always is: the cache never changes a report. Everything else (configuration, manifests, the module graph, the rules) is computed on every run. The design is recorded in ADR 0007.

  • skif --cache keeps the results between runs in node_modules/.cache/skif/modules.bin below the workspace root (or below the invocation directory of a multi-root run, and in $TEST_TMPDIR/skif/ under bazel test); --cache-location <DIR> puts the file elsewhere. The file is written after a run only when its entries changed, and it holds exactly the files that run parsed, so it does not grow with edits; a narrower run (--production, one root of several) drops the entries it did not use. A damaged file, or one written by another skif version, is ignored and replaced. If the file cannot be written, skif prints a warning and the exit code is unchanged. A warm run still reads every file, so the gain is the parse share of a run, which --performance shows as js parse beside js module cache: H hits, M misses, W waits.
  • skif -r without --cache keeps one cache in memory for the run, shared by its roots, for the files more than one root can reach: files outside the root parsing them (shared code outside every root) and files of a root nested in it. Such a file is parsed once, not once per root; each root parses its own files without the cache, so roots that share no code keep nothing in it. With --cache every file is shared the same way. Roots linted in parallel wait for a parse already under way rather than repeating it; --performance counts those lookups as waits and reports their time as js parse wait.
  • --watch keeps the cache in memory across its runs (with --cache also on disk, written after each run).
  • skif lsp and skif mcp keep one in memory per project, for as long as the server runs; they never read or write modules.bin.

skif lsp is a minimal Language Server Protocol server on stdio. When the editor opens or saves a file, skif lints the project that contains it and publishes the diagnostics of every file of that project, with the rule ID as the code and skif as the source; a file whose findings are gone gets an empty list.

It lints what the editor holds, not only what is saved: the open documents’ unsaved text replaces the files on disk for the lint, so a manifest, pnpm-workspace.yaml, skif.toml or source file is linted as you type. The server asks for the full text on every change (textDocumentSync.change: 1) and lints a project 250 milliseconds after its last change, so a burst of keystrokes causes one lint; opening or saving a file lints at once, and so does closing a file without saving its changes, since the file on disk counts again. While a lint runs the server answers nothing else. A new file that was never saved is not linted until it exists on disk, and files changed outside the editor are seen on the next lint of their project. Each project keeps an in-memory module cache, so a lint parses only the files that changed.

The fixes of the last lint are offered as code actions, planned exactly as skif --fix --dry-run plans them, and the editor applies them; the server writes nothing.

  • Quick fixes. Each fix of a diagnostic under the cursor is a quickfix with the fix’s title. A safe fix that is the diagnostic’s only fix is marked preferred. An unsafe fix (one that skif --fix leaves to --fix-unsafe) is offered too, with (unsafe) after its title and never preferred: choosing it is the explicit consent the flag stands for. A diagnostic with several alternatives gets one action per alternative.
  • Fix all. source.fixAll.skif applies every safe fix of the file’s diagnostics in one edit, taking the alternative [policy] prefer names where there are several, as a non-interactive skif --fix does. Editors run it from a “fix all” command or on save; in VS Code, "editor.codeActionsOnSave": { "source.fixAll.skif": "explicit" }.

A fix that creates or deletes a file (such as the unused-files fix) is not offered: deleting files stays a command-line opt-in (--allow-remove-files). A fix for a document with unsaved changes edits the text the editor holds. It is offered only while every open document it edits still has the text the last lint read; after a further change it waits for the next lint. When the editor supports documentChanges in a workspace edit, the edit of an open document carries the document’s version, so the editor refuses it if the text changed in between.

A message larger than 64 MiB, or one whose header the server cannot read, ends the session: skif prints the reason to stderr and exits with code 1, and the editor can restart it.

There is no skif editor extension (ADR 0013). Any editor that can start a language server for JSON files can run it; VS Code needs a generic language-server client extension for that. For example Neovim:

vim.lsp.config("skif", {
cmd = { "skif", "lsp" },
filetypes = { "json", "javascript", "typescript" },
root_markers = { "package.json" },
})
vim.lsp.enable("skif")

or Helix, in languages.toml:

[language-server.skif]
command = "skif"
args = ["lsp"]
[[language]]
name = "json"
language-servers = ["vscode-json-language-server", "skif"]