| name | synapse |
| description | Synapse platform overview and router skill. Use it to orient on projects and then hand off to the stage-specific Synapse skills. |
| license | AGPL-3.0 |
| metadata | {"author":"Vincentwei1021","version":"0.6.1","category":"research","mcp_server":"synapse"} |
Synapse Skill
Synapse is a research orchestration platform for human researchers and AI agents. This top-level skill is the entry point: use it to understand the product model, check in, inspect project context, and then switch to the stage-specific skill whose prompt boundary best matches the current task.
Stage Skills
| Skill | When to use it |
|---|
| setup | Configure MCP, API keys, and project-level .mcp.json |
| research | Research questions, literature search, related works, deep research |
| experiments | Experiment planning, revision, execution, compute, and result submission |
| documents | Markdown documents, reports, charts, plots, and embedded images |
| autonomy | Autonomous loop and next-experiment proposal work |
| sessions | Plugin hooks, session lifecycle, and multi-agent parallel execution |
Core Workflow
ResearchProject --> ResearchQuestion --> Experiment --> Report
^ ^ ^ ^
Human Human/Agent Agent executes Agent writes
creates formulates and reports synthesis
Tool families are exposed according to the agent's Synapse roles. Public read/comment/notification/session tools are broadly available, while literature tools usually require pre_research, experiment / compute tools require experiment, and mutation-heavy research or admin surfaces depend on research, report, or admin.
Getting Started
Step 1: Setup and check in
Configure your MCP connection with setup, then call:
synapse_checkin()
Returns your agent identity, current assignments, and pending work.
Step 2: Handle active plugin context
The Synapse Claude Code plugin may inject active context during session start, user prompts, sub-agent starts, and task completion. Treat that context as work already assigned by Synapse: do not wait for the user to restate it.
When hook context mentions an active project, assignment, experiment, synthesis task, deep research task, notification, or sub-agent session:
- Call
synapse_checkin() to refresh identity, roles, assignments, and notifications.
- Use the UUIDs from the hook context with the matching
synapse_get_* tool.
- Continue through the matching stage skill below.
- Report durable progress with
synapse_report_experiment_progress or synapse_add_comment when work spans more than a quick read-only lookup.
- Finish Synapse-triggered task state with the task-specific completion tool, such as
synapse_submit_experiment_results, synapse_save_project_synthesis, or synapse_complete_task for task types that still require explicit completion.
Step 2b: Empty-project onboarding
If synapse_checkin() returns no assignments and no notifications and the user's current project has no related works, no research questions, and no experiments, do not silently pick a direction. Ask the user which path to start with:
- Literature-first — search papers with
synapse_search_papers, curate with synapse_add_related_work, then synthesize a deep research report via synapse_save_deep_research_report. Switch to research.
- Question-first — draft one or more
ResearchQuestion records with synapse_create_research_question to frame the project. Switch to research.
- Experiment-first — skip ahead and create the foundational experiment (data preparation + baseline + evaluation script) with
synapse_create_experiment. Switch to experiments.
- Autonomous — hand the project to the CC-client autonomous loop so the agent proposes and runs experiments on its own. Switch to autonomy.
Each stage skill repeats this onboarding prompt from its own perspective when entered with empty state.
Step 3: Choose the right stage skill
| Current work | Skill to use |
|---|
| Understanding project context and project state | Stay here, then call synapse_get_project_full_context() |
| Research questions, literature, deep research | research |
| Experiment drafting, revision, execution, compute, reporting | experiments |
| Autonomous next-step proposal, queue-empty behavior, driving the CC-client autonomous loop | autonomy |
| Plugin hook behavior, session tracking, multi-agent parallel dispatch in Claude Code | sessions |
Active Trigger Routing
| Trigger or hook context | First action | Then use |
|---|
| Experiment assignment or assigned experiment UUID | synapse_get_experiment({ experimentUuid }) | experiments to start, run, report progress, and submit results |
| Experiment plan requested | synapse_get_experiment() plus synapse_get_project_full_context() | experiments to update the plan |
| Experiment revision requested | synapse_get_experiment() and read relevant comments if needed | experiments to revise and resubmit/update |
| Experiment report requested | synapse_get_experiment() and inspect completed results | experiments to write the report/result document; use documents for charts and image embedding |
| Research question claimed | synapse_get_research_question() and synapse_get_project_full_context() | research |
| Deep research requested | synapse_get_project_full_context(), synapse_get_related_works(), then existing report via synapse_get_deep_research_report() | research; call synapse_complete_task({ taskType: "deep_research" }) when done |
| Auto search triggered | synapse_get_project_full_context() and inspect existing related works | research to search, add related works, and complete the task if required |
| Synthesis refresh requested | synapse_get_project_full_context(), synapse_get_documents({ type: "project_synthesis" }), then synapse_get_document() if one exists | Save only if new results need analysis; synapse_save_project_synthesis() clears the active synthesis task |
| Autonomous loop or empty queue | synapse_get_project_full_context() and synapse_list_compute_nodes({ researchProjectUuid }) | autonomy to drive the CC-client loop |
| @mention or comment notification | synapse_get_comments() for the target when available | Reply with synapse_add_comment() using the @[name](actorType:uuid) format |
| Sub-agent start/session context | Use the injected experiment UUID, then synapse_get_experiment() | sessions for hook behavior and experiments for work execution |
Minimum Tool Map
| Need | Tools |
|---|
| Identity, assignments, notifications | synapse_checkin, synapse_get_notifications, synapse_mark_notification_read |
| Project context | synapse_get_research_project, synapse_get_project_full_context |
| Documents and synthesis | synapse_get_documents, synapse_get_document, synapse_upload_document_image, synapse_save_project_synthesis |
| Literature and deep research | synapse_search_papers, synapse_add_related_work, synapse_get_related_works, synapse_get_deep_research_report |
| Research questions | synapse_get_research_question and research-question mutation tools when roles allow |
| Experiments | synapse_get_assigned_experiments, synapse_get_experiment, synapse_create_experiment, synapse_start_experiment, synapse_report_experiment_progress, synapse_submit_experiment_results, synapse_save_experiment_report, synapse_upload_document_image, synapse_propose_experiment (autonomous loop only) |
| PI/Admin review | synapse_review_experiment |
| Compute | synapse_list_compute_nodes, synapse_reserve_gpus, synapse_get_node_access_bundle |
| Collaboration | synapse_add_comment, synapse_get_comments, synapse_search_mentionables |
| Task cleanup | synapse_complete_task except where a task-specific save/submit tool already clears state |
Execution Rules
- Always check in first -- call
synapse_checkin() at session start.
- Respond to active Synapse context first -- when hooks or routed notifications identify a task, handle that task before unrelated work.
- Use UUIDs from context -- pass experiment, document, project, question, and notification UUIDs directly into the matching
synapse_get_* tool.
- Keep stage boundaries clean -- use the research skill for literature/question work, the experiments skill for execution work, and the autonomy skill only when driving the next step yourself.
- Report durable progress -- use
synapse_report_experiment_progress and synapse_add_comment to keep the team informed.
- Document decisions -- add comments explaining reasoning on experiments and research questions.
- Use compute correctly -- call
synapse_list_compute_nodes before execution decisions, get SSH access via synapse_get_node_access_bundle, and never assume local key paths.
- Use sessions intentionally -- sub-agent sessions are plugin-managed; direct agent sessions are optional.
Shared References
Status Lifecycles
Experiment Status Flow
draft --> pending_review --> pending_start --> in_progress --> completed
Research Question Status Flow
open --> elaborating --> proposal_created --> completed
\ /
\--> closed <------------------------------/
