# Publish Command

> Run the `synapse-plugin-helper:publish` workflow from the original Claude slash command. Use when the user asks to publish Synapse plugin to the platform

- Skill: `datamaker-kr/publish-command` (Agent Skill)
- Install (CLI): `npx skillmds@latest add datamaker-kr/publish-command`
- Raw SKILL.md: https://api.skillmd.com/api/skills/datamaker-kr/publish-command/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: datamaker-kr (https://skillmd.com/u/datamaker-kr)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/datamaker-kr/publish-command

---


<!-- Generated by tools/generate-agent-marketplaces.py; edit the source command or agent-plugin.yaml instead. -->

# synapse-plugin-helper:publish Command Workflow

## Codex Adaptation

- Treat the user request or explicitly supplied text as the command arguments.
- Use the available Codex file, search, terminal, and clarification capabilities that match the workflow.
- Do not depend on Claude-only slash command variables or tool names.

# Publish Synapse Plugin

Publish the plugin to the Synapse platform for deployment.

**Arguments:** the user request or explicit arguments

## Pre-Publish Requirements

### Prerequisites Check

```bash
# Check synapse CLI
synapse --version 2>/dev/null || echo "ERROR: synapse-sdk not installed"

# Check authentication (login required)
synapse doctor 2>/dev/null || echo "WARNING: Not authenticated"
```

If synapse-sdk not installed:
```
synapse-sdk가 설치되어 있지 않습니다.
설치: uv pip install synapse-sdk (또는 pip install synapse-sdk)
```

### Checklist

Before publishing, ensure:
1. ✓ `config.yaml` is complete and valid
2. ✓ All actions are tested with `/synapse-plugin:test`
3. ✓ Dry run passes with `/synapse-plugin:dry-run`
4. ✓ Synapse CLI is authenticated (`synapse login`)

## Workflow

### Step 1: Pre-Publish Validation

Run a dry-run first:

```
synapse plugin publish --dry-run
```

This syncs config from code (`synapse plugin update-config` equivalent) and previews the upload.

### Step 2: Confirm Publishing

Display plugin information and ask for confirmation:

```
╔══════════════════════════════════════════════════╗
║              PUBLISH CONFIRMATION                ║
╠══════════════════════════════════════════════════╣
║ Plugin: [name]                                   ║
║ Version: [version]                               ║
║ Code: [code]                                     ║
║ Category: [category]                             ║
║                                                  ║
║ Actions to be published:                         ║
║   - train (job)                                  ║
║   - inference (task)                             ║
║   - serve (serve)                                ║
╠══════════════════════════════════════════════════╣
║ Proceed with publishing? [y/N]                   ║
╚══════════════════════════════════════════════════╝
```

### Step 3: Execute Publish

Run the Synapse CLI publish command:

```bash
synapse plugin publish
```

### Step 4: Monitor Progress

Display publishing progress:

```
[1/4] Validating configuration...     ✓
[2/4] Packaging plugin...             ✓
[3/4] Uploading to Synapse...         ✓
[4/4] Registering plugin...           ✓

✓ Plugin published successfully!
```

### Step 5: Post-Publish Information

After successful publishing:

```
╔══════════════════════════════════════════════════╗
║           PUBLISHING COMPLETE                    ║
╠══════════════════════════════════════════════════╣
║ Plugin ID: [plugin-id]                           ║
║ Version: [version]                               ║
║                                                  ║
║ Your plugin is now available at:                 ║
║ https://synapse.datamaker.kr/plugins/[code]     ║
║                                                  ║
║ Next steps:                                      ║
║ - Test in Synapse UI                             ║
║ - Monitor usage metrics                          ║
║ - Update with 'synapse plugin publish' again     ║
╚══════════════════════════════════════════════════╝
```

## Critical: Publish Scans the Entire Directory Tree

Before uploading, `synapse plugin publish` runs the same config sync as `synapse plugin update-config`. That sync calls `PluginDiscovery.discover_actions()`, which does `plugin_dir.rglob('*.py')` over the **whole project root** and imports every `BaseAction` subclass it finds — then **rewrites `config.yaml` in place** ("Synced types from code"). It only skips `__pycache__`, `test_*.py`, and `conftest.py`. It does **not** honor `.synapseignore` or `.gitignore`.

This means any action classes living under the project root get pulled into your `config.yaml`, overwriting your real entrypoints:
- `refs/`, `examples/`, or vendored sample plugins → their `train`/`convert`/`download`/`to_task` actions get added with foreign entrypoints like `refs.yolo.plugin.train.TrainAction`.
- A local `.venv/` → the SDK's own sample actions get pulled in (e.g. `.venv.lib.python3.x.site-packages.synapse_sdk.plugins.testing.sample_actions.*`, `DefaultExportAction`).

The result is a polluted `config.yaml` and a release that references modules that don't exist at runtime. The archive (`.synapseignore`) may look clean while the synced **config** is wrong — check the "Actions:" line in the publish output; if it lists actions you didn't define, the sync was poisoned.

**Reliable fix — publish from a clean staging copy via `--path`** so the rglob only sees real plugin files:

```bash
rm -rf /tmp/<code>-publish && mkdir -p /tmp/<code>-publish
cp -r plugin config.yaml README.md requirements.txt pyproject.toml .synapseignore /tmp/<code>-publish/
rm -rf /tmp/<code>-publish/plugin/__pycache__
synapse plugin publish --path /tmp/<code>-publish --host <host> --token <token> -y
```

Moving `refs/` out of the tree is *not* enough on its own when a `.venv/` also lives inside the project — the staging copy is the robust approach.

Also exclude large artifacts from the archive. Model checkpoints or zips (e.g. `whisper-large-v3.zip`, multi-GB weights) left in the project root get archived and uploaded, hanging the publish. Add them to `.synapseignore` — and note the pattern must match the file: `*.zip` matches `model.zip`, but a bare `whisper-large-v3` does **not** match `whisper-large-v3.zip`.

## Options

| Option | Description |
|--------|-------------|
| `--dry-run` | Preview without uploading (still runs config sync, which rewrites config.yaml) |
| `--debug` | Debug mode: bypasses backend validation, and lets you **re-publish an existing version** without bumping it |
| `--yes` | Skip confirmation prompt |
| `--path` | Plugin directory (default: current) — use a clean staging copy to avoid config-sync pollution |
| `--config` | Config file path (config.yaml or synapse.yaml) |
| `--host` / `--token` | Target backend + access token; pass explicitly to avoid relying on (or clobbering) saved `~/.synapse/config.json` |

## Error Handling

**Authentication required:**
```
✗ Not authenticated with Synapse
  Run: synapse login
```

**Version conflict:**
```
✗ Version 1.0.0 already exists
  Options:
  1. Update version in config.yaml
```

**Network error:**
```
✗ Connection failed
  Check network and retry
```

## Updating Published Plugins

To update an already published plugin:
1. Increment version in `config.yaml` (or `synapse.yaml`)
2. Run `/synapse-plugin:dry-run` to validate
3. Run `/synapse-plugin:publish`