Grok plugin list cannot see the user plugin inspect calls enabled

John Burns

grok plugin list printed No plugins installed and exited 0. In the same home, grok inspect printed gauge (user, enabled) and a skill count of 1. The Skills section above that row said None. grok plugin enable gauge and grok plugin details gauge both exited 1 and told the operator to run list.

That split is the contract in Grok 1.0.67, build 2fe064390d07, measured on 15 November 2026 on Linux x86_64. The user guide shipped inside that binary says Grok loads plugins from ~/.grok/plugins/, trusts that directory automatically, and leaves plugins off until the name is listed under [plugins] enabled. The public plugins page, fetched the same evening, lists the same directory and does not mention an install registry. Neither page says that inspect will mark a copied folder enabled while the Skills section stays empty, or that list, enable, and details will not open that folder.

Where the files actually sit

A plugin skill reaches the discovery list only if it appears under Skills in grok inspect. The plugin row is a separate count. On this version the row can say enabled, and can report a skill directory, while Skills stays empty. The name that moves a skill onto that list is an entry in the home’s config.toml, not the word enabled on the row.

Three locations showed up in the isolated home. A directory copied to <grok-home>/plugins/gauge is the path the guide calls the user plugin directory. grok plugin install --trust did not write there. It copied the source into <grok-home>/installed-plugins/<src-key>/ and recorded that copy in <grok-home>/installed-plugins/registry.json. The third location is the config file install and disable edit: [plugins] enabled and [plugins] disabled.

List, details, enable, disable, and uninstall read the registry. Inspect reads both the user plugin directory and the install copy, then applies the config lists when it builds the Skills section. Validate reads the directory you pass it. It does not read the registry, and it does not tell you whether the skill will be listed.

The home under test was not the operator home. GROK_HOME and HOME both pointed at a new directory. No API key was set. No login ran. No model call ran. The checkout used for inspect was a new git repository with one commit. A second isolated home, whose inspect line said the project was not trusted, produced the same split for a different plugin name. The empty Skills section is not the untrusted-project skip in the skills guide. That skip applies to project skills. These files were under the user plugin directory.

This run did not place a plugin in .grok/plugins/ inside the checkout, and it did not pass --plugin-dir. Those are other load paths in the guide. The measurements below are the user directory, the install copy, and the config lists.

The copied plugin

The copied tree was one manifest and one skill. The manifest was:

{
  "name": "gauge",
  "version": "1.0.0",
  "description": "A gauge plugin"
}

The skill file was <grok-home>/plugins/gauge/skills/gauge/SKILL.md:

---
name: gauge
description: Measure one reading.
---

Read the gauge and stop.

name in the manifest is the string inspect prints on the plugin row. name in the skill front matter is the string that later appears under Skills, qualified as plugin: gauge. The directory name under plugins/ matched the manifest name in this run. That match is not a check validate enforces. A separate probe the same evening, on a directory named dirname whose manifest name was other-name, exited 0 and printed Plugin manifest is valid. Use the manifest name in config. Do not assume the parent folder is the name inspect or enable will accept.

The version string is reported by validate and by details after install. List does not use it as a key. After a local install, list keys the record by a repo key taken from the source directory name, then prints the manifest name beside it. This run did not reinstall over an existing key.

grok plugin validate on the copied directory exited 0 and printed that the manifest was valid, with one skill directory, no command directory, and no agent directory. That exit code means the JSON parsed and the counted directories were present. It does not mean the skill is on the Skills list. An empty directory, in the same probe set, also exited 0, with the sentence that no plugin.json was found and that Grok discovers components from standard directories. Validate is a manifest and layout check. Run inspect after it if the question is whether a session would see the skill.

The skill count on the plugin row is that directory count. Before any config file existed, the row said 1 skills while Skills said None. After the name was added to enabled, the row still said 1 skills and Skills gained one line. The number does not move when the skill becomes visible.

List does not open the user plugin directory

Before any config file existed, the management commands and inspect disagreed. The commands were:

grok plugin list
grok plugin list --json
grok plugin enable gauge
grok plugin details gauge
grok inspect

List printed No plugins installed. Run grok plugin install --help to get started. and exited 0. The JSON form printed [] and exited 0. An empty registry is a successful list, not an error. A script that treats exit 0 as “the user plugin directory is empty” will miss the copied folder.

