ai-skill-manager 1.0.0

A lightweight utility to download and manage skills for different AI coding assistants

AI Skill Manager

A lightweight utility to download and manage skills for different AI coding assistants. Available as both Python and Node.js packages with full feature parity.

Status: ✅ Production Ready - Version 1.0.0 released with complete selective download functionality, comprehensive test suite, and dual-language support.

✨ Features

• 🤖 Multi-AI Support: Works with GitHub Copilot, Claude, Cursor, Codeium, and more
• 🎯 Selective Downloads: Download specific skills using git sparse-checkout
• 📦 Batch Operations: Download multiple skills with configuration files
• 🔍 Repository Exploration: Browse available skills in repositories
• 🔄 Cross-Model Copying: Share skills between different AI assistants
• 📋 Dependency Management: Automatic Python/Node.js dependency installation
• 🌐 Cross-Platform: Available for both Python and Node.js ecosystems
• ⚡ Performance Optimized: Uses uv for fast Python package management

🆕 What's New in v1.0.0

• ✅ Complete Selective Download Implementation: Full sparse-checkout support for efficient skill downloads
• ✅ Dual Package Support: Both Python (PyPI) and Node.js (npm) packages with feature parity
• ✅ Property-Based Testing: Comprehensive test suite with 45+ tests including property-based tests
• ✅ Enhanced CLI: Rich command-line interface with batch operations and repository exploration
• ✅ Type Safety: Full TypeScript support with comprehensive type definitions
• ✅ Modern Tooling: Uses uv for Python package management and modern build tools
• ✅ CI/CD Pipeline: Automated testing and publishing via GitHub Actions
• ✅ Documentation: Complete API documentation and usage examples

Supported AI Models

• GitHub Copilot: .github/skills/
• Claude: .claude/skills/
• Antigravity: .agent/skills/
• Codex: .codex/skills/
• Cursor: .cursor/skills/
• Codeium: .codeium/skills/
• TabNine: .tabnine/skills/
• Kite: .kite/skills/

📋 Requirements

System Requirements

• Git: Version 2.25.0 or higher (required for sparse-checkout support)
• Python: 3.11+ (for Python package)
• Node.js: 14.0+ (for Node.js package)

Optional Dependencies

• uv: Recommended for faster Python package management
• SSH keys: For private repository access

📦 Installation

Python Package (PyPI)

# Using pip
pip install ai-skill-manager

# Using uv (recommended for faster installation)
uv add ai-skill-manager

Node.js Package (npm)

# Global installation
npm install -g ai-skill-manager

# Local installation
npm install ai-skill-manager

# Using yarn
yarn global add ai-skill-manager

🚀 Quick Start

Auto-detect AI Model

ai-skill detect

Download Skills

From any URL:

ai-skill download https://example.com/skill.py --name my-skill

From GitHub repository:

ai-skill github owner/repo path/to/skill.py --name custom-name

🎯 Selective Download (Recommended!)

Download specific skills from git repositories using sparse-checkout for efficient, targeted downloads:

# Download a specific skill folder from a repository
ai-skill download-selective https://github.com/user/skills-repo skills/data-analysis --name data-analyzer

# Download with custom options
ai-skill download-selective https://github.com/user/skills-repo skills/web-scraper \
  --name scraper --no-deps --timeout 600 --retries 5

# Download multiple skills from a batch configuration
ai-skill download-batch batch-config.json

🔍 Repository Exploration

Explore repositories to see available skills:

# List all available skills in a repository
ai-skill explore https://github.com/user/skills-repo

# Explore a specific branch
ai-skill explore https://github.com/user/skills-repo --branch develop

📋 Skill Management

List skills:

# For current/detected model
ai-skill list

# For all models
ai-skill list --all

Copy skills between models:

ai-skill copy skill-name --from claude --to github-copilot

Remove skills:

ai-skill remove skill-name

List supported models:

ai-skill models

Specify model manually:

ai-skill --model claude download https://example.com/skill.py

💻 Programmatic Usage

Python

from ai_skill_manager import SkillManager

manager = SkillManager()

# Auto-detect model
model = manager.detect_model()
print(f"Detected model: {model}")

# Download a skill
manager.download_skill_from_url(
    "https://example.com/skill.py", 
    "claude", 
    "my-skill"
)

