Skip to content

feat(glean)!: rename glean_run skill to glean-run - #29

Open
steve-calvert-glean wants to merge 1 commit into
mainfrom
feat/rename-glean-run
Open

steve-calvert-glean wants to merge 1 commit into
mainfrom
feat/rename-glean-run

Conversation

@steve-calvert-glean

@steve-calvert-glean steve-calvert-glean commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Important

Hold the release after merging. Merging is safe, but the next release publishes the new name to the plugin repos. Before cutting it:

  • scio component tests (python_scio/scripts/tests/yoda_playwright_automation/component_tests/glean_run_plugin) accept glean-run. Every Codex test currently asserts that glean_run/SKILL.md was read.
  • docs.glean.com (askscio/glean-docs): the plug-in user guide says to invoke /glean_run in its setup, verification, and usage sections. Check the other plug-in pages (Cursor, Claude Code, Codex setup, troubleshooting) too.

The commit is feat(glean)!, so release-it will propose 4.0.0.

Why this rename is needed

In short: glean_run isn't a valid skill name under the open Agent Skills standard. Codex and ChatGPT are moving to a plugin format whose clients must drop invalid skills. Without the rename, Codex users would lose the plugin's main skill, possibly with no error.

  1. Skill names follow a standard, and glean_run breaks it. The Agent Skills spec says a skill name "may only contain unicode lowercase alphanumeric characters (a-z, 0-9) and hyphens (-)" and "must match the parent directory name." The underscore makes glean_run invalid.
  2. Clients that use the new format must skip invalid skills. The Agent Plugins spec says: "If a discovered skill does not conform to the Agent Skills specification, the client MUST skip that skill and continue loading other skills and component types." Reporting it is only a SHOULD. The plugin would still install and the MCP server would still connect, but glean_run would be missing, possibly with no error.
  3. Codex and ChatGPT are moving to that format. OpenAI's packaging docs now lead with the Agent Plugins package and keep .codex-plugin/plugin.json only "as a compatibility fallback." pluginpack 0.12 (feat!: emit Agent Plugins packages from codex and add an agent-plugins target pluginpack#38) switches our Codex output to it, and VS Code/Copilot load the same format. pluginpack 0.12 also fails npm run validate on the old name, so we find out at build time, not from users.
  4. This is the skill users actually type. The plug-in guide tells users to invoke /glean_run when they want Glean to discover a skill or tool. It's the plug-in's entry point, not an optional extra.

Why rename it everywhere instead of only for Codex: one command name across Cursor, Claude Code, and Codex keeps docs and support simple. The hyphenated name already works on all three today. A Codex-only rename would leave /glean-run in one client and /glean_run in the others.

Why not stay on the legacy Codex layout: that only delays the rename. OpenAI supports the legacy layout as a fallback, not as the direction forward.

What

  • shared/glean/mcp/skills/glean_run/ → glean-run/, with frontmatter name: glean-run.
  • The mcp/pluginpack.json shipping-file entry and one comment in start.mjs.

No other source in this repo references the old name. This PR works on the current pluginpack (0.11) and doesn't need 0.12.

Verification

  • npm test (build + validate for claude, cursor, codex) passes; all three targets ship skills/glean-run/SKILL.md.
  • check:no-shell, check:release-version, typecheck:bundle, and test:bundle (432 tests) pass.
  • Preview of the follow-up: with pluginpack 0.12's branch and overrides/codex/glean/mcp/config.json deleted, all three targets validate, and Codex gets a valid Agent Plugins plugin.json + mcp.json.

Follow-up

After pluginpack 0.12 is released: bump @gleanwork/pluginpack, delete overrides/codex/glean/mcp/config.json (0.12 renders the shared MCP config for Codex), and regenerate.

Agent Skills names allow only lowercase letters, digits, and hyphens, and
must match their directory. Clients that follow the Agent Plugins spec
skip a skill that breaks the rule, so glean_run would silently disappear
once Codex output moves to the Agent Plugins layout (pluginpack 0.12).

Renames the shared skill's directory and frontmatter name, and updates
its entry in the MCP shipping-file map. Claude Code, Cursor, and Codex
all accept the new name on pluginpack 0.11.

BREAKING CHANGE: the skill is now invoked as /glean-run (Cursor, Claude
Code) instead of /glean_run.
@steve-calvert-glean steve-calvert-glean added the enhancement New feature or request label Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant