How to use the Session Flow Map agent skill

What is an agent skill, and what does session-flow make the agent do?

An agent skill is a packaged set of instructions, stored as a SKILL.md file, that Claude Code can follow when a task calls for it. The session-flow skill is one of these. It is part of the oh-my-claudecode (OMC) project and is released under the MIT licence.

When you invoke it, the agent reconstructs how the current conversation actually unfolded, using the user messages and tool results in that conversation. It separates the original goal from explicit goal changes, pivots, completed outcomes, dropped paths and decisions still waiting on you. Each stage gets one outcome marker and a compact evidence pointer, such as a real URL, an artifact path or a short quote. Where the agent is reconstructing something uncertain, for example after compaction, it marks the item as inferred rather than stating it as fact.

• Completed stages are marked with a tick and the outcome that the conversation supports.
• The current unfinished stage is marked with a triangle.
• Planned but unstarted stages are marked with a circle.
• Dropped paths are marked with scissors and the stated reason.
• Pivots show the old direction and the new evidenced direction.

Install the session-flow skill

Download the ZIP for this skill from this page. The skill ships as a single file, SKILL.md. You can install it in one of three ways.

For a personal install that applies to all your projects, unzip the download into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Trigger the skill with a request

The skill has a argument hint with two optional modes. With no argument it renders the full map and reconciles the session's stage Tasks. With short it returns only the goal, the current stage and anything that needs you, and it does not change any Tasks. With reset it removes only the Tasks it previously created, and confirms what was removed.

The skill is set to be invoked explicitly rather than automatically, so ask for it directly when you want it. Note that the source documents the mode argument as a hint, so the exact way you pass it may depend on your Claude Code setup.

• Full map: no argument
• Quick status: short
• Clear saved stage Tasks: reset

Example requests and what you get back

Use plain language when you come back to a session. For example, after a break you might ask for the full map of this session so you can see what was decided. If you only want the headline, ask for a short status. If you have finished a long piece of work and want the saved stage Tasks removed, ask for a reset.

A full map is capped at 15 lines: one line per stage plus concise goal, Needs you and Next lines. Stage lines cite their evidence, so you can check each claim against the conversation.

• Full map: Show me the session flow map for this conversation.
• Short: Give me a short status of this session with just the goal, current stage and what needs me.
• Reset: Reset the session-flow tasks for this session.

What the skill needs and what it does not do

To save stages into the session's native task list, Claude Code needs its native Task tools (TaskList, TaskGet, TaskCreate and TaskUpdate). The map itself still works without them, but it cannot be saved, and reset cannot inspect or remove tasks. The skill is part of the OMC project, and its continuation hook relies on an ownership marker it writes into each task description.

The skill is advisory. It summarises the conversation and does not plan or carry out work, and it does not replace your task list. It is also not useful for sessions with little history, because the skill is told to use fewer stages rather than invent work to fill the map.

Safety: according to the source, this skill runs no scripts and makes no network requests. Its only side effects are creating, updating or deleting its own marked Tasks in the session.

• Needs Claude Code with native Task tools to save stages
• Runs scripts: no
• Uses network: no
• Only touches Tasks it owns, identified by the subject prefix and ownership marker line
• Never edits, completes or deletes unmarked Tasks

Tips for getting a useful map

The map is only as good as the conversation behind it. Sessions with clear user messages and real tool results give the most reliable stages. Check the evidence pointers on any line that matters before acting on it, especially lines marked inferred.

Use short when you only need orientation, and the full map when you want to save stages into the task list for later. Use reset once a piece of work is done and you no longer want the saved stage Tasks.

• Ask for short first if you only need to know where you are.
• Check any line marked inferred against the original messages.
• Use reset to clear saved stages once they are no longer useful.