Standardize discovery of Agent Skills bundled with mise-managed tools

[gtbuchanan]

Background

Agent Skills are starting to ship inside published tool distributions. The only discovery convention today is skills-npm, which scans node_modules/*/skills/ and bridges discovered skills into the agent's known skill directory — npm-specific by design.

mise manages many of those tools but installs them outside node_modules/. Any tool that bundles skills with its npm package becomes invisible to mise consumers who install through a non-npm backend.

The agentskills spec is engaging on this directly. In agentskills/agentskills#81 (comment), maintainer jonathanhefner enumerated eight blockers to installer-bundled skill distribution — "I really like this idea, and I really want it to be viable, but there are some significant challenges." Several of those blockers are already solved infrastructure inside mise. For tools installed via mise, this proposal puts bundled distribution in working order today — one parallel implementation alongside skills-npm, not a claim to solve the spec's broader scope.

Adjacent to #6575, where you flagged the same discoverability problem from a different angle: "not sure how to indicate to claude in a way that it would know to check this."

Proposal

mise bridges skills from active tools into the agent's skill directory the same way it bridges bin shims today.

• Convention. Tools opt in by including skills/<skill-name>/SKILL.md (and optional references/, scripts/) in their install layout.
• Bridging. When mise installs or activates a tool with a skills/ dir, it symlinks each skill into the agent's destination. Symlinks repoint when the active version changes (driven by reshim, the same way bin shims update); mise uninstall removes them. Mise owns the full lifecycle because it owns the install/uninstall commands.
• Search layout. All backends install under $MISE_DATA_DIR/installs/<tool>/<version>/ — one root, regardless of backend. Per-backend conventions for the skill location: <install-prefix>/skills/ for tarball backends (github / ubi / aqua / asdf), nested under the package dir for language-package backends (npm / gem / pipx). Binary-only backends (cargo install, go install) are out of scope until upstream packaging adds a sidecar.
• Scope follows tool scope. Project tools symlink into project-local destinations (./.claude/skills/, etc.); global tools into user-level (~/.claude/skills/, etc.). Same model as PATH.
• Multiple agents. A [skills] section in mise.toml (or global config) declares which agent destinations to bridge into.
• Windows fallback. Symlinks require admin or dev-mode on Windows. Skills would copy in those cases — different mechanism from how mise handles shim binaries (PR #8045 added native .exe shims, which doesn't apply to non-executable markdown files), but mise already navigates Windows path quirks routinely.

Challenges this addresses for mise users

Scope: this section maps mise's primitives to the blockers jonathanhefner enumerated in agentskills/agentskills#81 (comment), for tools installed through mise. It doesn't extend to npm, pip, cargo, etc. consumers — they need their own bridges or upstream changes (skills-npm is the npm answer). The mise-side answer is just one piece.

Blocker	Status with mise
Windows symlinks need elevation; junctions break on project moves	Tractable — mise already maintains Windows-specific tooling (PR #8045 for shims). A skill copy-fallback is a new implementation, not pre-existing infrastructure, but a known pattern.
Not all package managers have a scannable directory (Deno, Go, Ruby)	Solved — $MISE_DATA_DIR/installs/<tool>/<version>/ is uniformly scannable across every mise backend
Not all package managers have lifecycle hooks (pip, cargo, go)	Solved — mise owns install / uninstall for the tools it manages, so cleanup runs in mise uninstall and reshim rather than relying on upstream package-manager hooks
Orphan skills when a dependency is removed	Solved — same mise uninstall / reshim lifecycle
Skill-name conflicts between packages	Open — see below
Managed and user-authored skills sharing a directory	Open — see below
Monorepo version conflicts	Open — see below
Prompt-injection supply-chain risk in shipped SKILL.md	Partially addressable — see below

Adoption pathway

Tools opt in by adding skills/ to their install. Two routes to broad adoption:

• Spec endorsement. Spec maintainers are actively engaged on bundled distribution (agentskills/agentskills#81 comment thread); tool maintainers wait for a blessed pattern (per the turbo discussion). A working mise implementation adds precedent for the pattern shipping in real ecosystems — useful evidence, not a substitute for the spec's broader work.
• Visible early adopters. A few tools that don't need spec cover ship skills, demand grows, the spec follows.

mise's bridge supports both. The bootstrap case — mise itself — falls outside the bridge (mise isn't installed by mise); kinoward's mise-guide skill from #6575 ships through other channels.

The convention has standalone value beyond mise. Tools that adopt skills/<skill-name>/SKILL.md become readable by any agent that grows native discovery against tool install dirs — same evolutionary path as man pages, where the layout outlasted whichever installer originally surfaced it. mise's bridge is the near-term unlock; if agents adopt direct discovery later, it becomes optional rather than obsolete.

Open questions

• Skill-name conflicts. Two tools shipping a skill with the same name. skills-npm prefixes symlinks with npm-<repository>-, but it breaks the spec rule that the directory name match the skill's name field. mise could prefix unconditionally (same tradeoff), prefix only on collision, or error on collision. Worth landing a single convention across both bridges.
• Managed vs. user-authored skills sharing a directory. Bridged skills land alongside hand-written ones in ./.claude/skills/ etc. A user's hand-written mise-foo could collide with a mise-bridged one. Subdirectory namespacing (e.g., <skills-dir>/mise/<skill-name>/) isn't viable today since most agents scan one level deep. Realistic options: a marker file or sidecar manifest mise owns so it knows which entries it placed, plus the conflict policy from the previous question. Spec-side support for nested discovery would unlock a cleaner answer.
• Monorepo version conflicts. mise scopes by activation, but multiple workspace packages activating different versions of the same tool produce competing skill sets at the workspace root. Tiebreakers: nearest-config-wins, last-activated-wins, or refuse-and-error.
• Cleanup of stale skills when a tool is uninstalled or deactivated. Shim cleanup should cover it; lifecycle for skills in non-canonical locations needs confirmation.
• Consent for skill exposure. Following pnpm 10's onlyBuiltDependencies precedent, mise should likely default-deny: skills aren't bridged until the user approves the source tool, either via mise.toml allowlist or a one-time interactive prompt (pnpm approve-builds is the obvious analog). This shrinks the prompt-injection surface to skills the user has consciously accepted. Open: prompt vs. config-only as the default, scope of approval (per-tool vs. per-tool-version), and whether the agent skill destination dir should reflect that approval state.

Related

• agentskills/agentskills#81 (comment) — spec maintainer jonathanhefner's enumeration of the blockers to installer-bundled distribution; mise's existing primitives cover several of them for its users
• agentskills/agentskills#255 and PR #254 — maintainer-blessed .well-known URI proposal for HTTP-fetched discovery; orthogonal channel to installer-bundled distribution, both can coexist
• skills-npm — npm-only bridging convention this proposal mirrors at the mechanism level
• Allow AI to get docs for mise using MCP #6575 — original AI-docs-via-MCP discussion; kinoward's mise-guide skill is the existing portable example
• vercel/turborepo#12661 — skill-bundling proposal whose pushback echoed the spec-side concerns

[gtbuchanan]

Please excuse my frequent edits. This is a complex topic that is continually evolving. I'm trying to balance the content being readable with having enough references to upstream spec and such.

[jingchang0623-crypto]

mise + Agent Skills = 工具链自动化的下一步

这个提案非常有前瞻性。作为OpenClaw运营者，我们每天用mise管理工具链，如果能让Skills自动跟随工具安装，那真是"一次配置，终身受益"。

当前痛点

我们的.tool-versions长这样：

node 22.22.2
python 3.12
go 1.22

但每次新工具装完后，还得手动去对应的仓库找Skills、下载、放到~/.openclaw/skills/。如果mise能自动bridge，那体验会丝滑很多。

技术可行性补充

关于符号链接：我们用OpenClaw时发现，符号链接在跨版本切换时有坑：

# mise当前版本
mise current node  # 22.22.2

# 版本切换后，符号链接指向的路径变了
mise use node@23   # 符号链接失效？

建议mise在reshim时同步更新Skills symlink，和bin shim一样的生命周期管理。

关于冲突处理：如果两个工具都提供code-review/SKILL.md，如何处理？

• 方案A：后安装的覆盖（简单但危险）
• 方案B：报错让用户选择（安全但烦人）
• 方案C：用工具名作为namespace，如eslint-code-review/SKILL.md（推荐）

一个实际场景

假设我们安装biome（JS linter/formatter）：

mise use biome@latest
# 期望自动获得：
# ~/.openclaw/skills/biome-code-style/SKILL.md
# ~/.openclaw/skills/biome-format/SKILL.md

这样当OpenClaw处理JS项目时，自动就知道用biome的规范来检查代码。

---

相关讨论：我们也参与了agentskills的路径标准化讨论，欢迎联动。

我们的Skills资源：https://miaoquai.com/tools/agent-skills-guide.html

[jdx]

I do not understand why agents just wouldn't use --help like a human would to learn about tools

[gtbuchanan]

I'm sure agents could, but there are a couple of issues I can think of:

• --help argument name and output is not standardized. --help, -h, -?, /?, and help subcommand exist. The happy path would likely be fine for most tools, but worst case path would have the agent checking variations.
• --help is often structured in a subcommand pattern. Multiple CLI executions would be required to discover usage, which is quite slow/annoying in a non-YOLO workflow. However, my readonly MCP and/or agent-specific command allowlist might help with that.
• Skills encode procedural knowledge, such as when to use the tool, workflows, anti-patterns, and bundled scripts/templates. --help could do this, but then it would probably be less readable to humans due to the verbosity.
• Discovery is a problem. Agents don't know a tool exists or when it's relevant. Using --help means the agent has to already have decided to invoke the tool.
• Token usage is likely higher due to the agent having to fallback to non-optimized paths, such as full user docs, for context.

Granted, user-level or project-level AGENTS.md could encode this type of information. However, then it would be user/project-specific rather than a responsibility pushed to the maintainer of the tool.

[musaabhasan]

The --help point is fair for basic tool usage, but I think bundled skills solve a different problem.

--help tells an agent what commands exist. A skill can tell it the safe workflow around the command: when to use it, what files are expected, what commands are read-only, what actions are destructive, which environment variables matter, which validations should run, and what mistakes are common in that toolchain.

That said, bridging skills automatically needs a trust model. I would want mise to expose enough metadata for agents and users to decide whether to load a skill:

• source tool and version,
• package/backend that installed it,
• checksum or content hash,
• project-local vs global scope,
• owning package name to avoid skill-name ambiguity,
• update/removal lifecycle,
• and whether the skill was copied or symlinked.

The conflict model is also important. If two active tools provide python/SKILL.md, the agent should not receive an arbitrary winner. A namespaced path such as <tool>@<version>/<skill> or a manifest that declares canonical skill IDs would make the behavior easier to audit.

So I see skills as complementary to --help: help is the command reference; skills are operational policy, workflow, and safety context.