Menú
Guide for modifying the Synapse plugin, updating skill documentation, and releasing new plugin versions.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
Work on Synapse pre-experiment research: project context, research questions, literature search, related works, and deep research reports.
Write and update Synapse documents, reports, synthesis, and Markdown figures. Use when embedding charts, plots, images, or report visuals in Synapse documents.
Plan, revise, execute, and report Synapse experiments, including compute access and result submission.
Understand the Synapse Claude Code plugin hooks, session lifecycle, and multi-agent parallel execution. Covers what each hook does, where plugin state lives, and how to run multiple experiments in parallel via Task sub-agents.
Synapse platform overview and router skill. Use it to orient on projects and then hand off to the stage-specific Synapse skills.
Drive the Claude Code-client autonomous research loop — analyze project state, propose the next experiment, dispatch sub-agents to execute it, and iterate.
| name | plugin-maintenance |
| description | Guide for modifying the Synapse plugin, updating skill documentation, and releasing new plugin versions. |
| license | AGPL-3.0 |
| metadata | {"author":"synapse","version":"0.1.0","category":"development"} |
How to modify the Synapse plugin, update skill documentation, and release new versions.
.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
| 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) |
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
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".
src/mcp/tools/*.ts (pm.ts, public.ts, etc.)docs/MCP_TOOLS.md00-common-tools.md + standalone 00-common-tools.md + both SKILL.md shared tools tables02-pm-workflow.md tool list + standalone equivalentnpx tsc --noEmit to verifyHook 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 hookCRITICAL: 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:
/bin/bash public/synapse-plugin/bin/test-syntax.sh on macOS to verify Bash 3.2 compatibilityclaude --plugin-dir public/synapse-plugin/plugin update to get 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