Cursor compatibility: directory structure, {baseDir}, and Claude-specific features

[dguido]

Summary

Skills in this repository are not discoverable by Cursor's native Agent Skills support due to directory structure and Claude Code-specific features. This issue tracks the gaps and potential solutions based on research into how other popular skills repositories handle cross-tool compatibility.

Background

Cursor now supports the Agent Skills open standard (nightly channel). It scans:

• .cursor/skills/<skill-name>/SKILL.md
• .claude/skills/<skill-name>/SKILL.md

Our current structure (plugins/<plugin>/skills/<skill>/SKILL.md) is not discovered.

Issues Found

1. Directory Structure Mismatch (Critical)

Current: plugins/<plugin>/skills/<skill>/SKILL.md (4 levels deep)
Expected: .claude/skills/<skill>/SKILL.md (flat)

Impact: 0/46 skills are discoverable by Cursor.

How others solve it:

Repository	Approach
anthropics/skills	Flat skills/<name>/SKILL.md at repo root
alirezarezvani/claude-skills	Universal installer with --agent flag
openskills	Multi-directory scanning + --universal flag
cursor-skills	MCP server abstracting directory structure

2. {baseDir} Variable (Medium)

The {baseDir} variable is Claude Code-specific and not part of the open standard. Other agents provide the skill's base path contextually but don't do template substitution.

Affected files (25+ occurrences):

• plugins/constant-time-analysis/skills/constant-time-analysis/SKILL.md
• plugins/culture-index/skills/interpreting-culture-index/SKILL.md
• plugins/dwarf-expert/skills/dwarf-expert/SKILL.md
• plugins/burpsuite-project-parser/skills/SKILL.md

How others solve it:

• anthropics/skills: Uses relative paths only, no {baseDir}
• openskills: Prints base directory before SKILL.md content; agent resolves contextually
• agentskills.io spec: Uses <location> field with absolute path; no variable substitution

Portable pattern:

## Running Scripts
From the skill directory:
uv run scripts/analyze.py input.file

3. Task Tool Reference (Low)

The Task tool is Claude Code-specific. One file references it:

• plugins/fix-review/commands/fix-review.md

Impact: Command won't work on Cursor (but commands are Claude-specific anyway).

Proposed Solutions

Option A: Symlink Layer (Minimal Change)

Add .claude/skills/ with symlinks to existing skills:

mkdir -p .claude/skills
for skill in plugins/*/skills/*/; do
  skill_name=$(basename "$skill")
  ln -s "../../$skill" ".claude/skills/$skill_name"
done

Pros: No restructuring, maintains plugin organization
Cons: Symlinks in git can be platform-dependent; {baseDir} issue remains

Option B: Build Script (CI-generated)

Generate a flat .claude/skills/ directory during CI/release:

# In CI or Makefile
for skill in plugins/*/skills/*/; do
  skill_name=$(basename "$skill")
  cp -r "$skill" ".claude/skills/$skill_name"
done

Pros: Clean output, can transform {baseDir} during copy
Cons: Adds build step, potential drift between source and output

Option C: Restructure to Flat Layout

Move skills to skills/<name>/SKILL.md at repo root, keeping plugins for commands/agents/hooks only.

Pros: Matches anthropics/skills pattern, direct Cursor compatibility
Cons: Breaking change, loses plugin grouping

Option D: Document as Claude Code-First

Keep current structure, document that:

1. Native Cursor support requires manual copy to .cursor/skills/
2. {baseDir} is Claude Code-specific
3. Use Claude Code extension in Cursor for full compatibility

Pros: No code changes
Cons: Poor Cursor UX

Recommendation

Option A or B with documentation updates:

1. Add symlinks or build script for .claude/skills/
2. Document {baseDir} as Claude Code-specific in CLAUDE.md
3. Add installation instructions for Cursor users in README
4. Consider replacing {baseDir} with relative paths in future skill updates

References

• Cursor Agent Skills docs
• agentskills.io specification
• OpenAI Codex skills
• anthropics/skills
• openskills
• Claude Skills Deep Dive