ClaudeSkill CLI

Command-line tool for bootstrapping and updating ClaudeSkill projects.

Version: 1.16.0

Overview

ClaudeSkill CLI (cs) is a command-line tool for bootstrapping and updating projects from private GitHub releases. Built with Bun and TypeScript, provides fast, secure project setup and maintenance.

Key Features:

• Multi-tier GitHub authentication (gh CLI → env vars → keychain → prompt)
• Streaming downloads with progress tracking and platform optimizations
• Offline installation from local archives or directories
• Smart file merging with conflict detection
• Automatic skills directory migration with parallel processing
• Secure credential storage using OS keychain
• Beautiful CLI interface with interactive prompts
• Optional package installation (OpenCode, Gemini)
• System dependency auto-installation
• Platform-specific optimizations (macOS native unzip, adaptive concurrency)
• Intelligent update notifications with 7-day cache

Documentation

Comprehensive documentation in /docs:

• Codebase Summary - Overview, structure, key components
• Project Overview & PDR - Requirements, features, roadmap
• System Architecture - Architecture diagrams, data flow
• Code Standards - Coding conventions, best practices
• Project Roadmap - Release timeline, feature status
• Deployment Guide - Release procedures

Prerequisites

Before using ClaudeSkill CLI, you need to:

1. Purchase a ClaudeSkill Starter Kit from ClaudeSkill.cc
2. Get Repository Access: After purchase, you'll receive access to the private GitHub repository containing your kit
3. Create a GitHub Personal Access Token (PAT) with repo scope to download releases

Without a purchased kit and repository access, the CLI will not be able to download any project templates.

Installation

The ClaudeSkill CLI is published on npm at npmjs.com/package/claudeskill-cli.

Using npm (Recommended)

npm install -g claudeskill-cli

Using Bun

bun add -g claudeskill-cli

Using Yarn

yarn global add claudeskill-cli

Using pnpm

pnpm add -g claudeskill-cli

After installation, verify it's working:

cs --version

Usage

Create New Project

# Interactive mode
cs new

# With options
cs new --dir my-project --kit engineer

# Show beta versions
cs new --beta

# With exclude patterns
cs new --exclude "*.log" --exclude "temp/**"

# Optional packages (OpenCode, Gemini)
cs new --opencode --gemini

# Install skills dependencies (Python, Node packages, system tools)
cs new --install-skills

# Command prefix (/cs: namespace to avoid conflicts)
cs new --prefix

# Offline installation (from local archive or directory)
cs new --archive ~/downloads/engineer-v1.16.0.zip
cs new --kit-path ~/extracted-kit/

Flags:

• --install-skills: Auto-install Python packages, system tools (FFmpeg, ImageMagick), Node.js packages
• --prefix: Move commands to /cs: namespace (/plan → /cs:plan)
• --beta: Show pre-release versions in selection
• --opencode/--gemini: Install optional packages
• --archive <path>: Use local archive (zip/tar.gz) instead of downloading
• --kit-path <path>: Use local kit directory instead of downloading

Initialize or Update Project

Note: Run from project root.

# Interactive mode
cs init

# Non-interactive mode with sensible defaults
cs init --yes
cs init -y

# Combine with other flags
cs init -g --kit engineer -y

# With options
cs init --kit engineer --beta

# Global mode (platform-specific paths)
cs init --global

# Fresh installation (⚠️ DESTRUCTIVE - removes ALL customizations)
cs init --fresh

# With exclude patterns and prefix
cs init --exclude "*.local" --prefix

# Offline installation (from local archive or directory)
cs init --archive ~/downloads/engineer-v1.16.0.zip
cs init --kit-path ~/extracted-kit/

Flags:

• --yes/-y: Non-interactive mode with sensible defaults (skip all prompts)
• --global/-g: Use platform-specific config (macOS/Linux: ~/.claude, Windows: %USERPROFILE%.claude)
• --fresh: Clean reinstall, removes .claude directory (requires "yes" confirmation)
• --beta: Show pre-release versions
• --prefix: Apply /cs: namespace to commands
• --archive <path>: Use local archive (zip/tar.gz) instead of downloading
• --kit-path <path>: Use local kit directory instead of downloading

Default Behavior with -y Flag:

| Prompt | Default | |--------|---------| | Select ClaudeSkill | engineer (first option) | | Target directory | Current directory (.) | | Version selection | Latest stable release | | Google Gemini setup | Skip | | Other optional features | Skip |

Update CLI

Keep the ClaudeSkill CLI up to date:

# Check for CLI updates
cs update --check

# Update to latest version
cs update

# Update to specific version
cs update --version 1.17.0

# Update to beta / skip confirmation
cs update --beta
cs update --yes

The CLI notifies you when updates are available via cs --version.

Skills Migration:

• Auto-detects structure changes (flat → categorized)
• Preserves customizations (SHA-256 hashing)
• Creates backup before migration
• Rollback on failure