Enable printed Error: Plugin "gauge" not found. and Run grok plugin list to see installed plugins. and exited 1. Details printed the same error and the same exit code. The error is accurate about the registry. It is the wrong next step if the folder is already on disk under plugins/, because list will keep saying the registry is empty. Following the error’s advice loops. The folder has to be named in config, or installed so the registry exists.

Inspect, with no user config source, printed:

Skills (None)

Plugins (1)
└ gauge (user, enabled)  1 skills

Config Sources said the user config was none. The enabled word on that row was not read from config.toml. There was no config file yet. The guide’s sentence that plugins are off by default is true for the Skills section. It is not true of the label inspect prints for a folder in the user plugin directory. Trust is also not the missing switch. The guide says that directory is trusted automatically, and this row already says user. The skill still did not appear.

The same management commands, after the name was added to enabled, still could not see the plugin. List stayed empty. Enable still exited 1. Editing config does not register an install, and the management commands never grew a view of plugins/. If a runbook says to enable and then list, that runbook only works after install has already recorded the plugin.

The name in enabled is the skill gate

The file that moved the skill was:

[plugins]
enabled = ["gauge"]

Inspect then printed:

Skills (1)
└ gauge  plugin: gauge

Plugins (1)
└ gauge (user, enabled)  1 skills

Config Sources named the user config.toml. The plugin row did not change. The Skills section did. That is the check. If the skill line is absent, the copied plugin is not in the set inspect will report as discovered, whatever the row says.

The second home confirmed the gate is the list, not project trust. Its inspect line said the project was not trusted. A plugin copied into that home’s user plugin directory was marked user, enabled, with a skill count, and Skills stayed empty. Adding that plugin’s name to [plugins] enabled put the skill on the Skills list. The project trust line did not change. A copied user plugin does not wait on project trust. It waits on the config name.

Removing the name from enabled and writing only a disable entry took the skill back off:

[plugins]
disabled = ["gauge"]

Skills returned to None. The plugin row still read gauge (user, enabled) 1 skills. A disabled entry is enough to keep the skill out. It does not flip the label. If you are reading inspect to see whether a skill will load, read the Skills section. If you are reading it to see whether a disable entry took effect, the row will not tell you. Open the config file, or infer it from the skill line.

An operator who copied a plugin into ~/.grok/plugins/ and then ran grok plugin enable has not finished the step the guide describes. Enable cannot write the name, because it cannot find the plugin. Write the manifest name into [plugins] enabled yourself, or install the plugin so the install command writes that line. Then run inspect again and require the skill line. The string in the list is the manifest name, which was gauge here, not the skill front-matter name and not the repo key. Those three strings are equal only when you chose them that way.

Install writes a different directory

grok plugin install without --trust does not copy and does not register. On a local source it exits 1, prints that installation needs explicit trust, and tells you to re-run with --trust. That refusal is real. It is a different gate from the copied-folder case. The copied folder was already visible to inspect before any install, and install was never asked to trust it. Skipping --trust protects the install path. It does not hide a folder you already placed in plugins/.

The install under test used a second source, so it would not be confused with the copied gauge tree. The source held one skill named needle and a manifest named needle at version 2.0.0. The command was:

grok plugin install <plugin-src> --trust

It exited 0 and printed Installed 1 plugin(s) from <plugin-src>: needle. List then printed one row, src2-a6aea3f0: needle [local: <plugin-src>]. The JSON list had status installed, name needle, repo key src2-a6aea3f0, version 2.0.0, and a path under installed-plugins/src2-a6aea3f0. The marketplace field was null. Details printed the same repo key, the same path, kind local, and the install time 2026-11-16T04:08:13Z, which is 23:08 US Eastern. It counted one skill directory.

The config file, which already contained disabled = ["gauge"], became:

[plugins]
disabled = ["gauge"]
enabled = ["needle"]

Install appends the new name to enabled. It does not clear a disabled list that was already there. Inspect then showed both plugin rows, both labeled user, enabled, and one skill line: needle plugin: needle. The gauge skill stayed off because gauge was still in disabled. The needle skill appeared because install had put that name in enabled and the copy existed under installed-plugins/.

The public page’s load list names ~/.grok/plugins/marketplaces/ for marketplace installs. This local install did not use that directory. The copy landed in installed-plugins/, which neither the bundled guide’s load table nor the public page names. Details printed a path under the grok home, not under the source directory. This run did not delete the source after install.

Disable keeps the list row

grok plugin disable needle exited 0 and printed Disabled plugin: needle. The config became a disabled list containing both gauge and needle, and enabled set to an empty array. List still printed the needle row, with the same repo key and the same local source. Inspect Skills went back to None. Both plugin rows still said enabled, including needle.

