克劳德技能包管理

2. Add Dependencies

```bash

Managed dependencies (from craftdesk.lock)

Add these to dependencies or embedded list, or delete them

1. Remove from dependencies

craftdesk remove ruby-expert

2. Dependencies are resolved and auto-installed

Automatic Dependency Resolution

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

```bash $ craftdesk add company/rails-plugin

Installs dependency tree:

├── 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

Removing Plugins with Dependencies

CraftDesk prevents accidental removal of required dependencies:

$ craftdesk remove john/rspec-testing

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

Use --force to remove anyway

Force removal:

craftdesk remove john/rspec-testing --force

Install all dependencies

craftdesk install

Production install (skip dev dependencies)

craftdesk install --production

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

Show dependency tree

craftdesk list --tree

Check all dependencies

craftdesk outdated

**Example output:**

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

---

Update all outdated dependencies

craftdesk update

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

3. Git Dependencies

From git repositories:

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

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

---

Install CraftDesk

npm install -g craftdesk

Verify installation: ```bash craftdesk --version

3. Install Everything

craftdesk install

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

4. View Installed Crafts

craftdesk list

Output:

my-ai-project@1.0.0

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

Total: 2 crafts installed

---

Convert all installed crafts

craftdesk convert --all --to cursor --output .cursor/rules

1. Interactive setup (recommended)

craftdesk setup-multi-agent

Install a new skill

craftdesk add git+https://github.com/user/ruby-expert.git

✓ Installed to .claude/skills/ruby-expert

Setup wizard (interactive)

craftdesk setup-multi-agent

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

**Configuration:**

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

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

These are installed via `craftdesk install` and should not be committed

postgres-expert/ ruby-expert/

cat > .claude/skills/deployment-guide/SKILL.md <<'EOF'

skill: deployment-guide

Deployment Guide

Our custom deployment process... EOF

✅ Skill is ready to use (no craftdesk install needed!)

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

---

Installing Plugins

```bash

Install a plugin from registry

craftdesk add company/rails-standards-plugin

1. Plugin is installed to .claude/plugins/company-rails-standards-plugin/

`craftdesk install [options]`

Install all dependencies from craftdesk.json.

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

Examples: ```bash

`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

---

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.

---

Docker

```dockerfile FROM node:18

Install CraftDesk CLI

RUN npm install -g craftdesk

Install AI capabilities

RUN craftdesk install --production

Building from Source

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

Quick Start

✅ 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

---

https://example.com -> CRAFTDESK_AUTH_EXAMPLE_COM

```

Environment variables take precedence over stored credentials.

---

Quick Start: Auto-Converting GitHub URLs

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

```bash

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

Real-World Example

```bash

3. Sync all crafts to configured agents

craftdesk sync

3. Plugin is registered in .claude/settings.json

4. MCP server is configured (if provided)

Settings Integration

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

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

For complete details, see DEPENDENCY_MANAGEMENT.md

---

`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

Specify options

craftdesk init --name my-skill --type skill --author "Your Name" ```

---

`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

`craftdesk list [options]`

List installed crafts.

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

Examples: ```bash

`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

`craftdesk publish [options]`

Publish a craft to the registry.

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

Examples: ```bash

`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

`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

`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

`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

`craftdesk logout [options]`

Remove stored authentication credentials.

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

Examples: ```bash

`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

Environment Variable Authentication

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

```bash

Global Options

Available for all commands:

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

Examples:

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

---

Command Reference

Direct file reference

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

craftdesk.json Reference

Complete specification of the craftdesk.json format:

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

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

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

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

.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

team-workflow@1.0.0 📌 (embedded)

**4. Team collaboration:**

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

5. Plugin tree is added to craftdesk.lock

**Example Output**:

Plugin Structure

A plugin contains a plugin.json manifest:

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

company/rails-plugin (direct)

Plugin Tree Visualization

View your plugin dependency tree:

$ craftdesk list

my-project@1.0.0

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

📚 Skills:
  standalone-skill@1.0.0

Total: 5 crafts installed

Search for plugins

craftdesk search standards --type plugin

**Example output:**

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

---

CI/CD Integration

Troubleshooting