can you read this and tell me whats going on https://github.com/entireio/skills/issues/3

Here's what's going on in issue #3:

Title: Cursor local plugin install did not load on Windows + WSL; project-level .cursor/skills worked

Reporter: Lucas Lepski (@shurkanTwo), opened against entireio/skills. You already replied that you'll look into it.

Environment: Windows host + WSL2, Cursor 1.105.1, repo cloned in WSL, Cursor running on Windows.

What they tried (all failed):

1. Local plugin at ~/.cursor/plugins/local/entire (full copy, not symlink), with a valid .cursor-plugin/plugin.json — did not load.
2. Original repo layout with manifest pointing skills: ./plugins/entire/skills/ — plugin never appeared.
3. Added name: fields to the session-handoff, search, and explain SKILL.md frontmatter — still nothing.
4. Flattened to a top-level skills/ directory and updated manifest to ./skills/ — still nothing.
5. Personal skills at ~/.cursor/skills/ — also did not show up.

What worked: Dropping the skills directly into the repo as project-level files:

• .cursor/skills/session-handoff/SKILL.md
• .cursor/skills/search/SKILL.md
• .cursor/skills/explain/SKILL.md

They appeared immediately after a reload.

UI state when broken: "Include third-party Plugins, Skills, and other configs" was enabled; the plugin didn't appear in the Plugins UI, and skills didn't appear in the global Skills UI.

Ask: Document a Cursor-specific install path that actually works — either fix the local-plugin install, fix ~/.cursor/skills/, or recommend project-level .cursor/skills/ as the fallback in the README, especially for Windows + WSL setups.

The core suspicion worth investigating: Cursor on Windows likely doesn't traverse the WSL filesystem for ~/.cursor/plugins/local/, and the repo's current plugin manifest (skills: ./plugins/entire/skills/) may not match what Cursor's plugin loader expects. Worth checking if plugin.json in this repo is actually the shape Cursor wants, and whether Cursor scans %USERPROFILE%\.cursor\plugins\local on Windows at all vs. only at install-time via some registry.

I verified the reporter's claims against Cursor's official plugin spec and the repo on disk. The report is largely correct, and there are several concrete problems in this repo.

Verified facts from Cursor's spec

Cursor's plugin manifest schema is at github.com/cursor/plugins/schemas/plugin.schema.json:

• name is required and must match ^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$ (kebab-case).
• additionalProperties: false — unknown keys fail validation.
• skills accepts a string or string array of paths/globs.
• The manifest must live at <plugin-root>/.cursor-plugin/plugin.json.

A SKILL.md file needs YAML frontmatter with both name: (kebab-case) and description:. Cursor preloads name+description into the agent's system prompt.

For a multi-plugin repo (like cursor/plugins), the layout is .cursor-plugin/marketplace.json at the repo root plus a nested <plugin>/.cursor-plugin/plugin.json per plugin. marketplace.json has a different required shape (name, plugins[] with name+source).

Official docs don't document ~/.cursor/plugins/local/ as an auto-load path. Community guides (Medium, dredyson.com) say the working convention is ~/.cursor/plugins/<name>/ (often via symlink) with a full Cursor restart — no local/ subdirectory.

Problems in this repo

1. Manifest is in a split-brain state. /Users/alisha/Projects/skills/.cursor-plugin/plugin.json:13 sits at the repo root and points skills at ./plugins/entire/skills/, but plugins/entire/ is where the actual plugin lives (it has its own .claude-plugin/plugin.json and .codex-plugin/plugin.json, but no .cursor-plugin/plugin.json). So the repo is neither a clean single-plugin layout nor a proper marketplace layout. For Cursor you need one of:

• Single plugin: move all skills to ./skills/ at the repo root and set "skills": "./skills/", OR
• Marketplace: replace the root plugin.json with a marketplace.json, and add plugins/entire/.cursor-plugin/plugin.json with "skills": "./skills/".

2. SKILL.md files are missing name:. All three (plugins/entire/skills/{session-handoff,search,explain}/SKILL.md) have only description: in frontmatter. Cursor requires name: and the reporter correctly identified this gap — even though adding it alone didn't rescue their install, it's still a real defect independent of the install path issue.

