@open-skills-hub/mcp-server 1.0.0

package/PLATFORM-SUPPORT.md

@@ -0,0 +1,385 @@
+# Multi-Platform Support
+
+SkillsHub MCP Server now includes intelligent platform detection and automatic directory management for seamless skill installation across different AI agent platforms.
+
+## Supported Platforms
+
+The MCP server automatically detects and supports the following platforms:
+
+| Platform | Default Skills Directory | Detection Method |
+|----------|-------------------------|------------------|
+| **Cursor** | `~/.cursor/skills` | Directory existence or `CURSOR_USER_DATA` env var |
+| **Codex** | `~/.codex/skills` | Directory existence or `CODEX_HOME` env var |
+| **CodeBuddy** | `~/.codebuddy/skills` | Directory existence or `CODEBUDDY_HOME` env var |
+| **Claude** | `~/.claude/skills` | Directory existence |
+| **Anthropic** | `~/.anthropic/skills` | Directory existence |
+| **Generic** | `~/.skills` | Fallback when no platform detected |
+
+## How Platform Detection Works
+
+The system uses a multi-step detection process:
+
+1. **Environment Variables** - Checks for platform-specific environment variables
+2. **Directory Scanning** - Looks for existing platform directories in user home
+3. **Explicit Parameter** - Respects user-specified `platform` parameter
+4. **Fallback** - Uses generic `~/.skills` if no platform is detected
+
+## Usage Examples
+
+### Simplest Usage (Recommended)
+
+Let the system auto-detect everything:
+
+```json
+{
+  "tool": "skills_install",
+  "arguments": {
+    "name": "@official/pdf-parser"
+  }
+}
+```
+
+**Result:**
+- Platform automatically detected (e.g., "cursor")
+- Directory automatically created (`~/.cursor/skills/`)
+- Skill installed to `~/.cursor/skills/pdf-parser/`
+
+### Specify Platform
+
+Install for a specific platform regardless of current environment:
+
+```json
+{
+  "tool": "skills_install",
+  "arguments": {
+    "name": "@official/pdf-parser",
+    "platform": "codex"
+  }
+}
+```
+
+**Result:**
+- Uses Codex directory: `~/.codex/skills/`
+- Directory created if it doesn't exist
+- Skill installed to `~/.codex/skills/pdf-parser/`
+
+### Custom Directory
+
+Override platform detection with a custom path:
+
+```json
+{
+  "tool": "skills_install",
+  "arguments": {
+    "name": "@official/pdf-parser",
+    "targetDir": "/Users/george/projects/my-app/skills"
+  }
+}
+```
+
+**Result:**
+- Uses specified custom directory
+- Platform detection bypassed
+- Skill installed to custom location
+
+## Directory Creation
+
+All directories are created automatically if they don't exist:
+
+1. **Parent Directory** - Creates the main skills directory
+2. **Skill Directory** - Creates the skill-specific subdirectory
+3. **Subdirectories** - Creates any nested directories for attachments (scripts/, references/, etc.)
+
+**Example:**
+
+If `~/.cursor/skills` doesn't exist:
+```
+Before:  ~/
+After:   ~/.cursor/
+         ~/.cursor/skills/
+         ~/.cursor/skills/pdf-parser/
+         ~/.cursor/skills/pdf-parser/SKILL.md
+         ~/.cursor/skills/pdf-parser/scripts/
+         ~/.cursor/skills/pdf-parser/scripts/extract.py
+```
+
+## Platform-Specific Considerations
+
+### Cursor IDE
+
+- Default: `~/.cursor/skills`
+- Skills are automatically available to Cursor AI agents
+- Use the built-in Cursor skills system to manage loaded skills
+
+### Codex (OpenAI)
+
+- Default: `~/.codex/skills`
+- May coexist with Codex's native skill system
+- Skills follow Anthropic Agent Skills format (broader compatibility)
+
+### CodeBuddy
+
+- Default: `~/.codebuddy/skills`
+- Skills can be loaded by CodeBuddy's agent system
+- Check CodeBuddy documentation for skill activation
+
+### Generic/Custom Platforms
+
+- Default: `~/.skills`
+- Universal location that any platform can read from
+- Useful for testing or cross-platform development
+
+## Migration Guide
+
+### From Manual Installation
+
+**Before (required explicit paths):**
+```json
+{
+  "name": "@official/skill-name",
+  "targetDir": "/Users/george/.cursor/skills"
+}
+```
+
+**After (automatic):**
+```json
+{
+  "name": "@official/skill-name"
+}
+```
+
+### From Other Skill Systems
+
+If you have existing skills in platform-specific locations, SkillsHub will:
+
+1. Detect the existing directory
+2. Install new skills alongside existing ones
+3. Not interfere with native platform skill systems
+
+## API Changes
+
+### Updated Tool Definition
+
+```typescript
+{
+  name: 'skills_install',
+  parameters: {
+    name: string;        // Required: skill name
+    targetDir?: string;  // Optional: custom directory
+    platform?: string;   // Optional: target platform
+    version?: string;    // Optional: specific version
+  }
+}
+```
+
+### Breaking Changes
+
+⚠️ **Note:** `targetDir` is now **optional** instead of required.
+
+**Migration:**
+- Old code specifying `targetDir` will continue to work
+- New code can omit `targetDir` for automatic detection
+- No action required for existing integrations
+
+## Best Practices for AI Agents
+
+### 1. Prefer Auto-Detection
+
+```typescript
+// ✅ Recommended - Simple and works everywhere
+await tools.skills_install({ name: "@official/skill-name" });
+
+// ❌ Avoid unless specifically needed
+await tools.skills_install({ 
+  name: "@official/skill-name",
+  targetDir: "/some/path" 
+});
+```
+
+### 2. Only Specify Platform When Needed
+
+```typescript
+// ✅ When user explicitly mentions a platform
+User: "Install this for Codex"
+await tools.skills_install({ 
+  name: "@official/skill-name",
+  platform: "codex" 
+});
+
+// ✅ When installing for multiple platforms
+for (const platform of ["cursor", "codex"]) {
+  await tools.skills_install({ 
+    name: "@official/skill-name",
+    platform 
+  });
+}
+```
+
+### 3. Trust the Detection
+
+The detection algorithm is robust and handles:
+- Missing directories (creates them)
+- Multiple platforms on same machine (picks primary)
+- Custom setups (falls back gracefully)
+
+### 4. Inform Users About Auto-Creation
+
+When directories are auto-created, the response includes:
+- Detected platform name
+- Created directory path
+- Confirmation that directory was auto-created
+
+Share this info with users so they know where skills were installed.
+
+## Troubleshooting
+
+### Platform Not Detected
+
+**Symptoms:**
+- Skills installed to `~/.skills` instead of platform-specific directory
+- Wrong platform detected
+
+**Solutions:**
+1. Explicitly specify platform:
+   ```json
+   { "name": "skill", "platform": "cursor" }
+   ```
+
+2. Create platform directory manually:
+   ```bash
+   mkdir -p ~/.cursor/skills
+   ```
+
+3. Set environment variable:
+   ```bash
+   export CURSOR_USER_DATA=/path/to/cursor
+   ```
+
+### Directory Permission Issues
+
+**Symptoms:**
+- `EACCES` or `EPERM` errors
+- Cannot create directory
+
+**Solutions:**
+1. Check directory permissions:
+   ```bash
+   ls -la ~/.cursor/
+   ```
+
+2. Fix permissions if needed:
+   ```bash
+   chmod 755 ~/.cursor/skills
+   ```
+
+3. Use a custom directory in user-writable location:
+   ```json
+   { "name": "skill", "targetDir": "~/Documents/skills" }
+   ```
+
+### Skills Not Loading in Platform
+
+**Symptoms:**
+- Skills installed successfully but not available in platform
+- Platform doesn't recognize skills
+
+**Solutions:**
+1. Check platform-specific skill loading mechanism
+2. Restart the platform/IDE
+3. Verify skill format matches platform expectations
+4. Check platform documentation for skill activation
+
+## Technical Implementation
+
+### Detection Function
+
+```typescript
+function detectPlatform(): string {
+  const homeDir = process.env.HOME || '~';
+  
+  // Check existing directories
+  for (const [platform, dir] of Object.entries(PLATFORM_SKILLS_DIRS)) {
+    if (fs.existsSync(dir.replace('~', homeDir))) {
+      return platform;
+    }
+  }
+  
+  // Check environment variables
+  if (process.env.CURSOR_USER_DATA) return 'cursor';
+  if (process.env.CODEX_HOME) return 'codex';
+  
+  return 'unknown';
+}
+```
+
+### Directory Resolution
+
+```typescript
+function getDefaultSkillsDir(platform?: string): string {
+  const homeDir = process.env.HOME || '~';
+  const detectedPlatform = platform || detectPlatform();
+  
+  return PLATFORM_SKILLS_DIRS[detectedPlatform]?.replace('~', homeDir)
+    || path.join(homeDir, '.skills');
+}
+```
+
+## Future Enhancements
+
+Planned improvements for platform support:
+
+- [ ] VSCode integration
+- [ ] JetBrains AI support
+- [ ] Continue.dev detection
+- [ ] Aider integration
+- [ ] Per-project skill directories
+- [ ] Skill symlinking across platforms
+- [ ] Platform-specific skill validation
+
+## Contributing
+
+To add support for a new platform:
+
+1. Add platform directory mapping in `PLATFORM_SKILLS_DIRS`
+2. Add detection logic in `detectPlatform()`
+3. Update documentation and examples
+4. Test with the new platform
+5. Submit a pull request
+
+Example:
+
+```typescript
+const PLATFORM_SKILLS_DIRS = {
+  // ... existing platforms
+  'new-platform': '~/.new-platform/skills',
+};
+
+function detectPlatform() {
+  // ... existing checks
+  if (process.env.NEW_PLATFORM_HOME) return 'new-platform';
+  // ...
+}
+```
+
+## Learn More
+
+- [Main README](./README.md) - Full MCP server documentation
+- [Examples](./EXAMPLES.md) - Practical usage examples
+- [SkillsHub Documentation](../../README.md) - Project overview
+
+## Feedback
+
+Found a platform that should be supported? Have suggestions for improving detection?
+
+Open an issue or submit feedback using:
+```json
+{
+  "tool": "skills_feedback",
+  "arguments": {
+    "name": "@open-skills-hub/mcp-server",
+    "type": "suggestion",
+    "rating": 5,
+    "comment": "Add support for XYZ platform at ~/.xyz/skills"
+  }
+}
+```

