Skip to content

mensfeld/craftdesk

BranchesTags

Repository files navigation

CraftDesk CLI

Dependency management for AI capabilities - Install, manage, and version control your Claude Code skills, agents, commands, hooks, and plugins.

The command-line interface for managing your Coding AI capabilities. Similar to npm for JavaScript or bundler for Ruby, CraftDesk CLI provides a complete package management solution for AI-powered development tools.

npm version CI License: MIT

What is CraftDesk?

CraftDesk is a package manager for AI capabilities used in Claude Code and other AI development environments. It allows you to:

  • Install AI skills, agents, commands, hooks, and plugins from git repositories or registries
  • Plugin system - Bundle multiple crafts with automatic dependency resolution
  • Lock versions for reproducible environments across teams
  • Manage dependencies with automatic recursive installation
  • Support monorepos with subdirectory extraction
  • Auto-convert GitHub URLs - paste any GitHub URL (tree/blob)
  • Direct file references - install single files from repositories
  • Settings integration - Automatic registration in .claude/settings.json
  • MCP server support - Configure Model Context Protocol servers via plugins

Think of it as:

  • npm for Node.js → CraftDesk for AI capabilities
  • Bundler for Ruby → CraftDesk for Claude tools
  • Cargo for Rust → CraftDesk for AI agents

Note: A self-hosted registry server is currently under development and will be available soon, enabling private registries and centralized craft distribution.

Quick Start

Install CraftDesk

npm install -g craftdesk

Verify installation:

craftdesk --version
# 0.3.0

Requirements: Node.js >= 18.0.0, Git, npm or yarn

1. Initialize a New Project

mkdir my-ai-project
cd my-ai-project
craftdesk init

This creates a craftdesk.json file:

{
  "name": "my-ai-project",
  "version": "1.0.0",
  "type": "skill",
  "dependencies": {}
}

2. Add Dependencies

# Add a single skill file from GitHub (auto-converts web URLs)
craftdesk add https://github.com/aviflombaum/rspec-rails-agents/blob/main/rspec-dry-agent.md

# Add from git repository
craftdesk add git+https://github.com/aviflombaum/rspec-rails-agents.git

# Add from monorepo subdirectory
craftdesk add https://github.com/technicalpickles/pickled-claude-plugins/tree/main/plugins/working-in-monorepos/skills/working-in-monorepos

# Add with explicit type
craftdesk add https://github.com/aviflombaum/rspec-rails-agents/blob/main/rspec-dry-agent.md --type agent

3. Install Everything

craftdesk install

This installs all dependencies to .claude/ directory and creates craftdesk.lock.

4. View Installed Crafts

craftdesk list

Output:

my-ai-project@1.0.0

Installed crafts:
  • my-skill@main (skill)
  • custom-agent@main (agent)

Total: 2 crafts installed

Table of Contents

Core Concepts

Crafts

A craft is any AI capability:

  • Skill - Knowledge domain (e.g., ruby-on-rails, postgres-expert)
  • Agent - Autonomous task executor (e.g., code-reviewer, test-runner)
  • Command - Slash command (e.g., /deploy, /analyze)
  • Hook - Event handler (e.g., pre-commit, post-install)
  • Plugin - Bundle of multiple crafts with dependencies and MCP server configuration

Manifest File: craftdesk.json

Declares your project's dependencies:

{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": {
    "my-skill": {
      "git": "https://github.com/user/skill.git",
      "branch": "main"
    }
  }
}

Lockfile: craftdesk.lock

Records exact versions installed (like package-lock.json or Gemfile.lock):

{
  "version": "1.0.0",
  "lockfileVersion": 1,
  "crafts": {
    "my-skill": {
      "version": "main",
      "resolved": "https://github.com/user/skill.git",
      "integrity": "a1b2c3d4e5f6...",
      "type": "skill",
      "git": "https://github.com/user/skill.git",
      "branch": "main",
      "commit": "a1b2c3d4e5f6789012345678901234567890abcd"
    }
  }
}

Always commit this file to version control!