List Available Versions

# Show all available versions for all kits
cs versions

# Filter by specific kit
cs versions --kit engineer
cs versions --kit marketing

# Show more versions (default: 30)
cs versions --limit 50

# Include prereleases and drafts
cs versions --all

Diagnostics & Doctor

# Full health check (default)
cs doctor

# Verbose mode with execution timing and command details
cs doctor --verbose

# Generate shareable diagnostic report (prompts for gist upload)
cs doctor --report

# Auto-fix all fixable issues
cs doctor --fix

# CI mode: no prompts, exit 1 on failures
cs doctor --check-only

# Machine-readable JSON output
cs doctor --json

# Combine flags
cs doctor --verbose --check-only --json
cs doctor --verbose --fix

Health Checks:

• System: Node.js, npm, Python, pip, Claude CLI, git, gh CLI
• ClaudeSkill: Global/project installation, versions, skills
• Auth: GitHub CLI authentication, repository access
• Project: package.json, node_modules, lock files
• Modules: Dynamic skill dependency resolution

Auto-Fix Capabilities: | Issue | Fix Action | |-------|------------| | Missing dependencies | Install via package manager | | Missing gh auth | Run gh auth login | | Corrupted node_modules | Reinstall dependencies | | Missing global install | Run cs init --global | | Missing skill deps | Install in skill directory |

Exit Codes:

• 0: All checks pass or issues fixed
• 1: Failures detected (only with --check-only)

Note: cs diagnose is deprecated. Use cs doctor instead.

Uninstall

Remove ClaudeSkill installations from your system:

cs uninstall              # Interactive mode - prompts for scope and confirmation
cs uninstall --local      # Uninstall only local installation (current project)
cs uninstall --global     # Uninstall only global installation (~/.claude/)
cs uninstall -l -y        # Local only, skip confirmation
cs uninstall -g -y        # Global only, skip confirmation
cs uninstall --yes        # Non-interactive - skip confirmation (for scripts)

Scope Selection:

• When both local and global installations exist, you'll be prompted to choose:
  • Local only: Remove from current project (.claude/)
  • Global only: Remove from user directory (~/.claude/)
  • Both: Remove all ClaudeSkill installations
• Use --local or --global flags to skip the prompt

What it does:

• Detects local .claude directory in current project
• Detects global ~/.claude ClaudeSkill installation
• Shows paths before deletion
• Requires confirmation (unless --yes flag)
• Removes ClaudeSkill subdirectories (commands/, agents/, skills/, workflows/, hooks/, metadata.json)
• Preserves user configs like settings.json, settings.local.json, and CLAUDE.md

Note: Only removes valid ClaudeSkill installations (with metadata.json). Regular .claude directories from Claude Desktop are not affected.

Other Commands

# Show CLI version (shows local + global kit versions)
cs --version

# Show help
cs --help
cs -h

# Command-specific help
cs new --help
cs init --help
cs versions --help

Debugging

cs new --verbose              # Enable verbose logging
cs new --verbose --log-file debug.log  # Save to file
CLAUDEKIT_VERBOSE=1 cs new   # Via environment variable

Cache Configuration

Release data is cached locally to improve performance. You can configure the cache TTL:

# Set custom cache TTL (in seconds, default: 3600 = 1 hour)
CK_CACHE_TTL=7200 cs versions    # Cache for 2 hours
CK_CACHE_TTL=0 cs versions       # Disable caching (always fetch fresh)

# Permanent configuration (add to ~/.bashrc or ~/.zshrc)
export CK_CACHE_TTL=1800         # 30 minutes

Cache Location: ~/.claudeskill/cache/releases/

Update Notifications

The cs --version command checks for newer versions of your installed ClaudeSkill and displays a notification if an update is available. The check is cached for 7 days to minimize API calls.

Disable Update Notifications:

# Set environment variable to disable
NO_UPDATE_NOTIFIER=1 cs --version

# Windows (permanent)
[System.Environment]::SetEnvironmentVariable("NO_UPDATE_NOTIFIER", "1", [System.EnvironmentVariableTarget]::User)

# macOS/Linux (add to ~/.bashrc or ~/.zshrc)
export NO_UPDATE_NOTIFIER=1

Cache Location: ~/.claudeskill/cache/version-check.json (Windows: %USERPROFILE%\.claudeskill\cache\)

Authentication

The CLI requires GitHub authentication to download releases from private repositories.

Authentication Flow

┌─────────────────────────────────────────────────┐
│          Multi-Tier Authentication               │
│                                                  │
│  1. GitHub CLI (gh auth token)                  │
│       ↓ (if not available)                       │
│  2. Environment Variables (GITHUB_TOKEN)        │
│       ↓ (if not set)                             │
│  3. Config File (~/.claudeskill/config.json)      │
│       ↓ (if not found)                           │
│  4. OS Keychain (secure storage)                │
│       ↓ (if not stored)                          │
│  5. User Prompt (with save option)              │
└─────────────────────────────────────────────────┘