Disable, for an installed plugin, is a config edit. It removes the name from enabled, adds it to disabled, and that is what takes the skill off the Skills list. It does not remove the registry row, so list still looks installed. It does not change the inspect label. After disable, list says installed, the plugin row says enabled, and Skills says nothing. Skills is the view that matches the config.

grok plugin uninstall needle --confirm exited 0 and printed Uninstalled 1 plugin(s): needle. List returned to No plugins installed. Inspect dropped the needle row and kept the gauge row. The copy under installed-plugins/src2-a6aea3f0 was gone. registry.json and registry.lock remained. The config file still listed both names under disabled, with enabled empty. Uninstall removes the copy and the list row. It does not scrub the name out of disabled. A later install of another plugin can sit beside that leftover name, which is what happened in reverse when needle was installed beside the gauge disable entry. The leftover does not, by itself, bring the uninstalled skill back. After uninstall, inspect no longer had a needle row, and Skills stayed empty.

If you disable and then uninstall, expect the name to remain in disabled. Clear it when a later copy of that name should be allowed to load. This run did not re-copy needle after uninstall.

Verify the skill line before the session

Use a spare GROK_HOME. Do not point these commands at the home a signed-in session is already using until you have decided which skill you mean to add or remove. The binary writes its user guide into the home on first use. That write is normal. It is not the plugin under test.

If you copied a plugin into ~/.grok/plugins/<name>/, run grok plugin list and expect it to miss that folder. Run grok plugin enable <name> only if list already shows it. If enable says the plugin was not found, write the manifest name into [plugins] enabled in that home’s config.toml. Run grok inspect. Require a Skills line of the form <skill> plugin: <name>. A plugin row that says enabled, and a validate exit of 0, are not that line. If the skill line is missing, the name is absent from enabled, present in disabled, or the skill file is not where the row’s count looked. The count and the line are different fields.

If you installed with --trust, list should show a repo key and the plugin name. Details should show a path under installed-plugins/, not under plugins/. Inspect should show the skill only while the name is in enabled and not in disabled. After grok plugin disable <name>, list will still show the row. Read Skills, not list, to see that the skill is out. After uninstall, list should be empty of that name, and inspect should drop the row. Open config.toml if you need to know whether the name is still sitting in disabled. Remove it there if the next copy of that name should be allowed to load.

This run did not start a signed-in session and did not ask a model to invoke the skill. The measured boundary is the one inspect and the management commands already disagree on: which directory list can see, which directory inspect counts, which config key puts the skill on the Skills list, and which of those views disable and uninstall actually change.

Sources

  • Grok 1.0.67 (2fe064390d07), Linux x86_64, 15 November 2026, US Eastern. Two isolated homes, each with its own GROK_HOME and HOME. No API key and no login. In the home recorded here, a copy at plugins/gauge made grok plugin list print no plugins and exit 0, grok plugin list --json print [], and enable and details exit 1 with Plugin "gauge" not found. grok inspect printed gauge (user, enabled) and Skills (None) before any config file existed. [plugins] enabled = ["gauge"] added gauge plugin: gauge under Skills. [plugins] disabled = ["gauge"] removed that line and left the row labeled enabled. grok plugin install <plugin-src> --trust for a second plugin named needle exited 0, wrote installed-plugins/src2-a6aea3f0, and set enabled = ["needle"] beside the existing disable list. grok plugin disable needle left the list row in place, emptied enabled, and cleared Skills. grok plugin uninstall needle --confirm removed the copy and the list row, left registry.json, and left both names in disabled. A second home whose project line said not trusted showed the same copied-folder split. A same-evening validate probe accepted a manifest name that did not match its parent directory, and accepted an empty directory with exit 0.
  • User guide extracted by that binary into the isolated home on first run, docs/user-guide/09-plugins.md and docs/user-guide/08-skills.md. The plugins page lists ~/.grok/plugins/ as a user scope that is trusted automatically, says plugins are off by default until named in [plugins] enabled, and documents list, enable, disable, and details. It does not name installed-plugins/. The skills page says startup discovery skips project skills in untrusted folders. The skill in this run was not a project skill.
  • Skills, Plugins & Marketplaces, fetched 15 November 2026. The page lists ./.grok/plugins/, ~/.grok/plugins/, marketplace installs under ~/.grok/plugins/marketplaces/, extra [plugins] paths, and --plugin-dir. It does not name installed-plugins/ or the split between the plugin row and the Skills section.