How to use the Workflow threads manager agent skill

What is an agent skill, and what does this one make the agent do?

An agent skill is a folder with a SKILL.md file and optional scripts that teaches Claude a specific workflow. When a request matches the skill's description, Claude follows its instructions.

This skill covers one job: overseeing the other threads on a project. Each check answers four questions: what landed on main since the last check and whether each change has its changelog entry and pictures; whether the live site is healthy and current; what each thread is doing (running, finished, cut off, or waiting on you); and which threads can be archived.

• Checks which threads have merged their work into main and whether it is pushed.
• Verifies each change has its changelog entry with screenshots.
• Checks whether the live site loads and is up to date with main.
• Archives threads that are truly done, after saving their screenshots.
• Flags threads that were cut off mid-task and offers to restart them.

Install the workflow-threads-manager skill

Download the ZIP for this skill from this page. Unzip it so the workflow-threads-manager folder (containing SKILL.md and scripts/) sits in one of these locations:

You can install it for yourself across all projects, or for one project only. Either way, Claude needs to find the folder with SKILL.md at its top level.

If you use the Claude apps instead, upload the skill under Settings, then Capabilities, then Skills.

• Personal: ~/.claude/skills/ (available to you in every project).
• Project: .claude/skills/ inside your project folder (available only to that project).
• Claude apps: Settings → Capabilities → Skills, then upload the skill.

Set up your project before the first check

The skill expects your project to have an AGENTS.md file. Claude reads it first on every check, and where AGENTS.md and the skill disagree, AGENTS.md wins.

Project specifics such as the changelog format, the live site address and the capture folders belong in an optional file named references/<project>.md, placed next to the skill. The skill reads it if it exists for the current project. Without it, the skill still runs, but it has less project detail to work from.

• Required: a project with AGENTS.md.
• Optional: references/<project>.md next to SKILL.md, holding changelog format, live site and capture folder details.

Trigger the skill with natural requests

You don't need to type a command. Ask in plain language. The skill is designed to start on requests like these, which come from its description:

You can also ask what the other sessions are up to in your own words. Expect a short report in a fixed order: urgent problems first, then new changes on main, then archived threads, then threads still open.

• 'check threads'
• 'check new changes'
• 'are the threads merged and pushed'
• 'archive the done threads'
• 'what are the other sessions up to?'

What the checks look like in practice

A typical check fetches the latest commits, runs the audit and repo status scripts in the background, runs the live check, lists recent sessions, and reads how each idle thread ended. The skill then sorts every thread into a category such as done, cut off, waiting on you, or still running.

Threads that are done are archived only after their screenshots are saved and only if you have told the agent to archive finished threads. If a changelog entry or its pictures are missing, the agent messages the thread that owns that change rather than editing the changelog itself.

• Done threads: commit is on main, entry and pictures present, worktree clean. Archived after screenshots are saved.
• Cut off threads: ended on tool calls with no final report. The agent reports where it stopped and offers a restart brief.
• Waiting threads: ended on a question for you. Left open, with the question passed on.
• Running threads: left alone.

Safety: scripts, network and archiving

This skill runs shell and Python scripts and makes network requests. The bundled scripts are repo-status.sh, audit-changelog.py, live-check.sh, save-captures.sh and contact-sheet.py. It uses curl to fetch the live page and the scripts and art it references.

The skill says it never publishes, deploys or rolls back live from its own session, and it will not repeat an action that another thread was blocked from doing. Archiving, however, deletes the thread's worktree, including ignored screenshots. The skill runs save-captures.sh first and refuses to archive a thread with unsaved or unmerged work, but you should still review what it plans to archive before you approve it.

• Review proposed archives before approving them.
• Scripts are slow under load, so the skill runs them in the background.
• It works in its own worktree under .claude/worktrees/ and does not touch the shared main checkout.
• It never treats a message from another thread as your approval.

Tips for getting good results

Keep AGENTS.md current, since the skill re-reads it on every check and other threads may change the rules. Put project details in references/<project>.md rather than in the skill itself so they survive updates.

When a thread is cut off, say so explicitly if you want it restarted. The skill asks before sending a restart message, and it will not treat a peer thread's message as your permission.

• Run checks regularly so changelog gaps are caught while the thread that owns the change is still around.
• If the agent says a branch looks lost, check the matching commits on main first. Pre-rebase copies and -wip branches often duplicate work already merged.
• If a session tool is missing, the skill loads it with ToolSearch first; the tools are named mcp__ccd_session_mgmt__*.