# Selective download with options
result = manager.download_skill_selective(
    "https://github.com/user/skills-repo",
    "python/data-analysis",
    "claude",
    {
        'skillName': 'data-analyzer',
        'installDependencies': True,
        'useShallowClone': True,
        'timeout': 600
    }
)

# Batch download
requests = [
    {
        'repoUrl': 'https://github.com/user/skills-repo',
        'skillPath': 'python/skill1',
        'model': 'claude',
        'options': {'skillName': 'skill1'}
    },
    {
        'repoUrl': 'https://github.com/user/skills-repo', 
        'skillPath': 'python/skill2',
        'model': 'claude',
        'options': {'skillName': 'skill2'}
    }
]
results = manager.download_multiple_skills(requests)

# Explore repository
skills = manager.list_repository_skills("https://github.com/user/skills-repo")
print(f"Available skills: {skills}")

# List skills
skills = manager.list_skills("claude")
print(f"Skills: {skills}")

Node.js

const { SkillManager } = require('ai-skill-manager');

const manager = new SkillManager();

// Auto-detect model
const model = await manager.detectModel();
console.log(`Detected model: ${model}`);

// Download a skill
await manager.downloadSkillFromUrl(
    "https://example.com/skill.py", 
    "claude", 
    "my-skill"
);

// Selective download with options
const result = await manager.downloadSkillSelective(
    "https://github.com/user/skills-repo",
    "javascript/web-scraper", 
    "claude",
    {
        skillName: 'scraper',
        installDependencies: true,
        useShallowClone: true,
        timeout: 600
    }
);

// Batch download
const requests = [
    {
        repoUrl: 'https://github.com/user/skills-repo',
        skillPath: 'javascript/skill1',
        model: 'claude',
        options: { skillName: 'skill1' }
    },
    {
        repoUrl: 'https://github.com/user/skills-repo',
        skillPath: 'javascript/skill2', 
        model: 'claude',
        options: { skillName: 'skill2' }
    }
];
const results = await manager.downloadMultipleSkills(requests);

// Explore repository
const skills = await manager.listRepositorySkills("https://github.com/user/skills-repo");
console.log(`Available skills: ${skills}`);

// List skills
const skills = await manager.listSkills("claude");
console.log(`Skills: ${skills}`);

📚 TypeScript API Documentation

Core Interfaces

SelectiveDownloadOptions

interface SelectiveDownloadOptions {
  skillName?: string;              // Custom name for the downloaded skill
  useShallowClone?: boolean;       // Use shallow git clone (default: true)
  installDependencies?: boolean;   // Install Python/Node.js dependencies (default: true)
  dependencyManager?: 'uv' | 'pip' | 'auto';  // Python package manager preference
  timeout?: number;                // Timeout in seconds (default: 300)
  retryAttempts?: number;          // Number of retry attempts (default: 3)
}

SkillDownloadRequest

interface SkillDownloadRequest {
  repoUrl: string;                 // Git repository URL
  skillPath: string;               // Path to skill within repository
  model: ModelType;                // Target AI model
  options?: SelectiveDownloadOptions;
}

DownloadResult

interface DownloadResult {
  success: boolean;                // Whether download succeeded
  skillName: string;               // Name of the downloaded skill
  model: ModelType;                // Target AI model
  error?: string;                  // Error message if failed
  downloadedFiles: string[];       // List of downloaded files
  installedDependencies?: string[]; // List of installed dependencies
}

RepositoryInfo

interface RepositoryInfo {
  url: string;                     // Repository URL
  defaultBranch: string;           // Default branch name
  availableSkills: string[];       // List of available skill paths
  lastUpdated: Date;               // Last update timestamp
  size: number;                    // Repository size in bytes
}

SkillManager Methods

Selective Download Methods

// Download a specific skill using sparse-checkout
downloadSkillSelective(
  repoUrl: string, 
  skillPath: string, 
  model: ModelType, 
  options?: SelectiveDownloadOptions
): Promise<DownloadResult>

// Download multiple skills in batch
downloadMultipleSkills(
  requests: SkillDownloadRequest[]
): Promise<DownloadResult[]>

// List available skills in a repository
listRepositorySkills(
  repoUrl: string, 
  branch?: string
): Promise<string[]>

// Update an existing skill from its source repository
updateSkillFromRepository(
  skillName: string, 
  model: ModelType
): Promise<void>

Traditional Download Methods