Security: Checksum Verification

CraftDesk automatically verifies the integrity of downloaded packages:

  • Registry packages: SHA-256 checksums are computed when you first add a craft and stored in craftdesk.lock
  • Subsequent installs: The downloaded file is verified against the stored checksum before extraction
  • MITM protection: Prevents tampering during download by detecting any modifications
  • Git packages: Git commit hashes serve as checksums - stored in the lockfile and verified during clone

What happens on checksum mismatch:

Error: Checksum verification failed for john/rails-api@2.1.0.
Expected: a1b2c3d4e5f6...
This may indicate a corrupted download or a security issue.
Try running 'craftdesk install --no-lockfile' to re-resolve dependencies.

The lockfile contains SHA-256 hashes that ensure reproducible and secure installations across all team members.

Install Directory

By default, crafts install to .claude/ in your project:

.claude/
├── settings.json           # Plugin configuration (auto-generated)
├── skills/
│   ├── ruby-on-rails/
│   └── postgres-expert/
├── agents/
│   └── code-reviewer/
├── commands/
│   └── deploy/
├── hooks/
│   └── pre-commit/
└── plugins/                # Flat plugin installation
    ├── company-rails-plugin/
    │   ├── plugin.json
    │   ├── PLUGIN.md
    │   └── skills/...
    └── my-skill-plugin/    # Wrapped skill

Plugin System

New in v0.3.0: CraftDesk now supports a comprehensive plugin system for bundling multiple crafts with automatic dependency management.

What are Plugins?

Plugins allow you to:

  • Bundle multiple crafts (skills, agents, commands, hooks) together
  • Declare dependencies that are automatically installed
  • Configure MCP servers (Model Context Protocol) for external tools
  • Share configurations and related files as a cohesive package
  • Wrap individual crafts as plugins for better organization

Installing Plugins

# Install a plugin from registry
craftdesk add company/rails-standards-plugin

# What happens automatically:
# 1. Plugin is installed to .claude/plugins/company-rails-standards-plugin/
# 2. Dependencies are resolved and auto-installed
# 3. Plugin is registered in .claude/settings.json
# 4. MCP server is configured (if provided)
# 5. Plugin tree is added to craftdesk.lock

Example Output:

Adding company/rails-standards-plugin...
Found company/rails-standards-plugin@2.1.0
Installing company/rails-standards-plugin...
Plugin detected - resolving dependencies...
Resolved 3 total dependencies
Installing plugin dependency: john/rspec-testing...
✓ Resolved john/rspec-testing@1.5.3
Installing plugin dependency: jane/postgres-toolkit...
✓ Resolved jane/postgres-toolkit@3.2.1
✓ Installed company/rails-standards-plugin@2.1.0
Craft added successfully!

Plugin Structure

A plugin contains a plugin.json manifest:

{
  "name": "company-rails-plugin",
  "version": "2.1.0",
  "type": "plugin",
  "description": "Rails development standards",
  "author": "company",
  "components": {
    "skills": ["coding-standards", "rails-best-practices"],
    "agents": ["standards-enforcer"],
    "commands": ["check-standards"]
  },
  "dependencies": {
    "john/rspec-testing": "^1.5.0",
    "jane/postgres-toolkit": "^3.2.0"
  },
  "mcp": {
    "type": "stdio",
    "command": "/usr/bin/rails-standards-mcp",
    "args": ["--config", ".claude/plugins/company-rails-plugin/config.json"]
  }
}

Automatic Dependency Resolution

When you install a plugin, all dependencies are automatically installed:

$ craftdesk add company/rails-plugin

# Installs dependency tree:
# company/rails-plugin (direct)
#   ├── john/rspec-testing (dependency)
#   └── jane/postgres-toolkit (dependency)
#     └── jane/sql-helpers (nested dependency)

All dependencies are:

  • ✅ Downloaded from their respective sources (registry/git)
  • ✅ Installed to appropriate directories
  • ✅ Verified with integrity checksums
  • ✅ Marked as dependencies in lockfile
  • ✅ Registered in .claude/settings.json