Quick Setup

Step 1: Install GitHub CLI

# Windows
winget install GitHub.cli

# macOS
brew install gh

# Linux
sudo apt install gh

Step 2: Authenticate with GitHub CLI

gh auth login

When prompted, follow these steps:

1. Select GitHub.com
2. Select HTTPS (or SSH if preferred)
3. Authenticate Git? → Yes
4. Select Login with a web browser (⚠️ recommended)
5. Copy the one-time code shown
6. Press Enter to open browser and paste the code
7. Authorize GitHub CLI

⚠️ Important: Select "Login with a web browser" - do NOT use "Paste an authentication token" as PAT authentication is no longer supported for accessing private repositories.

Troubleshooting

Run the doctor command to diagnose issues:

# Interactive diagnostics
cs doctor

# Generate report for support
cs doctor --report

# CI/automation
cs doctor --check-only --json

# Verbose logging
cs new --verbose
cs init --verbose

Common Issues:

• "Access denied": Run cs doctor to check auth, use --fix to auto-repair
• "Authentication failed": Run cs doctor --fix to re-authenticate, or manually run gh auth login (select 'Login with a web browser')
• "GitHub CLI not authenticated": Run gh auth login and select 'Login with a web browser' (NOT 'Paste token')
• Module errors: Run cs doctor --fix to reinstall skill dependencies
• Need help: Run cs doctor --report and share the gist URL

Available Kits

ClaudeSkill offers premium starter kits available for purchase at ClaudeSkill.cc:

• engineer: ClaudeSkill Engineer - Engineering toolkit for building with Claude
• marketing: ClaudeSkill Marketing - [Coming Soon]

Each kit provides a comprehensive project template with best practices, tooling, and workflows optimized for Claude Code development.

Configuration

Configuration is stored in ~/.claudeskill/config.json:

{
  "github": {
    "token": "stored_in_keychain"
  },
  "defaults": {
    "kit": "engineer",
    "dir": "."
  }
}

Protected Files

The following file patterns are protected and will not be overwritten during updates:

• .env, .env.local, .env.*.local
• *.key, *.pem, *.p12
• node_modules/**, .git/**
• dist/**, build/**

Excluding Files

Use --exclude flag with glob patterns to skip files:

cs new --exclude "*.log" --exclude "temp/**"
cs update --exclude "node_modules/**" --exclude "dist/**"

Patterns: * (any chars), ** (recursive), ? (single char), [abc], {a,b} Restrictions: No absolute paths, no path traversal (..), 1-500 chars Note: User patterns are ADDED to default protected patterns

Custom .claude Files & Skills Migration

Custom File Preservation: The CLI automatically preserves your custom .claude/ files during updates:

• Custom slash commands
• Personal workflows
• Project-specific configurations
• Any other custom files in .claude/ directory

Skills Directory Migration: Automatic migration when structure changes (flat → categorized):

• Detection: Manifest-based + heuristic fallback
• Customizations: SHA-256 hash comparison detects modifications
• Safety: Backup before migration, rollback on failure
• Preservation: All customizations preserved during migration
• Interactive: Prompts for confirmation (can skip in CI/CD)

Example Migration:

Before (flat):
  .claude/skills/
    ├── gemini-vision/
    ├── postgresql-psql/
    └── cloudflare-dns/

After (categorized):
  .claude/skills/
    ├── ai-multimodal/
    │   └── gemini-vision/
    ├── databases/
    │   └── postgresql-psql/
    └── devops/
        └── cloudflare-dns/

Customizations in any skill are detected and preserved automatically.

Development

See Development Guide for:

• Project structure (modular domain-driven architecture)
• Build & compilation (bun run build, bun run compile)
• Testing & type checking
• Code standards & linting

Architecture Highlights:

• Modular design: 122 focused modules (target: <100 lines each)
• Facade pattern: Each domain exposes public API via facade
• Phase handlers: Complex commands use orchestrator + phase handlers
• Self-documenting names: kebab-case file names describe purpose

Quick Start:

bun install
bun run dev new --kit engineer
bun test

FAQ

Q: Do I need GitHub CLI? A: Yes, GitHub CLI is required. ClaudeSkill uses it exclusively for authentication with private repositories.

Q: How do I authenticate? A: Run gh auth login, select 'Login with a web browser', complete OAuth in browser. Do NOT use 'Paste an authentication token'.

Q: "Access denied" error? A: Accept GitHub repo invitation, re-run gh auth login with web browser login, wait 2-5min for permissions.

Q: "GitHub CLI not authenticated" error? A: Run gh auth login and select 'Login with a web browser' (NOT 'Paste token'). PAT authentication is no longer supported.

Q: Is my token secure? A: Yes. GitHub CLI manages tokens securely via OAuth, stored encrypted in OS keychain.

License

MIT