CraftDesk CLI

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

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

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
• Lock versions for reproducible environments across teams
• Manage dependencies with automatic transitive resolution
• Support monorepos with subdirectory extraction
• Auto-convert GitHub URLs - paste any GitHub URL (tree/blob)
• Direct file references - install single files from repositories

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.2.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:

[email protected]

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

Total: 2 crafts installed

Table of Contents

• What is CraftDesk?
• Quick Start
• Core Concepts
• Command Reference
• Dependency Sources
• Monorepo Support
• craftdesk.json Reference
• craftdesk.lock
• CI/CD Integration
• Troubleshooting
• Development

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 - Extended functionality or tool integration (e.g., mcp-server, custom-tools)

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!

Install Directory

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

.claude/
├── skills/
│   ├── ruby-on-rails/
│   └── postgres-expert/
├── agents/
│   └── code-reviewer/
├── commands/
│   └── deploy/
└── hooks/
    └── pre-commit/

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:

[email protected]

Installed crafts:
  • my-skill@main (skill)
  • [email protected] (agent)
  • postgres-expert@main (skill)

Total: 3 crafts installed

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 currently supports Git dependencies. Registry support is under development.

1. GitHub URLs (Easiest)

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

2. 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)

3. Registry Dependencies (Coming Soon)

Note: Registry support is currently under development. A self-hosted registry server will be available soon.

Future registry format:

{
  "dependencies": {
    "ruby-on-rails": "^7.0.0",
    "@company/internal-skill": "^2.0.0"
  }
}

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 <[email protected]>",
  "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

License

MIT

Links

• Repository: https://github.com/mensfeld/craftdesk
• Issues: https://github.com/mensfeld/craftdesk/issues
• Registry (Coming Soon): Self-hosted registry server under development

Roadmap

• ✅ Git dependency support
• ✅ GitHub URL auto-conversion
• ✅ Direct file references
• ✅ Monorepo support
• ✅ Lockfile-based version control
• 🚧 Self-hosted registry server (in development)
• 🚧 Private registry authentication
• 🚧 Dependency conflict resolution
• 🚧 Semantic versioning for registry packages

Made for the AI development community