Imported from Rlegaspi562/agent-handoff-skill (agent-handoff-setup/SKILL.md). Install upstream with npx skills add Rlegaspi562/agent-handoff-skill --skill agent-handoff-setup. Copyright stays with the author.

Agent Handoff Setup

This skill creates a file-based handoff for project context. Context can carry between sessions when agents read the latest synchronized files, then commit and push relevant updates before handing off. It does not create automatic model memory.

The system has three parts:

1. HQ (entry point) repository: Stores stable information about the user, machines, projects, and shared instructions. It is where any agent, on any platform, starts reading. Current project status stays elsewhere. Because this file can contain identifiers and local paths, make the HQ private by default.
2. STATE.md: Stores current work, next actions, decisions, and blockers in each project repository. Update it when project state changes.
3. Shared Git remote: Stores pushed commits. Agents need repository access, instructions to read the files, and a fetch or pull before relying on changes made elsewhere.

Use this skill for initial setup or later restructuring. The separate agent-handoff skill handles ongoing project sessions and should not repeat the setup interview.

Step 1: Interview

Ask conversationally and in batches instead of sending a long questionnaire:

1. Who are you? Preferred name or identifier, GitHub handle(s), and one line on what you do. Do not request an email address unless it is operationally necessary.
2. Machines. Which computers do you work from, and where do repos live on each? Agents need valid local paths, but collect only paths they need.
3. Projects. For each active project: name, GitHub repo, local path, one line on what it is, and whether the repository is public or private. Start with two to five active projects. Explain that a root STATE.md in a public repository is public, then confirm the user will keep its contents suitable for that audience before creating it.
4. Connections. Besides GitHub, what does an agent need to touch? (Issue tracker, local dashboard, database, deploy target.) For each: how to verify it works, where credentials live. Never ask for credential values.
5. HQ repo name. Suggest hq-entry-point so the repo's role is visible in its own name, and describe it as the "HQ entry point" in the generated files. Ask whether it should use an existing repository or a new one. If it is new, recommend a private remote.

If the user has already told you some of this in the conversation, don't re-ask it. Confirm inferred details and ask only for missing information.

Step 2: Scaffold

Templates live in templates/ next to this file. Fill them with the interview answers. Replace every <placeholder> and delete sections that do not apply.

Build the HQ repo:

hq-entry-point/
├── README.md          (what this repo is + the onboarding prompt, from PROMPT.template.md)
├── CONTEXT.md         (from CONTEXT.template.md; user, machines, registry)
├── AGENTS.md          (from AGENTS.template.md; shared instructions)
├── CONNECTIONS.md     (from CONNECTIONS.template.md; verification commands)
└── templates/
    └── STATE.template.md   (copy as-is, for creating future STATE.md files)

Then, for each registered project the user can reach from this machine, create a root STATE.md from STATE.template.md unless an explicit registry exception applies. Preserve and adapt existing state rather than overwriting it blindly. Fill it from evidence, not imagination: read the repo's README, run git log --oneline -15, look at open branches. Ask the user to confirm the "Now" and "Next" sections because repository history may not show current priorities.

Keep STATE.md near 2 KB, replace stale information, and keep current project status out of HQ. Include branch/upstream, source commit or PR, dated checks, and local-only work in Verification. Preserve longer rationale in focused linked docs and explain when to read them; do not load all references at startup. Do not invent successful checks or a confirmed push from repository history.

For an existing checkout, inspect branch, upstream, remote, worktrees, and dirty files before syncing. Fetch when available; use git pull --ff-only only on the intended branch with a clean checkout and known upstream. Preserve divergent or uncommitted work. Honor documented registry exceptions for read-only upstream clones, distribution mirrors, and projects with another context entry point.

Step 3: Wire it up

• Before committing, search the generated files for credential values and unnecessary personal details. Keep credential values out of Git.
• git init if needed, review the diff, and commit only intended setup files. If a remote is needed, recommend private by default. Create it or push when the user's request already authorizes that action; otherwise ask for the missing authorization. Preserve unrelated files and pending commits. Cross-machine handoffs require a shared Git remote or another synchronization method.
• Show the onboarding prompt from the generated README and say exactly what it does. Another agent can participate only if it can access the repository and follows the onboarding instructions.
• Offer the optional per-tool one-liners (CLAUDE.md, Cursor rules, AGENTS.md) from PROMPT.template.md for the projects they touch most.

Step 4: Verify the setup

Test the onboarding prompt in a fresh session. Ask, "where did I leave off?" If the answer is incomplete, check repository access, the latest pushed commit, whether the agent read the requested files, and whether STATE.md contains enough context.