Skills not recognized on Windows - 'Unknown skill' error

[goulartfs]

Environment

• OS: Windows 11 Pro (10.0.26200)
• Claude Code: latest
• Aseprite: 1.3.17-x64 (Steam, E:/SteamLibrary/steamapps/common/Aseprite/)
• Plugin version: 0.5.0
• Shell: Git Bash (MINGW64)

Setup

• Plugin installed via claude plugin marketplace add willibrandon/pixel-plugin ✅
• Plugin enabled in settings.json ("pixel-plugin@pixel-plugin": true) ✅
• MCP config at ~/.config/pixel-mcp/config.json ✅
• pixel-mcp-windows-amd64.exe --health passes ✅
• MCP server responds with 49 tools when queried manually via stdin ✅
• Server registered as plugin:pixel-plugin:aseprite in ListMcpResourcesTool ✅

Problem

Skills not found

When typing any of these in the Claude Code prompt:

• /pixel-plugin:pixel-art-creator
• /pixel-plugin:pixel-setup
• /pixel-art-creator
• /pixel-setup

All return: Unknown skill: Pixel or Unknown skill: pixel-setup

MCP tools not accessible

The 49 tools from the aseprite MCP server (create_canvas, draw_pixels, etc.) do not appear in ToolSearch. They are not exposed as deferred tools to the agent.

When a skill is invoked via the Skill tool, the SKILL.md content is returned as text/context but the sub-agent with access to mcp__aseprite__* tools is not spawned.

Expected Behavior

• /pixel-plugin:pixel-art-creator should be recognized as a valid skill
• The skill should spawn a sub-agent with access to the MCP tools
• MCP tools should be callable within the skill context

Workaround

Using Aseprite CLI directly via aseprite.exe -b --script script.lua works for sprite generation.

Files Verified

• skills/pixel-art-creator/SKILL.md exists with correct frontmatter
• commands/pixel-setup.md exists
• .mcp.json declares server correctly
• installed_plugins.json shows plugin installed
• settings.json shows plugin enabled

[goulartfs]

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

[willibrandon]

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.