Wrapping Individual Crafts

Convert any skill, agent, command, or hook into a plugin:

craftdesk add my-skill --as-plugin

What happens:

  1. Original craft installed to .claude/skills/my-skill/
  2. Plugin wrapper created at .claude/plugins/my-skill-plugin/
  3. plugin.json and PLUGIN.md auto-generated
  4. Craft files copied to plugin structure
  5. Registered in settings as wrapped plugin

Use cases:

  • Add MCP server to existing skill
  • Bundle configuration with craft
  • Prepare for publishing to marketplace
  • Enable/disable craft from Claude Code UI

Plugin Tree Visualization

View your plugin dependency tree:

$ craftdesk list

my-project@1.0.0

🔌 Plugins:
  company/rails-standards@2.1.0
    ├── john/rspec-testing@1.5.3
    └── jane/postgres-toolkit@3.2.1
  my-skill-plugin@1.0.0

📚 Skills:
  standalone-skill@1.0.0

Total: 5 crafts installed

Removing Plugins with Dependencies

CraftDesk prevents accidental removal of required dependencies:

$ craftdesk remove john/rspec-testing

Warning: john/rspec-testing is required by:
  - company/rails-standards@2.1.0

Use --force to remove anyway

Force removal:

craftdesk remove john/rspec-testing --force

Settings Integration

Plugins are automatically registered in .claude/settings.json:

{
  "version": "1.0.0",
  "plugins": {
    "company-rails-plugin": {
      "name": "company-rails-plugin",
      "version": "2.1.0",
      "enabled": true,
      "installPath": "plugins/company-rails-plugin",
      "dependencies": ["john-rspec-testing", "jane-postgres-toolkit"],
      "mcp": {
        "type": "stdio",
        "command": "/usr/bin/rails-standards-mcp",
        "args": ["--config", ".claude/plugins/company-rails-plugin/config.json"]
      }
    }
  }
}

For complete details, see DEPENDENCY_MANAGEMENT.md

Command Reference

craftdesk init [options]

Initialize a new craftdesk.json file.

Options:

  • -y, --yes - Skip prompts and use defaults
  • -n, --name <name> - Project name (default: directory name)
  • -v, --version <version> - Project version (default: "1.0.0")
  • -t, --type <type> - Project type: skill, agent, command, hook, or plugin (default: "skill")
  • -d, --description <desc> - Project description
  • -a, --author <author> - Author name
  • -l, --license <license> - License (default: "MIT")

Examples:

# Interactive initialization
craftdesk init

# Quick init with defaults
craftdesk init -y

# Specify options
craftdesk init --name my-skill --type skill --author "Your Name"

craftdesk install [options]

Install all dependencies from craftdesk.json.

Options:

  • --no-lockfile - Ignore craftdesk.lock and re-resolve dependencies
  • --production - Skip devDependencies

Examples:

# Install all dependencies
craftdesk install

# Or use the alias
craftdesk i

# Production install (skip dev dependencies)
craftdesk install --production

# Force re-resolve (ignore lockfile)
craftdesk install --no-lockfile

What it does:

  1. Reads craftdesk.json
  2. Uses craftdesk.lock if present (ensures reproducibility)
  3. Resolves dependencies (registry + git sources)
  4. Installs to .claude/ directory
  5. Updates/creates craftdesk.lock

craftdesk add <craft> [options]

Add a new dependency and install it immediately.

Options:

  • -D, --save-dev - Save as devDependency
  • -O, --save-optional - Save as optionalDependency
  • -E, --save-exact - Save exact version (no ^ or ~)
  • -t, --type <type> - Specify craft type (skill, agent, command, hook, plugin)

Examples:

# GitHub web URLs (auto-converted)
craftdesk add https://github.com/user/repo/blob/main/skill.md
craftdesk add https://github.com/user/repo/tree/main/skills/auth

# With explicit type
craftdesk add https://github.com/user/repo/blob/main/agent.md --type agent

