[BUG] Path Resolution & Sandbox Access Conflict for Global OpenSkills on macOS
Bug Description
In the macOS environment, due to system sandboxing and path resolution constraints, the AI agent cannot directly recognize or read skill files stored in the global directory (~/.claude/skills). Even after a successful installation, the agent fails to invoke skills because it cannot resolve the ~ symbol or lacks cross-directory access permissions.
Steps to Reproduce
- Install the tool globally on MacBook via
npm install -g openskills. - Run
openskills install <skill-name> --globalto download skills to the home directory. - Reference the global path in the project configuration (e.g., custom rules or system prompts).
- Attempt to trigger the skill in the AI chat interface (e.g., requesting a code review or doc drafting).
Expected Behavior
The AI agent should correctly identify the skill index in AGENTS.md and read the SKILL.md content from the specified path to execute the task.
Actual Behavior The AI reports "File not found," "Path does not exist," or completely ignores global skills, failing to enhance AI capabilities as expected.
Environment
- openskills version:
0.1.x(Latest stable) - Operating System: macOS (Darwin arm64)
- Node.js version: v20.6.0+
- AI agent: Custom IDE Extension (with local file read access)
Installation Context
- Global install (
npm i -g openskills) - Local install via npm link
- Installed skills:
code-reviewer,unit-test-gen,algorithmic-art,doc-coauthoring,skill-creator
Additional Context (Final Solution)
The issue was resolved using a Symbolic Link. By running ln -s ~/.claude/skills ./.skills-mirror in the project root, the global library was mirrored inside the workspace. The AI system prompt was then updated to direct the agent to read from this local mirror path, successfully bypassing permission and pathing obstacles.
Source: numman-ali/openskills