Vincentwei1021 Synapse Plugin & Skill Maintenance
How to modify the Synapse plugin, update skill documentation, and release new versions.
File Structure
.claude-plugin/
marketplace.json ← Marketplace registry (version here)
public/synapse-plugin/ ← The plugin package
.claude-plugin/
plugin.json ← Plugin metadata (version here)
hooks.json ← Hook definitions (SubagentStart, etc.)
bin/ ← Hook scripts (bash)
skills/synapse/
SKILL.md ← Main skill file (execution rules, lifecycle)
references/
00-common-tools.md ← Public MCP tools shared by all roles
01-setup.md ← MCP configuration guide
02-pm-workflow.md ← PM Agent complete workflow
03-developer-workflow.md ← Developer Agent complete workflow
04-admin-workflow.md ← Admin Agent complete workflow
05-session-sub-agent.md ← Session & observability guide
06-claude-code-agent-teams.md ← Agent Teams integration
public/skill/ ← Standalone skill (non-CC agents)
SKILL.md ← Same structure, softer language
references/ ← Same files, IDE-agnostic wording
When to Update What
| Change | Files to update |
|---|---|
| New MCP tool added | src/mcp/tools/*.ts (implementation) + docs/MCP_TOOLS.md + plugin 00-common-tools.md or 02-pm-workflow.md + standalone equivalents |
| MCP tool description changed | src/mcp/tools/*.ts only (skill docs reference tool names, not descriptions) |
| New workflow step | Plugin 02-pm-workflow.md (or 03/04) + standalone equivalent |
| New Idea/Task status | Plugin SKILL.md lifecycle diagram + standalone SKILL.md + messages/en.json + messages/zh.json |
| New execution rule | Plugin SKILL.md execution rules + standalone SKILL.md (softer wording) |
| Hook script change | public/synapse-plugin/bin/*.sh + hooks.json if new hook |
| Any plugin change | Bump version in BOTH files (see below) |
Version Bump Checklist
Every time the plugin content changes, bump the version in both files:
public/synapse-plugin/.claude-plugin/plugin.json—"version": "X.Y.Z".claude-plugin/marketplace.json—"version": "X.Y.Z"
Both must match. Users update via:
/plugin update synapse@synapse-plugins
Plugin vs Standalone Skill: Tone Differences
The plugin skill targets Claude Code specifically. The standalone skill targets any MCP-compatible agent (Cursor, Kiro, etc.).
| Aspect | Plugin (public/synapse-plugin/skills/) |
Standalone (public/skill/) |
|---|---|---|
| AskUserQuestion | "ALWAYS use... NEVER display as text" | "prefer your IDE's interactive prompt if available" |
| Session management | "Do NOT create sessions — plugin handles it" | "Create or reopen a session before starting work" |
| Skip elaboration | "you MUST ask the user for permission first" | "confirm with the user first" |
| Hook references | References specific hooks (SubagentStart, etc.) | No hook references |
Rule of thumb: Plugin version uses MUST/NEVER/ALWAYS. Standalone version uses "prefer", "confirm", "consider".
Adding a New MCP Tool — Full Checklist
- Implement in
src/mcp/tools/*.ts(pm.ts, public.ts, etc.) - Add to
docs/MCP_TOOLS.md - If public tool: add to plugin
00-common-tools.md+ standalone00-common-tools.md+ bothSKILL.mdshared tools tables - If PM tool: add to plugin
02-pm-workflow.mdtool list + standalone equivalent - If it changes the workflow: update the relevant workflow steps
- Bump plugin version
- Run
npx tsc --noEmitto verify
Modifying Hook Scripts
Hook scripts are in public/synapse-plugin/bin/:
on-session-start.sh— SessionStart hookon-user-prompt.sh— UserPromptSubmit hookon-subagent-start.sh— SubagentStart hookon-subagent-stop.sh— SubagentStop hookon-teammate-idle.sh— TeammateIdle hook
CRITICAL: All hook scripts MUST be compatible with Bash 3.2. macOS ships with /bin/bash 3.2 (due to GPL licensing) and Claude Code uses it to execute hooks. Do NOT use Bash 4+ features:
| Bash 4+ (FORBIDDEN) | Bash 3.2 alternative |
|---|---|
${VAR,,} (lowercase) |
$(printf '%s' "$VAR" | tr '[:upper:]' '[:lower:]') |
${VAR^^} (uppercase) |
$(printf '%s' "$VAR" | tr '[:lower:]' '[:upper:]') |
declare -A (associative arrays) |
Use separate variables or jq |
readarray / mapfile |
while IFS= read -r line loop |
|& (pipe stderr) |
2>&1 | |
&>> (append both) |
>> file 2>&1 |
After modifying:
- Run
/bin/bash public/synapse-plugin/bin/test-syntax.shon macOS to verify Bash 3.2 compatibility - Test locally:
claude --plugin-dir public/synapse-plugin - Bump plugin version
- Users must restart CC and run
/plugin updateto get changes
Testing Plugin Changes
# Load plugin locally (no install needed)
claude --plugin-dir public/synapse-plugin
# Or update installed plugin
/plugin update synapse@synapse-plugins
# Verify plugin loaded
/plugin list