# Git dependencies (manual format)
craftdesk add git+https://github.com/user/repo.git
craftdesk add git+https://github.com/user/repo.git#develop
craftdesk add git+https://github.com/user/repo.git#v2.0.0

# Direct file reference
craftdesk add git+https://github.com/user/repo.git#main#file:skill.md

# Subdirectory (monorepo)
craftdesk add git+https://github.com/company/monorepo.git#main#path:skills/auth

craftdesk remove <craft>

Remove a dependency from craftdesk.json and the filesystem.

Examples:

craftdesk remove my-skill
craftdesk remove my-agent

craftdesk list [options]

List installed crafts.

Options:

  • --tree - Show dependency tree
  • --depth <n> - Limit tree depth
  • --json - Output as JSON

Examples:

# Simple list
craftdesk list

# Show dependency tree
craftdesk list --tree

# Limit tree depth
craftdesk list --tree --depth 2

# JSON output (for scripts)
craftdesk list --json

Example output:

my-project@1.0.0

Installed crafts:
  • my-skill@main (skill)
  • code-reviewer@v2.0.1 (agent)
  • postgres-expert@main (skill)

Total: 3 crafts installed

craftdesk search <query> [options]

Search for crafts in the registry.

Options:

  • -t, --type <type> - Filter by type (skill, agent, command, hook, plugin)

Examples:

# Search for crafts
craftdesk search kafka

# Search for skills only
craftdesk search rails --type skill

# Search for plugins
craftdesk search standards --type plugin

Example output:

Search results for "kafka":

  john/kafka-processing@2.1.0 (skill)
    Expert knowledge for processing Kafka messages

  jane/kafka-agent@1.5.3 (agent)
    Autonomous agent for Kafka stream management

Found 2 crafts

craftdesk info <craft>

Display detailed information about a craft from the registry.

Examples:

# Get info about a craft
craftdesk info john/rails-api

# Get info about a specific version
craftdesk info john/rails-api@2.1.0

Example output:

john/rails-api@2.1.0

  Description: Rails API development best practices
  Type:        skill
  Author:      john
  License:     MIT
  Downloads:   1,234

  Versions:
    2.1.0 (latest)
    2.0.0
    1.5.0

  Dependencies:
    jane/postgres-toolkit: ^1.0.0

craftdesk outdated

Check for outdated dependencies that have newer versions available.

Examples:

# Check all dependencies
craftdesk outdated

Example output:

Checking for outdated dependencies...

Outdated crafts:

  john/rails-api
    Current: 2.0.0
    Latest:  2.1.0
    Type:    skill

  jane/postgres-toolkit
    Current: 1.2.0
    Latest:  1.5.0
    Type:    skill

2 outdated crafts found
Run 'craftdesk update' to update all, or 'craftdesk update <craft>' to update specific crafts.

craftdesk update [craft]

Update dependencies to their latest compatible versions.

Examples:

# Update all outdated dependencies
craftdesk update

# Update a specific craft
craftdesk update john/rails-api

What it does:

  1. Checks for newer versions in the registry
  2. Downloads and installs updates
  3. Updates craftdesk.lock with new versions
  4. Verifies checksums for security

craftdesk publish [options]

Publish a craft to the registry.

Options:

  • --visibility <level> - Set visibility: public, private, or organization (default: public)

Examples:

# Publish the current craft
craftdesk publish

# Publish as private
craftdesk publish --visibility private

# Publish to organization only
craftdesk publish --visibility organization

Prerequisites:

  • Must be logged in (craftdesk login)
  • Must have a valid craftdesk.json in current directory
  • Craft files must exist (SKILL.md, AGENT.md, etc.)

What it does:

  1. Reads craftdesk.json for metadata
  2. Collects all craft files
  3. Creates a new version on the registry
  4. Publishes with specified visibility

Authentication

CraftDesk supports authenticated access to private registries.

craftdesk login [options]

Authenticate with a registry using an API token.

Options:

  • -r, --registry <url> - Registry URL (uses default from craftdesk.json if not specified)

Examples:

# Login to default registry
craftdesk login

# Login to a specific registry
craftdesk login --registry https://private.company.com

