claudeck: Skill for Claude Code

Create a new Claudeck Plugin

You are scaffolding a new tab-sdk plugin called "$ARGUMENTS".

Parse the arguments: the first word is the plugin name (kebab-case), the rest is the description of what the plugin should do.

Plugin Locations

Claudeck supports two plugin directories:

Default: Create user plugins in ~/.claudeck/plugins/<name>/ unless the user explicitly asks for a built-in plugin. User plugins are the recommended approach since they persist across npm upgrades and don't require modifying the Claudeck source code.

To resolve the user plugins directory, use ~/.claudeck/plugins/ (or $CLAUDECK_HOME/plugins/ if the env var is set).

Rules

1. The plugin name MUST be kebab-case (e.g. my-plugin, code-metrics)
2. All files go in the chosen plugin directory — NO other files need to be modified (no main.js, no style.css, no index.html)
3. The plugin is auto-discovered by the server at runtime via GET /api/plugins
4. Create at minimum: client.js and optionally client.css
5. If the plugin needs server-side API routes, also create server.js (for user plugins, requires CLAUDECK_USER_SERVER_PLUGINS=true in ~/.claudeck/.env)
6. If the plugin needs persistent config, also create config.json (auto-copied to ~/.claudeck/config/ on first run)

Client JS file template

Create client.js in the plugin directory following this structure:

// <Title> — Tab SDK plugin
// <Description of what the plugin does>
import { registerTab } from '/js/ui/tab-sdk.js';

registerTab({
  id: '<name>',
  title: '<Title>',
  icon: '<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">...</svg>',
  lazy: true,

  init(ctx) {
    // ── Build DOM ──
    const root = document.createElement('div');
    root.className = '<name>-tab';
    root.style.cssText = 'display:flex;flex-direction:column;flex:1;overflow:hidden;';

    // Build the UI innerHTML here...

    // ── Context API (ctx) ──
    // ctx.pluginId                      — Plugin's ID string
    // ctx.getProjectPath()              — Current project path
    // ctx.getSessionId()                — Current session ID
    // ctx.getTheme()                    — Current theme: 'dark' or 'light'
    // ctx.on('projectChanged', fn)      — Fires when user switches project (returns unsub fn)
    // ctx.on('ws:message', fn)          — Live WebSocket stream messages (returns unsub fn)
    // ctx.onState('sessionId', fn)      — Session switch (returns unsub fn)
    // ctx.off(event, fn)                — Remove an event listener
    // ctx.api                           — Full API module for fetch calls
    // ctx.storage.get(key)              — Read from plugin-scoped localStorage
    // ctx.storage.set(key, value)       — Write to plugin-scoped localStorage
    // ctx.storage.remove(key)           — Remove from plugin-scoped localStorage
    // ctx.toast(msg, opts)              — Show notification ({duration, type: 'info'|'success'|'error'})
    // ctx.showBadge(count)              — Show badge on tab button
    // ctx.clearBadge()                  — Hide badge
    // ctx.setTitle(text)                — Update tab button label
    // ctx.dispose()                     — Unsubscribe all listeners (auto-called on destroy)

    // ── Project-scoped data ──
    // If your plugin loads data scoped to a project, follow this pattern:
    //
    //   function loadData() {
    //     const project = ctx.getProjectPath();
    //     if (!project) return;
    //     fetch(`/api/plugins/<name>/?project=${encodeURIComponent(project)}`)
    //       .then(r => r.json()).then(data => { /* render */ });
    //   }
    //   ctx.on('projectChanged', loadData);  // reload on project switch
    //   loadData();                           // initial load
    //
    // IMPORTANT: ALWAYS use ctx.getProjectPath() to read the project path.
    //   NEVER use document.getElementById('project-select') directly.
    // IMPORTANT: ALWAYS use ctx.on('projectChanged', fn) to react to project changes.
    //   NEVER add your own change listener to the project select element.

    return root;  // must return an HTMLElement
  },

  // onActivate(ctx)   { /* tab became visible — ctx is passed */ },
  // onDeactivate(ctx) { /* tab was hidden — ctx is passed */ },
  // onDestroy(ctx)    { /* cleanup — ctx is passed; all subscriptions auto-disposed */ },
});