Package manager for Claude Code skills, agents, commands, hooks, and plugins
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.
CraftDesk is a package manager for AI capabilities used in Claude Code and other AI development environments. It allows you to:
.claude/settings.jsonThink of it as:
Note: A self-hosted registry server is currently under development and will be available soon, enabling private registries and centralized craft distribution.
npm install -g craftdesk
Verify installation:
craftdesk --version
# x.y.z
Requirements: Node.js >= 18.0.0, Git, npm or yarn
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": {}
}
# 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
craftdesk install
This installs all dependencies to .claude/ directory and creates craftdesk.lock.
craftdesk list
Output:
my-ai-project@1.0.0
Installed crafts:
• my-skill@main (skill)
• custom-agent@main (agent)
Total: 2 crafts installed
A craft is any AI capability:
Convert CraftDesk crafts to other AI editor formats for cross-platform use.
Supported Formats:
.mdc format in .cursor/rules/ directory.cursorrules format.continue/prompts/ and .continue/rules/Why convert formats?
Basic Usage:
# 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:
---
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:
---
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:
# 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:
**/*.rb, **/*.erb, config files**/*.ts, **/*.tsx**/*.py**/*.js, **/*.jsxContinue converter generates:
/) - for manual useCI/CD Integration:
# .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:
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?
.claude/skills/)Quick Start:
# 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:
{
"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:
.claude/skills/ (source of truth).cursor/skills/, .windsurf/skills/, etc..craftdesk-checksum file (SHA-256)craftdesk verify compares checksums to detect modificationscraftdesk sync updates all copies from canonicalExample Workflow:
# 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:
# 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:
.claude/skills/craftdesk sync.gitignoregitignore Example:
# 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:
core.symlinks complicationsCommit 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:
git clone (not craftdesk install)craftdesk updateWhen 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:
# 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:
{
"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:
craftdesk install)Example generated .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]Register a skill as embedded (committed to git).
Options:
--type <type> - Craft type: skill, agent, command, hook (default: skill)--skip-sync - Skip multi-agent sync after embeddingExamples:
# 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:
craftdesk.json embedded array.claude/skills/.gitignore to allow the skillRequirements:
.claude/skills/my-local-skill/)dependencies first)craftdesk unembed <name> [options]Unregister an embedded skill (no longer committed).
Options:
--remove - Also delete the skill files from diskExamples:
# Unembed a skill (files remain on disk)
craftdesk unembed my-local-skill
# Unembed and delete files
craftdesk unembed old-skill --remove
What happens:
craftdesk.json embedded array.claude/skills/.gitignore (skill becomes orphaned)--remove is usedAfter unembedding:
.gitignore)dependencies to manage itWorkflow Examples:
1. Create and embed a new skill:
# 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:
# 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:
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:
# 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:
craftdesk verify after embeddingCollections are crafts that group related capabilities together. Instead of installing 6 individual crafts, install one collection that includes all of them.
Why use collections?
Example: Rails Enterprise Stack
Create a collection in craftdesk.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:
craftdesk add git+https://github.com/company/rails-enterprise-stack.git
What happens:
craftdesk.jsonResult: 7 crafts installed (collection + 6 dependencies)
How collections work:
Collections leverage CraftDesk's recursive dependency resolution. When you install a craft with dependencies, CraftDesk:
craftdesk.jsonThis 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:
{
"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.
Declares your project's dependencies:
{
"name": "my-project",
"version": "1.0.0",
"dependencies": {
"my-skill": {
"git": "https://github.com/user/skill.git",
"branch": "main"
}
}
}
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!
CraftDesk automatically verifies the integrity of downloaded packages:
craftdesk.lockWhat 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.
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
New in v0.3.0: CraftDesk now supports a comprehensive plugin system for bundling multiple crafts with automatic dependency management.
Plugins allow you to:
# 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!
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"]
}
}
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:
.claude/settings.jsonConvert any skill, agent, command, or hook into a plugin:
craftdesk add my-skill --as-plugin
What happens:
.claude/skills/my-skill/.claude/plugins/my-skill-plugin/plugin.json and PLUGIN.md auto-generatedUse cases:
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
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
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
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:
# 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 devDependenciesExamples:
# 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:
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:
# 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 JSONExamples:
# 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:
# 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 outdatedCheck 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:
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:
craftdesk login)craftdesk.json in current directoryWhat it does:
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 setupExamples:
# 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:
craftdesk.json with multiAgent configurationcraftdesk 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:
# 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 changesExamples:
# 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:
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:
# 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:
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
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:
~/.craftdesk/config.jsonGetting an API 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
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.
Available for all commands:
-v, --version - Output the version number-d, --debug - Enable debug output-h, --help - Display helpExamples:
craftdesk --version
craftdesk --help
craftdesk init --help
CraftDesk supports both registry and git dependencies.
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"
}
}
}
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
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 tagcommit - Specific commit hashpath - Subdirectory within repo (for monorepos)file - Direct file path (for single-file crafts)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.
The easiest way to install from monorepos is to paste GitHub web URLs directly:
# 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.
For more control, use explicit git URL syntax with path or file specifiers:
# 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 extractMultiple crafts from the same monorepo:
{
"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:
path)file)✅ 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
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
CraftDesk lockfile tracks the exact subdirectory and commit:
{
"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.
# 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.
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 | 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 |
The lockfile ensures reproducible installations across different machines and times.
{
"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": {}
}
}
}
✅ DO:
❌ DON'T:
--no-lockfile flagname: 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
deploy:
image: node:18
script:
- npm install -g craftdesk
- craftdesk install --production
- ./deploy.sh
only:
- main
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"]
No craftdesk.json foundMake sure you're in a directory with a craftdesk.json file, or run craftdesk init first.
Failed to resolve dependenciescraftdesk install --no-lockfile to re-resolveGit clone failedgit --versionPermission deniedsudo npm install -g craftdesknpx craftdesk installDependency conflictsCurrently uses last-write-wins. Future versions will have interactive conflict resolution.
Enable verbose logging:
craftdesk --debug install
# General help
craftdesk --help
# Command-specific help
craftdesk init --help
craftdesk add --help
craftdesk install --help
git clone https://github.com/mensfeld/craftdesk.git
cd craftdesk
npm install
npm run build
npm link
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
npm test
CraftDesk uses automated NPM publishing via GitHub Actions with provenance attestation.
Quick release:
./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:
Manual process:
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 for complete setup instructions.
MIT
craftdesk publish commandcraftdesk outdated commandcraftdesk update commandcraftdesk validate <plugin> commandMade for the AI development community
FAQs
Package manager for Claude Code skills, agents, commands, hooks, and plugins
The npm package craftdesk receives a total of 3 weekly downloads. As such, craftdesk popularity was classified as not popular.
We found that craftdesk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.