How it works:

  1. Prompts for your API token
  2. Verifies the token with the registry
  3. Stores credentials in ~/.craftdesk/config.json
  4. Token is used for subsequent registry operations

Getting an API token:

  • Log in to your CraftDesk registry web interface
  • Navigate to Settings → API Tokens
  • Generate a new token

craftdesk logout [options]

Remove stored authentication credentials.

Options:

  • -r, --registry <url> - Registry URL (uses default from craftdesk.json if not specified)

Examples:

# Logout from default registry
craftdesk logout

# Logout from specific registry
craftdesk logout --registry https://private.company.com

craftdesk whoami [options]

Display the currently logged-in user.

Options:

  • -r, --registry <url> - Registry URL (uses default from craftdesk.json if not specified)

Examples:

# Check current user
craftdesk whoami

# Check user for specific registry
craftdesk whoami --registry https://private.company.com

Example output:

Logged in to https://craftdesk.ai as john (john@example.com)
Organization: acme-corp

Environment Variable Authentication

For CI/CD environments, you can use environment variables instead of craftdesk login:

# For a registry named "company-private" in craftdesk.json
export CRAFTDESK_AUTH_COMPANY_PRIVATE=your_api_token_here

# For the default registry
export CRAFTDESK_AUTH_LOCALHOST_3000=your_api_token_here

# The variable name is derived from the registry URL:
# https://example.com -> CRAFTDESK_AUTH_EXAMPLE_COM

Environment variables take precedence over stored credentials.

Global Options

Available for all commands:

  • -v, --version - Output the version number
  • -d, --debug - Enable debug output
  • -h, --help - Display help

Examples:

craftdesk --version
craftdesk --help
craftdesk init --help

Dependency Sources

CraftDesk supports both registry and git dependencies.

1. Registry Dependencies (CraftDesk Web API)

Install crafts from the CraftDesk registry using author/name format:

# Search for crafts
craftdesk search kafka

# Get information about a craft
craftdesk info john/rails-api

# Add from registry
craftdesk add john/rails-api
craftdesk add john/rails-api@^2.1.0

# Add with specific version
craftdesk add jane/postgres-expert@1.2.0

Registry format in craftdesk.json:

{
  "dependencies": {
    "john/rails-api": "^2.1.0",
    "jane/kafka-processing": "~1.5.2",
    "team/postgres-admin": "latest"
  },
  "registries": {
    "default": {
      "url": "http://localhost:3000"
    }
  }
}

Important: You must configure your registry URL in craftdesk.json to use registry-based crafts. Git-based dependencies (GitHub URLs) work without any registry configuration.

Private Registry Authentication:

For private registries, set authentication tokens via environment variables:

# For a registry named "company-private" in craftdesk.json
export CRAFTDESK_AUTH_COMPANY_PRIVATE=your_token_here

# For default registry
export CRAFTDESK_AUTH_DEFAULT=your_token_here

Example craftdesk.json with private registry:

{
  "registries": {
    "default": {
      "url": "https://your-registry.com"
    },
    "company-private": {
      "url": "https://private.company.com",
      "scope": "@company"
    }
  }
}

2. GitHub URLs (Easiest for Git)

Simply paste any GitHub URL - it auto-converts to the correct format:

# Directory in monorepo
craftdesk add https://github.com/user/repo/tree/main/skills/auth

# Single file
craftdesk add https://github.com/user/repo/blob/main/agent.md

# Entire repository
craftdesk add https://github.com/user/repo

3. Git Dependencies

From git repositories:

{
  "dependencies": {
    "custom-agent": {
      "git": "https://github.com/user/agent-repo.git",
      "branch": "develop"
    },
    "stable-skill": {
      "git": "https://github.com/org/skills.git",
      "tag": "v2.1.0"
    },
    "specific-commit": {
      "git": "https://github.com/user/repo.git",
      "commit": "a1b2c3d4"
    }
  }
}