3. The reporter's ~/.cursor/plugins/local/entire/ path is probably not a thing. The supported convention is ~/.cursor/plugins/entire/ (no local/ intermediary). So their attempt #1 was using an unsupported directory — which is partially on docs (Cursor's own docs are thin here) and partially on us (our README doesn't tell them the right path).

4. README "Cursor" section is effectively empty — README.md:78-80 just says "Use .cursor-plugin/plugin.json." No install command, no ~/.cursor/plugins/ path, no .cursor/skills/ project-level fallback, no Windows+WSL caveat. Cursor has no equivalent to Claude Code's /plugin marketplace add entireio/skills, so we can't copy that pattern.

5. WSL+Windows is a red herring for their specific failure. They copied into the Windows-side C:\Users\USERNAME\.cursor\plugins\local\entire\, so cross-filesystem visibility wasn't the direct blocker — the local/ subdir and the manifest issues were. But it's still worth calling out in docs.

What actually works (and why)

The reporter's working path — dropping skills at .cursor/skills/<name>/SKILL.md inside the open project — works because Cursor auto-discovers project-level skills independent of the plugin system. This doesn't need a manifest, doesn't need marketplace registration, and doesn't need the ~/.cursor/plugins/ path. It's the most reliable fallback and should be documented.

Suggested fix (minimal → thorough)

• Minimal: add name: frontmatter to all three SKILL.md files, and add a Cursor-specific README section explaining: (a) clone to ~/.cursor/plugins/entire/ (no local/), restart Cursor; (b) fallback — copy/symlink plugins/entire/skills/ into the open project's .cursor/skills/.
• Proper: restructure as a marketplace (.cursor-plugin/marketplace.json at root, plugins/entire/.cursor-plugin/plugin.json with "skills": "./skills/"). This matches Claude Code's marketplace layout already present and aligns with cursor/plugins' conventions.

Sources:

• Cursor plugin schema
• cursor/plugins README — repo layout
• Plugins Reference | Cursor Docs
• How to Write and Test Cursor Plugins Locally — Vitek Tajzich, Medium
• Cursor 2.5 Plugins local testing — Dre Dyson
• Cursor 2.5: Plugins — Cursor Forum

Want me to implement the minimal fix (add name: frontmatter + a proper Cursor section in README), or the marketplace restructure?

Mirroring the existing Claude marketplace layout. Let me load the task tools and execute.

Saved the constraint. Holding on the restructure until you tell me which agent breaks and which approach you prefer.

Done. Changes:

• /Users/alisha/Projects/skills/.cursor-plugin/plugin.json → deleted
• /Users/alisha/Projects/skills/.cursor-plugin/marketplace.json → new (marketplace listing entire with source: ./plugins/entire)
• /Users/alisha/Projects/skills/plugins/entire/.cursor-plugin/plugin.json → new (per-plugin manifest with skills: ./skills/)
• /Users/alisha/Projects/skills/README.md:78-95 → Cursor section now documents: the marketplace layout, the local ~/.cursor/plugins/entire symlink install with macOS/Linux + Windows variants, and the .cursor/skills/ project-level fallback (the path the issue reporter confirmed works).

Skipped the name: frontmatter additions per your call — Cursor uses the folder name when name: is omitted, so session-handoff, search, explain will still identify correctly. Worth validating once in Cursor before closing the issue, in case the folder-name fallback doesn't fully register.

Two ways — marketplace plugin via symlink (tests the full restructure) and project-level fallback (tests just the skills).

Full plugin test

Then:

1. Quit Cursor fully (Cmd+Q, not just close window — the process has to restart to re-scan ~/.cursor/plugins/).
2. Reopen Cursor. Open any project.
3. Settings → make sure "Include third-party Plugins, Skills, and other configs" is enabled.
4. Open the Plugins panel — "Entire" should appear as installed.
5. Open the Skills panel — session-handoff, search, explain should be listed.
6. In chat, try a natural-language trigger: hand off this session or /explain README.md or search past work for X.

If it doesn't show up, first thing to check is JSON validity against the schemas:

There's also an official create-plugin plugin from Cursor that scaffolds and validates — you could install that first and use its validation against our manifests.

Fallback test (project-level skills)

Pick any scratch repo and drop the skills in:

Then try the same skill invocations in chat. This path doesn't need a full Cursor restart — a window reload is enough.

Cleanup after testing

Want me to run the JSON validity checks now as a pre-flight?

That's a useful signal — something is already registering them. Cursor provides multiple discovery paths, so let's figure out which one is active before trusting any test.

Diagnostic steps:

1. Find where they're coming from. Cursor's Skills panel usually shows the source path per skill. What does it list next to session-handoff / search / explain?

2. Check the other global locations:

3. Check the workspace you have open. If Cursor is pointed at /Users/alisha/Projects/skills, it's likely auto-scanning the workspace. Cursor walks the workspace for SKILL.md files in specific locations. Our repo has:

• plugins/entire/skills/session-handoff/SKILL.md
• plugins/entire/skills/search/SKILL.md
• plugins/entire/skills/explain/SKILL.md

It's possible Cursor picks those up directly because it sees .cursor-plugin/marketplace.json at the repo root and follows the manifest inline (workspace-scoped plugin install) — that would actually be a success case for our restructure.

4. Isolate with a clean workspace. Open Cursor on a totally unrelated repo (e.g. /tmp/empty-test, mkdir /tmp/empty-test && cd /tmp/empty-test && git init). If the skills still appear there, they're coming from ~/.cursor/ or a globally installed plugin. If they don't appear, they're workspace-scoped from the skills repo itself.

Can you paste the output of step 2 and tell me what the Skills panel shows as the source? That'll tell us whether our restructure is actually being exercised or we're looking at a pre-existing install.

That makes the test ambiguous — Cursor's chat backend can be Claude Code or Codex, and those have their own skill registries. To prove our Cursor plugin itself is loading, we need a skill that only exists in the Cursor plugin path.

Proposal: drop a unique, throwaway skill into the Cursor plugin tree, install only via the Cursor symlink, and see if it shows up in Cursor's Skills panel. If it does, the plugin loader is working. If it doesn't, we know the restructure is still wrong.

Then fully quit Cursor (Cmd+Q), reopen, open the Skills panel and look for cursor-loader-probe.

• Present → our plugin manifest works. Remove the probe and the symlink after.
• Absent but the other three still show → they were coming from Claude Code/Codex all along; our Cursor plugin isn't loading. We'd then debug the manifest (likely candidates: schema URL rejection, skills path format, or Cursor needing name: in SKILL.md frontmatter after all).

Cleanup after testing:

Want me to create the probe skill and do the grep pre-check now?

Clean — no real registrations of cursor-loader-probe anywhere in ~/.claude, ~/.codex, or ~/.opencode. The probe is unique.

Test skill is ready at plugins/entire/skills/cursor-loader-probe/SKILL.md. To run the actual test:

Then fully quit Cursor (Cmd+Q), reopen, and check the Skills panel. If cursor-loader-probe appears, the Cursor plugin loader is reading our restructured manifest correctly. If it doesn't appear but the other three still do, they were coming from Claude Code / Codex all along and we need to keep debugging the Cursor plugin load.

Cleanup after:

Want me to run the symlink command for you, or would you rather do it manually?

The symlink didn't work because Cursor doesn't scan ~/.cursor/plugins/ on this version. Found the real picture:

• ~/.cursor/skills-cursor/<name>/SKILL.md — where Cursor actually stores user skills (synced from the marketplace; babysit, canvas, create-hook, etc. live here).
• ~/.cursor/extensions/ — traditional VS Code extensions (Claude Code is installed here as anthropic.claude-code-2.1.119-darwin-arm64).
• ~/.cursor/plugins/ — empty except for our dead symlink and an unused local/ subdir.

The skills you were seeing in Cursor were almost certainly coming from Claude Code's extension surface, not from Cursor's native skills system. That matches your hunch.

Two consequences:

1. The README instructions I just wrote (ln -s ... ~/.cursor/plugins/entire) are wrong. There's no supported unpacked-plugin install path at ~/.cursor/plugins/<name>/ in the current Cursor build. The dredyson article and my earlier summary were outdated or never right.
2. The real install targets are: the Cursor marketplace (populates skills-cursor/) or the project-level .cursor/skills/ path the issue reporter found.

Also relevant: ~/.cursor/skills-cursor/babysit/SKILL.md does use name: in frontmatter — so if we ever want to distribute via that path, the name: field becomes mandatory again, which puts us back in the cross-agent compat problem.

Before I touch more code, two quick confirmations I'd like to run:

1. Confirm ~/.cursor/skills-cursor/ is a live load path — drop the probe there and see if it shows up:

   Restart Cursor, check Skills panel. If it shows up, that's the real user-scope install path.

2. Confirm project-level .cursor/skills/ works for your setup:

   Reload Cursor window, check Skills panel. This is the path the issue reporter confirmed works.

Depending on the results, we then fix the README to document the path(s) that actually work and drop the bogus ~/.cursor/plugins/ instructions I wrote earlier.

Want me to set up one or both probes?