KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #typescript #codex #cli #claude-code #mcp #rust #deepseek-harness #ai-agent

craftdesk

★ 65 Open GitHub ↗

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

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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](https://img.shields.io/npm/v/craftdesk.svg)](https://www.npmjs.com/package/craftdesk)
[![CI](https://github.com/mensfeld/craftdesk/actions/workflows/ci.yml/badge.svg)](https://github.com/mensfeld/craftdesk/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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, plugins, and collections** from git repositories or registries
- **Collections** - Curate and share groups of related crafts that work together
- **Plugin system** - Bundle multiple crafts with automatic dependency resolution
- **Multi-agent sync** - Share skills across multiple AI assistants (Claude, Cursor, Windsurf, etc.)
- **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

```bash
npm install -g craftdesk
```

Verify installation:
```bash
craftdesk --version
# x.y.z
```

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

### 1. Initialize a New Project

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

This creates a `craftdesk.json` file:
```json
{
  "name": "my-ai-project",
  "version": "1.0.0",
  "type": "skill",
  "dependencies": {}
}
```

### 2. Add Dependencies

```bash
# 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

```bash
craftdesk install
```

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

### 4. View Installed Crafts

```bash
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

- [What is CraftDesk?](#what-is-craftdesk)
- [Quick Start](#quick-start)
- [Core Concepts](#core-concepts)
  - [Crafts](#crafts)
  - [Collections](#collections)
- [Plugin System](#plugin-system)
- [Command Reference](#command-reference)
  - [init](#craftdesk-init-options)
  - [install](#craftdesk-install-options)
  - [add](#craftdesk-add-craft-options)
  - [remove](#craftdesk-remove-craft)
  - [list](#craftdesk-list-options)
  - [search](#craftdesk-search-query-options)
  - [info](#craftdesk-info-craft)
  - [outdated](#craftdesk-outdated)
  - [update](#craftdesk-update-craft)
  - [publish](#craftdesk-publish-options)
- [Embedded/Local Skills](#embeddedlocal-skills)
  - [embed](#craftdesk-embed-name-options)
  - [unembed](#craftdesk-unembed-name-options)
- [Authentication](#authentication)
  - [login](#craftdesk-login-options)
  - [logout](#craftdesk-logout-options)
  - [whoami](#craftdesk-whoami-options)
- [Dependency Sources](#dependency-sources)
- [Monorepo Support](#monorepo-support)
- [craftdesk.json Reference](#craftdeskjson-reference)
- [craftdesk.lock](#craftdesklock)
- [CI/CD Integration](#cicd-integration)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [Documentation](#documentation)

---

## 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
- **Collection** - Curated group of related crafts that work together (e.g., rails-enterprise-stack)

### Format Conversion

**Convert CraftDesk crafts to other AI editor formats** for cross-platform use.

**Supported Formats:**
- **Cursor** - Modern `.mdc` format in `.cursor/rules/` directory
- **Cursor Legacy** - Plain text `.cursorrules` format
- **Continue.dev** - Prompt and rule files in `.continue/prompts/` and `.continue/rules/`

**Why convert formats?**
- **Use any AI editor** - Write once, deploy to Cursor, Continue, Windsurf, etc.
- **Team flexibility** - Developers can use their preferred editors
- **Maximum reach** - Distribute crafts to wider audience
- **No lock-in** - Not tied to single platform

**Basic Usage:**

```bash
# Convert a craft to Cursor format
craftdesk convert ./my-craft --to cursor

# Convert to Continue.dev format
craftdesk convert ./my-craft --to continue

# Convert to legacy .cursorrules
craftdesk convert ./my-craft --to cursor-legacy

# Convert all installed crafts
craftdesk convert --all --to cursor --output .cursor/rules

# List available formats
craftdesk convert --list-formats
```

**Example: Rails Skill → Cursor**

Your `SKILL.md`:
```markdown
---
name: ruby-on-rails
description: Ruby on Rails development
---

## Instructions
Expert knowledge of Rails framework...

## Best Practices
- Use Strong Parameters
- Follow RESTful conventions
```

Converted to `.cursor/rules/ruby-on-rails.mdc`:
```markdown
---
description: Ruby on Rails development
globs:
  - "**/*.rb"
  - "**/*.erb"
  - "**/*.haml"
alwaysApply: true
---

# Ruby On Rails

## Overview
Expert knowledge of Rails framework...

## Best Practices
- Use Strong Parameters
- Follow RESTful conventions
```

**Advanced Options:**

```bash
# Merge modes
craftdesk convert --to cursor --merge-mode skip      # Skip existing files
craftdesk convert --to cursor --merge-mode append    # Append to existing
craftdesk convert --to cursor --merge-mode overwrite # Overwrite (default)

# Custom output directory
craftdesk convert --to cursor --output /custom/path

# Convert specific craft type
craftdesk convert .claude/skills/ruby-rails --to continue
```

**What Gets Converted:**

| Section | Cursor | Continue |
|---------|--------|----------|
| Instructions | ✓ Overview | ✓ Context |
| Code Patterns | ✓ Code Patterns | ✓ Patterns to Follow |
| Examples | ✓ Examples | ✓ Examples |
| Best Practices | ✓ Best Practices | ✓ Best Practices |
| Pitfalls | ✓ Mistakes to Avoid | ✓ Mistakes to Avoid |
| Workflows | ✓ Common Workflows | ✓ Step-by-Step Workflows |

**Language-Specific Features:**

Cursor converter automatically infers file globs based on content:
- **Ruby/Rails** → `**/*.rb`, `**/*.erb`, config files
- **TypeScript** → `**/*.ts`, `**/*.tsx`
- **Python** → `**/*.py`
- **JavaScript** → `**/*.js`, `**/*.jsx`
- **And more...** (Go, Rust, PHP, Java, etc.)

Continue converter generates:
- **Prompts** (invokable with `/`) - for manual use
- **Rules** (automatic) - applied to all matching files

**CI/CD Integration:**

```yaml
# .github/workflows/convert-crafts.yml
name: Convert Crafts to Multiple Formats
on: [push]
jobs:
  convert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install CraftDesk
        run: npm install -g craftdesk
      - name: Convert to Cursor
        run: craftdesk convert --all --to cursor --output dist/cursor
      - name: Convert to Continue
        run: craftdesk convert --all --to continue --output dist/continue
      - name: Upload artifacts
        uses: actions/upload-artifact@v2
        with:
          name: converted-crafts
          path: dist/
```

**Tips:**

1. **Test conversions** - Always verify converted files work in target editor
2. **Preserve originals** - Keep SKILL.md as source of truth
3. **Update together** - Convert after each craft update
4. **Version control** - Commit both source and converted formats

### Multi-Agent Sync

**Share skills across multiple AI coding assistants** - Sync your crafts to Claude Code, Cursor, Windsurf, Continue.dev, and more with automatic copy management and drift detection.

**Why use multi-agent sync?**
- **Single source of truth** - Maintain skills in one location (`.claude/skills/`)
- **Cross-editor compatibility** - Use the same skills in Claude, Cursor, Windsurf, etc.
- **Team flexibility** - Developers can use their preferred AI assistant
- **Automatic sync** - Install once, sync everywhere
- **Drift detection** - SHA-256 checksums detect modifications
- **Windows compatible** - Copy-based (no symlinks required)

**Quick Start:**

```bash
# 1. Interactive setup (recommended)
craftdesk setup-multi-agent

# 2. Detect available AI assistants
craftdesk detect-agents

# 3. Sync all crafts to configured agents
craftdesk sync

# 4. Verify sync status (check for drift)
craftdesk verify
```

**Configuration:**

Add to your `craftdesk.json`:

```json
{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": {
    "ruby-expert": "^1.0.0"
  },
  "multiAgent": {
    "enabled": true,
    "canonical": ".claude",
    "targets": [
      ".claude/skills",
      ".cursor/skills",
      ".windsurf/skills"
    ],
    "autoSync": true
  }
}
```

**How it works:**

1. **Canonical Location** - Skills are installed to `.claude/skills/` (source of truth)
2. **Target Directories** - Copies are created in `.cursor/skills/`, `.windsurf/skills/`, etc.
3. **Checksum Tracking** - Each copy has a `.craftdesk-checksum` file (SHA-256)
4. **Drift Detection** - `craftdesk verify` compares checksums to detect modifications
5. **Re-sync** - `craftdesk sync` updates all copies from canonical

**Example Workflow:**

```bash
# Install a new skill
craftdesk add git+https://github.com/user/ruby-expert.git

# Skills auto-sync to all agents (if autoSync: true)
# ✓ Installed to .claude/skills/ruby-expert
# ✓ Synced to .cursor/skills/ruby-expert
# ✓ Synced to .windsurf/skills/ruby-expert

# Verify everything is in sync
craftdesk verify
# ✅ All 3 craft(s) are in sync!

# Later, check for drift
craftdesk verify
# ⚠️  ruby-expert
#   Out of sync: .cursor/skills/ruby-expert (modified)

# Re-sync to fix drift
craftdesk sync --craft ruby-expert
# ✅ Synced ruby-expert to 3 location(s)
```

**Supported AI Assistants:**

| Assistant | Directory | Auto-Detected |
|-----------|-----------|---------------|
| **Claude Code** | `.claude/skills/` | ✅ Always enabled (canonical) |
| **Cursor** | `.cursor/skills/` | ✅ Yes |
| **Windsurf** | `.windsurf/skills/` | ✅ Yes |
| **Continue.dev** | `.continue/skills/` | ✅ Yes |
| **Generic .agents** | `.agents/skills/` | ✅ Yes |

**Commands:**

```bash
# Setup wizard (interactive)
craftdesk setup-multi-agent

# Detect AI assistants in project
craftdesk detect-agents
craftdesk detect-agents --verbose
craftdesk detect-agents --format json

# Sync all crafts to all targets
craftdesk sync
craftdesk sync --craft ruby-expert       # Sync specific craft
craftdesk sync --dry-run                 # Preview changes
craftdesk sync --force                   # Force re-sync

# Verify sync status
craftdesk verify
craftdesk verify --craft ruby-expert     # Verify specific craft
craftdesk verify --verbose               # Show checksums
craftdesk verify --format json           # JSON output
```

**Best Practices:**

1. **Use canonical as source of truth** - Always edit skills in `.claude/skills/`
2. **Enable autoSync** - New installs automatically sync to all agents
3. **Run verify regularly** - Check for drift, especially in teams
4. **Sync after manual edits** - If you edit a skill, run `craftdesk sync`
5. **Commit canonical only** - Add target directories to `.gitignore`

**gitignore Example:**

```gitignore
# Only track canonical location
.cursor/skills/*
.windsurf/skills/*
.continue/skills/*

# Track canonical
!.claude/skills/
```

**Why copy instead of symlinks?**

We use copy-based sync instead of symlinks for maximum compatibility:
- ✅ **Windows compatible** - No admin privileges or Developer Mode required
- ✅ **Git-friendly** - No `core.symlinks` complications
- ✅ **Reliable** - Works consistently across all platforms
- ✅ **Simple** - Easy to understand and debug
- ✅ **Verifiable** - Checksums detect any modifications

---

### Embedded/Local Skills

**Commit project-specific skills to your repository** alongside managed dependencies for a hybrid approach to skill management.

**What are embedded skills?**

Embedded skills are local, project-specific AI capabilities that are:
- ✅ **Committed to git** - Part of your repository, versioned with your code
- ✅ **Project-specific** - Custom skills unique to your project
- ✅ **Team-shared** - Distributed via `git clone` (not `craftdesk install`)
- ✅ **Auto-synced** - Sync to other AI assistants with multi-agent support
- ⚠️ **Not managed** - No version updates via `craftdesk update`

**When to embed vs. manage:**

| Use Case | Embedded | Managed (dependencies) |
|----------|----------|------------------------|
| Project-specific business logic | ✅ | ❌ |
| Custom team workflows | ✅ | ❌ |
| Proprietary domain knowledge | ✅ | ❌ |
| Shared/reusable skills | ❌ | ✅ |
| Skills that need updates | ❌ | ✅ |
| Skills from registry/git repos | ❌ | ✅ |

**Quick Start:**

```bash
# 1. Create a local skill manually
mkdir -p .claude/skills/my-project-skill
cat > .claude/skills/my-project-skill/SKILL.md <<EOF
---
skill: my-project-skill
version: 1.0.0
---
# My Project Skill

Project-specific knowledge about our custom architecture...
EOF

# 2. Register it as embedded
craftdesk embed my-project-skill

# 3. Commit to git
git add .claude/skills/my-project-skill craftdesk.json
git commit -m "Add my-project-skill as embedded skill"

# Team members get it via git clone (not craftdesk install!)
```

**Configuration:**

Your `craftdesk.json` tracks embedded skills separately from dependencies:

```json
{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": {
    "ruby-expert": "^1.0.0",    // Managed, from registry
    "postgres-expert": "^2.0.0"  // Managed, from git
  },
  "embedded": [
    "my-project-skill",           // Embedded, committed to git
    "team-coding-standards"       // Embedded, team-specific
  ]
}
```

**How .gitignore works:**

CraftDesk automatically generates `.claude/skills/.gitignore` to:
- ✅ **Ignore managed skills** - Not committed (installed via `craftdesk install`)
- ✅ **Allow embedded skills** - Committed with your code
- ✅ **Track orphans** - Skills not in either list (commented warnings)

Example generated `.gitignore`:

```gitignore
# Auto-generated by CraftDesk - DO NOT EDIT
# This file is managed automatically based on craftdesk.json and craftdesk.lock

# Managed dependencies (from craftdesk.lock)
# These are installed via `craftdesk install` and should not be committed
postgres-expert/
ruby-expert/

# Embedded/local skills (committed to git)
# These are project-specific and should be committed
# NOT ignored: my-project-skill/
# NOT ignored: team-coding-standards/

# Untracked (not in craftdesk.json or craftdesk.lock)
# Add these to dependencies or embedded list, or delete them
# orphaned-old-skill/
```

**Commands:**

#### `craftdesk embed <name> [options]`

**Options:**
- `--type <type>` - Craft type: skill, agent, command, hook (default: skill)
- `--skip-sync` - Skip multi-agent sync after embedding

**Examples:**

```bash
# Embed a skill
craftdesk embed my-local-skill

# Embed an agent
craftdesk embed my-automation-agent --type agent

# Embed without syncing to other agents
craftdesk embed team-workflow --skip-sync
```

**What happens:**
1. ✅ Adds skill to `craftdesk.json` `embedded` array
2. ✅ Updates `.claude/skills/.gitignore` to allow the skill
3. ✅ Syncs to other AI assistants (if multi-agent enabled)

**Requirements:**
- Skill directory must exist (`.claude/skills/my-local-skill/`)
- Cannot embed a managed dependency (remove from `dependencies` first)
- Cannot embed the same skill twice

---

#### `craftdesk unembed <name> [options]`

Unregister an embedded skill (no longer committed).

**Options:**
- `--remove` - Also delete the skill files from disk

**Examples:**

```bash
# Unembed a skill (files remain on disk)
craftdesk unembed my-local-skill

# Unembed and delete files
craftdesk unembed old-skill --remove
```

**What happens:**
1. ✅ Removes skill from `craftdesk.json` `embedded` array
2. ✅ Updates `.claude/skills/.gitignore` (skill becomes orphaned)
3. ⚠️ Skill files remain unless `--remove` is used

**After unembedding:**
- Skill becomes "orphaned" (commented in `.gitignore`)
- Manually delete files or re-embed it
- Or add it to `dependencies` to manage it

---

**Workflow Examples:**

**1. Create and embed a new skill:**

```bash
# Create skill directory and file
mkdir -p .claude/skills/deployment-guide
cat > .claude/skills/deployment-guide/SKILL.md <<'EOF'
---
skill: deployment-guide
version: 1.0.0
---
# Deployment Guide

Our custom deployment process...
EOF

# Embed it
craftdesk embed deployment-guide

# Commit
git add .claude/skills/deployment-guide craftdesk.json
git commit -m "Add deployment-guide skill"
```

**2. Convert managed skill to embedded:**

```bash
# You have: ruby-expert@1.0.0 (from registry)
# You want: Modify it and commit to your repo

# 1. Remove from dependencies
craftdesk remove ruby-expert

# 2. Skill files are now orphaned (but still on disk)

# 3. Embed it
craftdesk embed ruby-expert

# 4. Commit your customized version
git add .claude/skills/ruby-expert craftdesk.json
git commit -m "Embed ruby-expert with custom modifications"
```

**3. List and identify embedded skills:**

```bash
craftdesk list

# Output shows embedded badge:
# 📚 Skills:
#   ruby-expert@1.0.0
#   postgres-expert@2.0.0
#   my-project-skill@1.0.0 📌 (embedded)
#   team-workflow@1.0.0 📌 (embedded)
```

**4. Team collaboration:**

```bash
# Developer A: Creates and embeds skill
craftdesk embed new-feature-guide
git add .claude/skills/new-feature-guide craftdesk.json .claude/skills/.gitignore
git commit -m "Add new-feature-guide"
git push

# Developer B: Pulls and gets skill automatically
git pull
# ✅ Skill is ready to use (no craftdesk install needed!)

# Multi-agent sync works too (if enabled)
craftdesk verify
# ✅ new-feature-guide synced to .cursor/skills/
# ✅ new-feature-guide synced to .windsurf/skills/
```

**Best Practices:**

1. **Use embedded for project-specific knowledge** - Custom workflows, business logic, proprietary info
2. **Use managed for reusable skills** - Generic skills that can be shared across projects
3. **Always commit .gitignore** - CraftDesk auto-generates it, keep it in git
4. **Document embedded skills** - Add README explaining their purpose
5. **Version embedded skills** - Update version in skill frontmatter when modified
6. **Verify multi-agent sync** - Run `craftdesk verify` after embedding

---

### Collections

**Collections** are crafts that group related capabilities together. Instead of installing 6 individual crafts, install one collection that includes all of them.

**Why use collections?**
- **Faster onboarding** - One command installs complete workflows
- **Curated quality** - Experts bundle best-of-breed tools
- **Consistent stacks** - Teams share identical setups
- **Versioned together** - Dependencies tested to work together

**Example: Rails Enterprise Stack**

Create a collection in `craftdesk.json`:
```json
{
  "name": "rails-enterprise-stack",
  "version": "1.0.0",
  "type": "collection",
  "description": "Complete Rails enterprise development setup",
  "dependencies": {
    "ruby-on-rails": "^7.0.0",
    "rspec-testing": "^3.12.0",
    "rubocop-linter": "^1.50.0",
    "sidekiq-background-jobs": "^7.0.0",
    "postgresql-expert": "^15.0.0",
    "devise-auth": "^4.9.0"
  }
}
```

**Installing a collection:**
```bash
craftdesk add git+https://github.com/company/rails-enterprise-stack.git
```

**What happens:**
1. CraftDesk reads the collection's `craftdesk.json`
2. Recursively resolves all 6 dependencies
3. Installs the collection + all dependencies
4. Creates lockfile tracking everything

**Result:** 7 crafts installed (collection + 6 dependencies)

**How collections work:**

Collections leverage CraftDesk's **recursive dependency resolution**. When you install a craft with dependencies, CraftDesk:
1. Clones the repository
2. Reads `craftdesk.json`
3. Adds all dependencies to the resolution queue
4. Recursively resolves transitive dependencies
5. Installs everything with a single lockfile

This means **any craft with dependencies acts as a collection** - the `type: "collection"` field just improves discoverability in the registry.

**Nested collections:**

Collections can depend on other collections:
```json
{
  "name": "full-stack-rails",
  "type": "collection",
  "dependencies": {
    "rails-enterprise-stack": "^1.0.0",  // Another collection!
    "frontend-tooling": "^2.1.0",        // Another collection!
    "docker-deployment": "^1.5.0"
  }
}
```

CraftDesk handles arbitrary nesting depth with circular dependency detection.

### Manifest File: craftdesk.json

Declares your project's dependencies:
```json
{
  "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):
```json
{
  "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

```bash
# 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:

```json
{
  "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**:

```bash
$ 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:

```bash
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:

```bash
$ 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:

```bash
$ 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:
```bash
craftdesk remove john/rspec-testing --force
```

### Settings Integration

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

```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](./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, plugin, or collection (default: "skill")
- `-d, --description <desc>` - Project description
- `-a, --author <author>` - Author name
- `-l, --license <license>` - License (default: "MIT")

**Examples:**
```bash
# 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:**
```bash
# 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, collection)

**Examples:**

```bash
# 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:**
```bash
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:**
```bash
# 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, collection)

**Examples:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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

---

### `craftdesk setup-multi-agent [options]`

Interactive wizard to configure multi-agent sync.

**Options:**
- `--auto-sync` - Enable automatic sync on install/update
- `--skip-sync` - Skip initial sync after setup

**Examples:**
```bash
# Interactive setup (recommended)
craftdesk setup-multi-agent

# Setup with auto-sync enabled
craftdesk setup-multi-agent --auto-sync

# Setup without initial sync
craftdesk setup-multi-agent --skip-sync
```

**What it does:**
1. Detects AI coding assistants in your project
2. Lets you choose which agents to sync to
3. Updates `craftdesk.json` with multiAgent configuration
4. Optionally performs initial sync of existing crafts

---

### `craftdesk detect-agents [options]`

Detect AI coding assistants installed in the project.

**Options:**
- `-v, --verbose` - Show detailed detection information
- `-f, --format <format>` - Output format: text or json (default: text)

**Examples:**
```bash
# Detect agents
craftdesk detect-agents

# Verbose output
craftdesk detect-agents --verbose

# JSON output for scripting
craftdesk detect-agents --format json
```

**Example output:**
```
🔍 AI Coding Assistant Detection

Detected Agents:
  ✓ Claude Code
    Directory: .claude/skills
    Status: ✅ Enabled

○ Cursor
    Directory: .cursor/skills
    Status: ⚪ Available

Summary:
  Detected: 2 agent(s)
  Enabled: 1 agent(s)

💡 Tip:
  You have multiple agents but sync is only enabled for one.
  Run `craftdesk setup-multi-agent` to sync across all agents.
```

---

### `craftdesk sync [options]`

Sync crafts to all configured AI agents.

**Options:**
- `-c, --craft <name>` - Sync specific craft by name
- `-f, --force` - Force sync even if checksums match
- `--dry-run` - Show what would be synced without making changes

**Examples:**
```bash
# Sync all crafts
craftdesk sync

# Sync specific craft
craftdesk sync --craft ruby-expert

# Dry run (preview changes)
craftdesk sync --dry-run

# Force sync
craftdesk sync --force
```

**What it does:**
1. Reads multiAgent configuration from craftdesk.json
2. Copies crafts from canonical location to all targets
3. Calculates and stores SHA-256 checksums
4. Reports sync status for each location

**Example output:**
```
✅ Synced 5 craft(s)

✓ ruby-expert: 3 location(s)
✓ python-expert: 3 location(s)
✓ postgres-expert: 3 location(s)
✓ docker-expert: 3 location(s)
✓ git-expert: 3 location(s)

Summary:
  Total synced: 15 location(s)
```

---

### `craftdesk verify [options]`

Verify sync status of crafts across AI agents using checksum validation.

**Options:**
- `-c, --craft <name>` - Verify specific craft by name
- `-v, --verbose` - Show detailed checksum information
- `-f, --format <format>` - Output format: text or json (default: text)

**Examples:**
```bash
# Verify all crafts
craftdesk verify

# Verify specific craft
craftdesk verify --craft ruby-expert

# Verbose output with checksums
craftdesk verify --verbose

# JSON output
craftdesk verify --format json
```

**What it does:**
1. Reads multiAgent configuration
2. Calculates SHA-256 checksums for all copies
3. Compares checksums to detect drift
4. Reports which copies are in sync vs. out of sync

**Example output (in sync):**
```
🔍 Sync Status: All Crafts

Summary:
  Total crafts: 5
  In sync: 5
  Out of sync: 0

✅ All 5 craft(s) are in sync!
```

**Example output (drift detected):**
```
🔍 Sync Status: All Crafts

Summary:
  Total crafts: 5
  In sync: 4
  Out of sync: 1

❌ Out of Sync (1):

ruby-expert
    ⚠️  .cursor/skills/ruby-expert (modified)

💡 Run `craftdesk sync` to fix all issues
```

---

## 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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`:

```bash
# 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:**
```bash
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:

```bash
# 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:**

```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:

```bash
# 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:

```json
{
  "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:

```bash
# 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:

```json
{
  "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

CraftDesk has **full support for monorepo workflows**, allowing you to install crafts from subdirectories within a repository. This is perfect for teams maintaining multiple related crafts in one repository.

### Quick Start: Auto-Converting GitHub URLs

The easiest way to install from monorepos is to **paste GitHub web URLs directly**:

```bash
# Subdirectory from monorepo - just paste the GitHub URL!
craftdesk add https://github.com/company/monorepo/tree/main/skills/auth

# Single file from monorepo
craftdesk add https://github.com/company/monorepo/blob/main/skills/auth/SKILL.md

# Works with any branch or tag
craftdesk add https://github.com/company/monorepo/tree/v2.0.0/packages/deployer
```

CraftDesk automatically converts these to the correct git syntax and extracts only the specified subdirectory or file.

### Git URL Syntax

For more control, use explicit git URL syntax with path or file specifiers:

```bash
# Subdirectory with branch
craftdesk add git+https://github.com/company/monorepo.git#main#path:skills/auth

# Subdirectory with tag
craftdesk add git+https://github.com/company/monorepo.git#v2.0.0#path:packages/deployer

# Subdirectory with commit hash
craftdesk add git+https://github.com/company/monorepo.git#abc123def#path:skills/auth

# Single file with branch
craftdesk add git+https://github.com/company/monorepo.git#main#file:skills/auth/SKILL.md

# Just path (uses default branch)
craftdesk add git+https://github.com/company/monorepo.git#path:skills/auth
```

**Syntax breakdown:**
- `#main` - Branch name
- `#v2.0.0` - Git tag
- `#abc123def` - Commit hash (full 40-char)
- `#path:skills/auth` - Subdirectory to extract
- `#file:skill.md` - Single file to extract

### Using in craftdesk.json

Multiple crafts from the same monorepo:

```json
{
  "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"
    },
    "deploy-script": {
      "git": "https://github.com/company/ai-crafts-monorepo.git",
      "tag": "v3.2.0",
      "file": "scripts/deploy.md"
    }
  }
}
```

**Each craft can:**
- Use different subdirectories (`path`)
- Reference single files (`file`)
- Use the same or different tags/branches
- Be versioned independently or together

### Benefits

✅ **Single repository** for multiple related crafts
✅ **Version together** using git tags (or independently with branches)
✅ **Efficient cloning** - repository is cloned once and reused
✅ **Clear organization** - keep related crafts together
✅ **Atomic updates** - update all crafts by changing the tag
✅ **Works with private repos** - standard git authentication

### Monorepo Structure Example

```
ai-crafts-monorepo/
├── skills/
│   ├── auth/
│   │   ├── craftdesk.json
│   │   └── SKILL.md
│   ├── database/
│   │   ├── craftdesk.json
│   │   └── SKILL.md
│   └── reporting/
│       ├── craftdesk.json
│       └── SKILL.md
├── agents/
│   ├── code-reviewer/
│   │   ├── craftdesk.json
│   │   └── AGENT.md
│   └── test-runner/
│       ├── craftdesk.json
│       └── AGENT.md
├── commands/
│   └── deploy/
│       ├── craftdesk.json
│       └── COMMAND.md
└── scripts/
    ├── setup.md
    └── deploy.md
```

### Lockfile Tracking

CraftDesk lockfile tracks the exact subdirectory and commit:

```json
{
  "crafts": {
    "auth-handler": {
      "git": "https://github.com/company/monorepo.git",
      "tag": "v3.2.0",
      "commit": "abc123def456...",
      "path": "skills/auth",
      "type": "skill",
      "version": "3.2.0"
    }
  }
}
```

This ensures **reproducible installations** - the exact subdirectory from the exact commit is always installed.

### Real-World Example

```bash
# Install from technicalpickles' monorepo
craftdesk add https://github.com/technicalpickles/pickled-claude-plugins/tree/main/plugins/working-in-monorepos/skills/working-in-monorepos
```

This installs only the `working-in-monorepos` skill from the deeply nested monorepo structure.

---

## craftdesk.json Reference

Complete specification of the craftdesk.json format:

```json
{
  // 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, collection |
| `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?

```json
{
  "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

```yaml
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

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

### Docker

```dockerfile
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:

```bash
craftdesk --debug install
```

### Getting Help

```bash
# General help
craftdesk --help

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

---

## Development

### Building from Source

```bash
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

```bash
npm test
```

### Publishing

CraftDesk uses automated NPM publishing via GitHub Actions with provenance attestation.

**Quick release:**
```bash
./scripts/release.sh patch   # x.y.z → x.y.(z+1)
./scripts/release.sh minor   # x.y.z → x.(y+1).0
./scripts/release.sh major   # x.y.z → (x+1).0.0
```

The script will:
1. Bump version in package.json
2. Prompt you to update CHANGELOG.md
3. Commit and push changes
4. Create GitHub release
5. GitHub Actions automatically publishes to NPM with provenance

**Manual process:**
```bash
npm version patch
git add package.json CHANGELOG.md
git commit -m "Bump to 0.3.1"
git push
gh release create v0.3.1 --title "v0.3.1" --generate-notes
```

See [NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md) for complete setup instructions.

---

## Documentation

### Core Documentation
- **[README.md](./README.md)** - This file, general overview and quick start
- **[DEPENDENCY_MANAGEMENT.md](./DEPENDENCY_MANAGEMENT.md)** - Complete guide to dependency management
- **[PLUGIN_IMPLEMENTATION_COMPLETE.md](./PLUGIN_IMPLEMENTATION_COMPLETE.md)** - Plugin system implementation details

### Additional Resources
- **[Package.json](./package.json)** - Project metadata and scripts
- **[TypeScript Source](./src/)** - Full source code

---

## License

MIT

---

## Links

- **Repository**: [https://github.com/mensfeld/craftdesk](https://github.com/mensfeld/craftdesk)
- **Issues**: [https://github.com/mensfeld/craftdesk/issues](https://github.com/mensfeld/craftdesk/issues)
- **Registry**: Self-hosted registry server available at [CraftDesk Web](../web)

---

## 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

craftdesk

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README