Git options:

  • git - Repository URL (required)
  • branch - Branch name (default: main/master)
  • tag - Git tag
  • commit - Specific commit hash
  • path - Subdirectory within repo (for monorepos)
  • file - Direct file path (for single-file crafts)

Monorepo Support

Install multiple crafts from the same git repository using subdirectory paths:

{
  "dependencies": {
    "auth-handler": {
      "git": "https://github.com/company/ai-crafts-monorepo.git",
      "tag": "v3.2.0",
      "path": "skills/auth"
    },
    "data-processor": {
      "git": "https://github.com/company/ai-crafts-monorepo.git",
      "tag": "v3.2.0",
      "path": "agents/processor"
    },
    "report-generator": {
      "git": "https://github.com/company/ai-crafts-monorepo.git",
      "tag": "v3.2.0",
      "path": "skills/reporting"
    }
  }
}

Benefits:

  • Single git repository for multiple crafts
  • Version them together with git tags
  • Each craft installs independently
  • Efficient cloning (repo cached during resolution)

Monorepo structure example:

ai-crafts-monorepo/
├── skills/
│   ├── auth/
│   │   ├── craftdesk.json
│   │   └── SKILL.md
│   └── reporting/
│       ├── craftdesk.json
│       └── SKILL.md
├── agents/
│   └── processor/
│       ├── craftdesk.json
│       └── AGENT.md
└── commands/
    └── deploy/
        ├── craftdesk.json
        └── COMMAND.md

craftdesk.json Reference

Complete specification of the craftdesk.json format:

{
  // Required fields
  "name": "my-project",
  "version": "1.0.0",

  // Optional metadata
  "type": "skill",
  "description": "My awesome AI project",
  "author": "Your Name <you@example.com>",
  "license": "MIT",
  "homepage": "https://example.com",
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo.git"
  },
  "keywords": ["ai", "claude", "automation"],

  // Dependencies
  "dependencies": {
    "my-skill": {
      "git": "https://github.com/user/repo.git",
      "branch": "main"
    },
    "auth-handler": {
      "git": "https://github.com/company/monorepo.git",
      "tag": "v3.2.0",
      "path": "skills/auth"
    },
    "my-agent": {
      "git": "https://github.com/user/agents.git",
      "branch": "main",
      "file": "agent.md"
    }
  },

  "devDependencies": {
    "test-runner": {
      "git": "https://github.com/org/test-tools.git",
      "branch": "main"
    }
  }
}

Field Descriptions

Field Type Required Description
name string Yes Craft name (lowercase, no spaces)
version string Yes Semantic version (e.g., "1.0.0")
type string No Craft type: skill, agent, command, hook, plugin
description string No Short description
author string No Author name and email
license string No License identifier (e.g., "MIT")
dependencies object No Production dependencies
devDependencies object No Development dependencies

craftdesk.lock

The lockfile ensures reproducible installations across different machines and times.

What's in the Lockfile?

{
  "version": "1.0.0",
  "lockfileVersion": 1,
  "generatedAt": "2025-11-18T10:30:00.000Z",
  "crafts": {
    "my-skill": {
      "version": "main",
      "resolved": "https://github.com/user/skill.git",
      "integrity": "a1b2c3d4e5f6789012345678901234567890abcd",
      "type": "skill",
      "author": "git",
      "git": "https://github.com/user/skill.git",
      "branch": "main",
      "commit": "a1b2c3d4e5f6789012345678901234567890abcd",
      "dependencies": {}
    },
    "custom-agent": {
      "version": "v2.0.0",
      "resolved": "https://github.com/user/agent.git",
      "integrity": "b2c3d4e5f6789012345678901234567890abcdef",
      "type": "agent",
      "git": "https://github.com/user/agent.git",
      "tag": "v2.0.0",
      "commit": "b2c3d4e5f6789012345678901234567890abcdef",
      "dependencies": {}
    }
  }
}

Best Practices

