Skills not recognized on Windows - 'Unknown skill' error #3

Activity

1. goulartfs commented on Mar 30, 2026

   

   goulartfs

   on Mar 30, 2026

   Author

   More actions

   Additional Investigation

   After deeper investigation, the root cause is clearer:

   The MCP server works perfectly

   • pixel-mcp-windows-amd64.exe --health passes
   • Sending JSON-RPC tools/list via stdin returns all 49 tools correctly
   • Server registered as plugin:pixel-plugin:aseprite in Claude Code's ListMcpResourcesTool

   Skills are loaded but tools are NOT accessible

   • All skills appear in the system-reminder (pixel-art-creator, pixel-art-animator, etc.)
   • When a skill is invoked (via Skill tool or user slash command), the SKILL.md content is loaded as context
   • BUT the MCP tools declared in allowed-tools frontmatter (mcp__aseprite__create_canvas, etc.) are never exposed as callable tools
   • ToolSearch finds zero tools from the aseprite MCP server, even during active skill execution

   Root cause hypothesis

   The Claude Code plugin system loads the SKILL.md as a prompt injection into the current context, but does NOT spawn a sub-agent with isolated MCP tool access as the architecture intends. The allowed-tools frontmatter is read but not acted upon — the tools are never registered in the agent's tool inventory.

   This means the plugin is structurally correct but functionally broken because Claude Code's skill→MCP tool bridge doesn't work (at least on Windows with Git Bash/MINGW64).

   Environment

   • Claude Code version: latest (March 2026)
   • Windows 11, Git Bash (MINGW64)
   • Plugin installed via marketplace, enabled in settings.json
   • Aseprite 1.3.17 via Steam
2. willibrandon

   self-assigned this

   on Apr 7, 2026
3. willibrandon commented on Apr 7, 2026

   

   willibrandon

   on Apr 7, 2026

   Last edited by willibrandon

   Owner

   More actions

   Reproduced this on Windows 11 with nushell. Running /doctor after installing the plugin shows:

   Plugin Errors
   └ plugin:pixel-plugin [pixel-plugin]: MCP server aseprite invalid: Missing environment variables: HOME
   

   The .mcp.json uses ${HOME}/.config/pixel-mcp/config.json for the config path, but HOME isn't set on native Windows outside of Git Bash/MINGW. Claude Code validates the MCP config at load time and won't start the server if env vars are missing, so the server never connects and no tools get exposed. That's the main blocker.

   While digging into this I found a few more issues that would bite even after fixing the env var:

   The name field in all four SKILL.md files uses spaces and uppercase (Pixel Art Creator, etc.). The spec requires lowercase letters, numbers, and hyphens only — so these should be pixel-art-creator, pixel-art-animator, etc. This is likely what causes the "Unknown skill" error.

   The allowed-tools frontmatter in all skills and commands uses comma-separated values (Read, Bash, mcp__aseprite__create_canvas, ...). The spec expects space-separated or a YAML list. Depending on how the parser handles it, the tools may not get recognized.

   The bin/pixel-mcp wrapper is a bash script. On Windows, bash in the system PATH can resolve to the WSL bash proxy (C:\WINDOWS\system32\bash.exe) rather than Git Bash, which can't handle the D:/SRC/... paths that ${CLAUDE_PLUGIN_ROOT} expands to. The fix is a small Go launcher binary in pixel-mcp that replaces the bash wrapper entirely — it uses runtime.GOOS/runtime.GOARCH to find and exec the right platform binary. No shell dependency, no path resolution issues. Tracked in willibrandon/pixel-mcp#18.
4. willibrandon

   added

   bugSomething isn't workingSomething isn't working

   on Apr 7, 2026