package/QUICK-REFERENCE-PLATFORMS.md

@@ -0,0 +1,128 @@
+# Platform Support - Quick Reference
+
+> **TL;DR**: Just use `{ "name": "skill-name" }` - the system auto-detects everything!
+
+## 🚀 Simplest Usage
+
+```json
+{
+  "tool": "skills_install",
+  "arguments": {
+    "name": "@official/pdf-parser"
+  }
+}
+```
+
+**That's it!** The system will:
+- ✅ Detect your platform (Cursor, Codex, etc.)
+- ✅ Use the correct default directory
+- ✅ Create directories if needed
+- ✅ Install the skill
+
+## 📍 Default Directories
+
+| Platform | Directory |
+|----------|-----------|
+| Cursor | `~/.cursor/skills` |
+| Codex | `~/.codex/skills` |
+| CodeBuddy | `~/.codebuddy/skills` |
+| Claude | `~/.claude/skills` |
+| Anthropic | `~/.anthropic/skills` |
+| *Fallback* | `~/.skills` |
+
+## 🎯 Three Ways to Install
+
+### 1. Auto-Detect (Recommended)
+```json
+{ "name": "@official/skill" }
+```
+System detects platform and uses default directory.
+
+### 2. Specify Platform
+```json
+{
+  "name": "@official/skill",
+  "platform": "cursor"
+}
+```
+Force install to specific platform's directory.
+
+### 3. Custom Directory
+```json
+{
+  "name": "@official/skill",
+  "targetDir": "/custom/path"
+}
+```
+Override everything with custom location.
+
+## 🆕 What Changed?
+
+| Before | After |
+|--------|-------|
+| `targetDir` required | `targetDir` optional |
+| Manual directory creation | Auto-created |
+| Must know platform | Auto-detected |
+
+## ✅ Backward Compatible
+
+Old code still works:
+```json
+{
+  "name": "@official/skill",
+  "targetDir": "/Users/george/.cursor/skills"
+}
+```
+
+## 🛠️ For AI Agents
+
+**Simple Rule**: Only ask for directory if user explicitly wants custom location.
+
+```typescript
+// ✅ Default behavior
+User: "Install the PDF skill"
+→ { name: "@official/pdf-parser" }
+
+// ✅ Platform specified
+User: "Install for Codex"
+→ { name: "@official/pdf-parser", platform: "codex" }
+
+// ✅ Custom location
+User: "Install to my project at /path/to/project"
+→ { name: "@official/pdf-parser", targetDir: "/path/to/project/skills" }
+```
+
+## 📚 Full Documentation
+
+- [Platform Support Guide](./PLATFORM-SUPPORT.md) - Complete details
+- [Changelog](./CHANGELOG-PLATFORM.md) - What's new
+- [Examples](./EXAMPLES.md) - Practical examples
+- [README](./README.md) - Full documentation
+
+## 💡 Pro Tips
+
+1. **Let it auto-detect** - Works 99% of the time
+2. **Only specify platform** when installing for different platform than current
+3. **Only use custom dir** when user explicitly wants non-standard location
+4. **Trust the system** - It handles missing directories automatically
+
+## ❓ Troubleshooting
+
+**Wrong platform detected?**
+```json
+{ "name": "skill", "platform": "cursor" }
+```
+
+**Need custom location?**
+```json
+{ "name": "skill", "targetDir": "/custom/path" }
+```
+
+**Permission errors?**
+```bash
+chmod 755 ~/.cursor/skills
+```
+
+---
+
+**Updated**: 2026-02-05 | **Version**: 2.0.0