✅ DO:

  • Commit craftdesk.lock to version control
  • Let the CLI manage it (don't edit manually)
  • Use it for reproducible builds in CI/CD

❌ DON'T:

  • Ignore craftdesk.lock in .gitignore
  • Edit it manually
  • Delete it without --no-lockfile flag

CI/CD Integration

GitHub Actions

name: Deploy
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install CraftDesk CLI
        run: npm install -g craftdesk

      - name: Install AI capabilities
        run: craftdesk install --production

      - name: Deploy
        run: ./deploy.sh

GitLab CI

deploy:
  image: node:18
  script:
    - npm install -g craftdesk
    - craftdesk install --production
    - ./deploy.sh
  only:
    - main

Docker

FROM node:18

# Install CraftDesk CLI
RUN npm install -g craftdesk

# Copy project files
WORKDIR /app
COPY craftdesk.json craftdesk.lock ./

# Install AI capabilities
RUN craftdesk install --production

# Copy rest of application
COPY . .

CMD ["node", "app.js"]

Troubleshooting

Common Issues

No craftdesk.json found

Make sure you're in a directory with a craftdesk.json file, or run craftdesk init first.

Failed to resolve dependencies

  • Check internet connection
  • Verify git repository URLs are accessible
  • For private repos, ensure SSH keys or access tokens are configured
  • Try craftdesk install --no-lockfile to re-resolve

Git clone failed

  • Verify git is installed: git --version
  • Check git repository URL is accessible
  • For private repos, ensure SSH keys or tokens are configured

Permission denied

  • For global install: sudo npm install -g craftdesk
  • Or use npx: npx craftdesk install

Dependency conflicts

Currently uses last-write-wins. Future versions will have interactive conflict resolution.

Debug Mode

Enable verbose logging:

craftdesk --debug install

Getting Help

# General help
craftdesk --help

# Command-specific help
craftdesk init --help
craftdesk add --help
craftdesk install --help

Development

Building from Source

git clone https://github.com/mensfeld/craftdesk.git
cd craftdesk
npm install
npm run build
npm link

Project Structure

craftdesk/
├── src/
│   ├── commands/       # CLI commands
│   ├── services/       # Core services
│   ├── types/          # TypeScript types
│   └── utils/          # Utilities
├── dist/               # Compiled JavaScript
├── bin/                # Executable entry point
├── examples/           # Example craftdesk.json files
└── docs/               # Documentation

Running Tests

npm test

Publishing

npm version patch
npm publish

Documentation

Core Documentation

Additional Resources

License

MIT

Links

Roadmap

Completed (v0.3.0)

  • ✅ Git dependency support
  • ✅ GitHub URL auto-conversion
  • ✅ Direct file references
  • ✅ Monorepo support
  • ✅ Lockfile-based version control
  • ✅ Self-hosted registry server support
  • ✅ ZIP archive extraction for registry crafts
  • ✅ Plugin system with dependency management
  • ✅ Auto-install plugin dependencies (recursive)
  • ✅ Settings integration (.claude/settings.json)
  • ✅ MCP server configuration via plugins
  • ✅ Craft wrapping (--as-plugin flag)
  • ✅ Plugin tree visualization
  • ✅ Dependency removal protection
  • ✅ SHA-256 checksum verification (MITM protection)
  • ✅ Registry search and info commands
  • ✅ craftdesk publish command
  • ✅ craftdesk outdated command
  • ✅ craftdesk update command
  • ✅ Authentication system (login/logout/whoami)
  • ✅ Private registry authentication (token-based)
  • ✅ Environment variable auth (CI/CD support)
  • ✅ Semantic versioning for registry packages

Planned

  • 🔲 Plugin marketplace/directory
  • 🔲 craftdesk validate <plugin> command
  • 🔲 Multiple dependency versions support
  • 🔲 Peer dependency warnings
  • 🔲 Persistent download cache
  • 🔲 Offline installation mode
  • 🔲 Interactive dependency conflict resolution

Made for the AI development community

About

Package manager for Claude Code skills and agents and other AI related resources

craftdesk.ai/

Topics

javascript cli package-manager typescript skills developer-tools dependencies agents claude llm anthropic claude-code claude-skills

Resources

Readme
Activity

Stars

31 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

Languages