maestro-handoff

Read on-disk JSON envelopes to restore context between agents in maestro projects.

1|Updated May 26, 2026

Search Tags:#agent handoff #MCP tools #workflow resume #maestro #task claim #task block

Ready to run

npx skills add https://github.com/Leonardo-Corte/local-social-smm-agent --skill maestro-handoff

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: maestro-handoff
Source: https://github.com/Leonardo-Corte/local-social-smm-agent/tree/main/reference/github-agent-orchestration/maestro/skills/bundled/maestro-handoff
Command: npx skills add https://github.com/Leonardo-Corte/local-social-smm-agent --skill maestro-handoff

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill solves the problem of lost or stale context when switching between AI agents in a maestro project, so you can resume work with the right task state.

Core Features & Use Cases

Passive handoff via on-disk envelopes: Lifecycle verbs emit a JSON contract that the next agent can read directly.
Claim/block continuity checks: The receiver verifies whether a prior agent claimed or blocked a task and follows the referenced reason.
Optional targeted routing between tools: Use the envelope’s to_agent field (or intra-tool tool argument on claim/block) to keep continuity within the same tool.

Quick Start

Tell your AI to load maestro-handoff, then scan and pick the correct envelope for the task you are resuming.

Frequently Asked Questions about maestro-handoff

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I resume an AI agent workflow with context from a previous session?▼

To resume an AI agent workflow with prior context, you read handoff envelopes left on disk in the .maestro/handoffs directory. This passive discovery mechanism ensures the next agent picks up the exact task state and continuity left by the previous lifecycle event.

How does task claim and task block continuity work in multi-agent workflows?▼

Task claim and task block continuity works by using trigger_verb-aware handling to verify prior agent actions on a specific task_id. The receiving agent reads the JSON envelope to check whether the task was claimed or blocked and follows the referenced reason to resume correctly.

What is the best way to pass task state between different AI agents?▼

The best way to pass task state between agents is using on-disk JSON contracts emitted during lifecycle events. This passive handoff approach allows any subsequent agent to directly read the prior context and task state without requiring active inter-agent communication.

Can I route a handoff envelope to a specific AI tool to maintain continuity?▼

Yes, you can route a handoff envelope to a specific AI tool by using the optional to_agent field or the intra-tool tool argument during task claim or block events. This strict filtering ensures continuity remains within the same tool environment.

Do I need a maestro project to use on-disk handoff envelopes for agent context?▼

Yes, you need a maestro project structure because the Skill discovers envelopes passively within the .maestro/handoffs directory. It targets session start, task pickup, and debugging missed continuity specifically for tasks identified by a task_id in that environment.

Why does my agent miss prior context when picking up a blocked task?▼

An agent misses prior context when picking up a blocked task if the handoff envelope is stale or missing from the .maestro/handoffs directory. Debugging missed continuity requires locating the correct envelope by task_id to retrieve the referenced block reason.