// Download skill from any URL
downloadSkillFromUrl(
  url: string, 
  model: ModelType, 
  skillName?: string
): Promise<void>

// Download skill from GitHub repository
downloadGithubSkill(
  repo: string, 
  path: string, 
  model: ModelType, 
  skillName?: string
): Promise<void>

Skill Management Methods

// List skills for a model
listSkills(model: ModelType): Promise<string[]>

// Remove a skill
removeSkill(model: ModelType, skillName: string): Promise<boolean>

// Copy skill between models
copySkill(
  sourceModel: ModelType, 
  targetModel: ModelType, 
  skillName: string
): Promise<boolean>

// Auto-detect current AI model
detectModel(): Promise<ModelType | null>

// Get list of supported models
getSupportedModels(): ModelType[]

Error Handling

The TypeScript implementation provides comprehensive error handling with typed exceptions:

try {
  const result = await manager.downloadSkillSelective(
    'https://github.com/user/skills-repo',
    'typescript/web-scraper',
    'claude',
    { timeout: 600, retryAttempts: 5 }
  );
  
  if (result.success) {
    console.log(`Downloaded ${result.downloadedFiles.length} files`);
  } else {
    console.error(`Download failed: ${result.error}`);
  }
} catch (error) {
  if (error instanceof GitError) {
    console.error(`Git operation failed: ${error.message}`);
  } else if (error instanceof NetworkError) {
    console.error(`Network error: ${error.message}`);
  } else {
    console.error(`Unexpected error: ${error.message}`);
  }
}

Advanced Usage Examples

Custom Configuration

import { SkillManager } from 'ai-skill-manager';

const manager = new SkillManager({
  projectRoot: '/custom/project/path'
});

// Set environment variables for configuration
process.env.AI_SKILL_MANAGER_TIMEOUT = '600';
process.env.AI_SKILL_MANAGER_RETRIES = '5';
process.env.AI_SKILL_MANAGER_USE_UV = 'true';

Progress Monitoring

// Monitor download progress with custom logging
const result = await manager.downloadSkillSelective(
  repoUrl,
  skillPath,
  model,
  {
    timeout: 600,
    onProgress: (stage: string, progress: number) => {
      console.log(`${stage}: ${progress}%`);
    }
  }
);

Batch Operations with Error Handling

const requests: SkillDownloadRequest[] = [
  {
    repoUrl: 'https://github.com/user/skills-repo',
    skillPath: 'typescript/skill1',
    model: 'claude',
    options: { skillName: 'skill1', timeout: 300 }
  },
  {
    repoUrl: 'https://github.com/user/skills-repo',
    skillPath: 'typescript/skill2',
    model: 'claude',
    options: { skillName: 'skill2', timeout: 300 }
  }
];

const results = await manager.downloadMultipleSkills(requests);

// Process results
const successful = results.filter(r => r.success);
const failed = results.filter(r => !r.success);

console.log(`✓ ${successful.length} skills downloaded successfully`);
if (failed.length > 0) {
  console.log(`✗ ${failed.length} skills failed:`);
  failed.forEach(result => {
    console.log(`  - ${result.skillName}: ${result.error}`);
  });
}

📖 Examples

# Download a Python skill for Claude
ai-skill --model claude download https://raw.githubusercontent.com/user/repo/main/skills/data-analysis.py

# Download from GitHub for auto-detected model
ai-skill github anthropic/claude-skills skills/code-review.md

# Selective download - download only specific skill folders
ai-skill download-selective https://github.com/awesome-ai/skills-collection python-tools/data-processor

# Batch download multiple skills
ai-skill download-batch my-skills-config.json

# Explore repository structure
ai-skill explore https://github.com/awesome-ai/skills-collection

# Copy a skill from Claude to GitHub Copilot
ai-skill copy code-review.md --from claude --to github-copilot

# List all skills across all models
ai-skill list --all

Batch Configuration Example

Create a batch-config.json file for downloading multiple skills:

{
  "skills": [
    {
      "repoUrl": "https://github.com/user/skills-repo",
      "skillPath": "python/data-analysis",
      "options": {
        "skillName": "data-analyzer",
        "installDependencies": true,
        "useShallowClone": true
      }
    },
    {
      "repoUrl": "https://github.com/user/skills-repo", 
      "skillPath": "javascript/web-scraper",
      "options": {
        "skillName": "scraper",
        "timeout": 600
      }
    }
  ]
}

Features

• Auto-detection: Automatically detects which AI model you're using
• Multi-format support: Handles Python, JavaScript, JSON, YAML, and Markdown files
• GitHub integration: Easy downloading from GitHub repositories
• Selective downloads: Download specific skill folders using git sparse-checkout
• Batch operations: Download multiple skills with configuration files
• Repository exploration: Browse available skills in repositories
• Cross-model copying: Share skills between different AI assistants
• Clean organization: Maintains proper directory structure for each model
• Dependency management: Automatic Python dependency installation with uv/pip
• Cross-platform: Available for both Python and Node.js ecosystems

⚙️ Configuration

Environment Variables

• AI_SKILL_MANAGER_TIMEOUT: Default timeout for git operations (seconds, default: 300)
• AI_SKILL_MANAGER_RETRIES: Default number of retry attempts (default: 3)
• AI_SKILL_MANAGER_USE_UV: Force use of uv for Python dependencies (true/false)

Configuration File

Create .ai-skill-manager.json in your project root:

{
  "defaultTimeout": 600,
  "defaultRetries": 5,
  "preferUv": true,
  "tempDirectory": "/tmp/ai-skills",
  "gitOptions": {
    "depth": 1,
    "singleBranch": true
  }
}

🔧 Troubleshooting

Common Issues

Git not found

# Install git on your system
# macOS: brew install git
# Ubuntu: sudo apt-get install git
# Windows: Download from https://git-scm.com/

Authentication failures for private repositories

# Set up SSH key authentication
ssh-keygen -t ed25519 -C "[e-mail]"
# Add the public key to your Git provider

# Or use personal access tokens for HTTPS
git config --global credential.helper store

Dependency installation failures

# Install uv for faster Python package management
pip install uv

# Or ensure pip is up to date
python -m pip install --upgrade pip

Permission errors

# Ensure you have write permissions to the skill directories
chmod -R 755 ~/.github/skills/  # Example for GitHub Copilot

Debug Mode

Enable verbose logging:

export AI_SKILL_MANAGER_DEBUG=1
ai-skill download-selective https://github.com/user/repo skill-path

📦 Publishing

Python Package

# Build and publish to PyPI
uv build
uv publish

Node.js Package

# Build and publish to npm
npm run build
npm publish

🛠️ Development

Prerequisites

• Python 3.11+ with uv package manager (recommended)
• Node.js 16+ with npm
• Git 2.25+ (for sparse-checkout support)

Setup

# Clone the repository
git clone https://github.com/yourusername/ai-skill-manager.git
cd ai-skill-manager

# Install Python dependencies with uv (recommended)
uv sync --dev

# Or with pip
pip install -e ".[dev]"

# Install Node.js dependencies
npm install

🔧 Development Workflow

# Python development
uv run pytest                    # Run Python tests
uv run ruff check .             # Lint Python code  
uv run ruff format .            # Format Python code
uv run mypy ai_skill_manager/   # Type check Python code
uv run ai-skill --help          # Test CLI

# Node.js development
npm test                        # Run TypeScript tests
npm run lint                    # Lint TypeScript code
npm run type-check             # Type check TypeScript code
npm run build                  # Build TypeScript
node bin/ai-skill.js --help    # Test CLI

# Build packages
uv build                       # Build Python package (wheel + sdist)
npm run build                  # Build TypeScript package

🧪 Testing

# Run all tests
uv run pytest tests/ -v        # Python tests (45+ tests including property-based)
npm test                       # TypeScript tests (31+ tests)

# Run specific test types
uv run pytest tests/test_*_properties.py  # Property-based tests only
npm run test:watch                         # Watch mode for TypeScript tests

# Run integration tests
uv run pytest tests/ -m integration

# Test coverage
uv run pytest --cov=ai_skill_manager tests/
npm run test -- --coverage

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run the test suite: uv run pytest && npm test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

🚀 Release Process

Releases are automated via GitHub Actions:

1. Update version numbers in pyproject.toml and package.json
2. Update CHANGELOG.md with new features and changes
3. Create a git tag: git tag v1.0.1
4. Push the tag: git push origin v1.0.1
5. GitHub Actions will automatically build and publish to PyPI and npm

License

This project is licensed under the MIT License - see the LICENSE file for details.