Agent skills

Nobody moves a task across a board in Clocktopus. A task arrives from your tracker or from your coding agent, and its stage follows the work: the commits, pull requests and merges that name its key. The Work page updates as they arrive.

Where tasks come from

• Linear or Jira. With the tracker connected under Settings → Integrations, every task created there shows up in Clocktopus, with its title, description, link and kind.
• Your coding agent, through the MCP server. create_task creates a task in Clocktopus, with a key such as CLK-12 and a branch name that starts with it. The skills below create tasks this way, unless your repository's agent instructions (CLAUDE.md, AGENTS.md or a contributing guide) say to create them in your tracker: then they create them in Linear or Jira, through its own MCP server. Connecting a tracker alone doesn't move task creation there.
• The work itself. A key that turns up first in a branch, a commit or a time entry becomes a task too, shown by its key until a tracker sends a title.

How a task moves

Each stage is worked out from what happened, never set by hand:

Stage	Moves there when
In progress	A commit carries the key, an agent session works on it, or a draft pull request opens
In review	A pull request from a branch naming the key opens ready for review, or its draft is marked ready
Ready to ship	That pull request merges
Delivered	The work reaches one of the project's delivery branches (main or master unless set)
Cancelled	It is cancelled in the tracker or in Clocktopus, or every pull request naming the key closes without merging; in both cases until work on it resumes

In review, Ready to ship and a closed pull request's Cancelled come from pull request events, and so does delivery for a team that merges into its delivery branch, so the repository's webhook needs them: see which event powers what. The full rules are in Where each task stands.

The skills

clocktopus agent setup installs four skills and the MCP server they use into each coding agent it configures: a Clocktopus plugin in Claude Code, and clocktopus-create-task, clocktopus-start-work, clocktopus-refine and clocktopus-create-goal in ~/.agents/skills for Codex CLI, OpenCode and Cursor. Sign in to the MCP server once from the agent: /mcp in Claude Code, codex mcp login clocktopus in Codex, opencode mcp auth clocktopus in OpenCode, and Cursor Settings → MCP (or cursor-agent mcp login clocktopus) in Cursor. See the CLI for setup. In Claude Code each skill runs as /clocktopus:<name>, such as /clocktopus:start-work G-3; in the other agents, ask for it by name.

In Claude Code, Codex and Cursor, each session starts with a line from Clocktopus naming the task its branch carries, with the session's id. OpenCode shows no such line, so link_session finds the session itself: the one live in that repository.

The skills keep you in flow, from a one-line idea to a pull request:

• Note it now, do it later: create-task, then start-work.
• Hand an agent a goal: create-goal, then start-work G-3, which ends in stacked pull requests to review one at a time.

In either, refine is the extra pass in between when you aren't sure a task covers everything.

create-task (/clocktopus:create-task "<what to do>") notes a task for later from your words, written so an agent can pick it up: a title, the problem, why it matters, what to do and what is out of scope, and a kind, but no implementation design. It creates it straight away, without starting it or asking how, and adds it to a goal when you name one (G-3).

start-work carries a task through to an open pull request. It:

1. Reads the repository's project, its open tasks and its active goal.
2. Picks up the task you named, the one the branch names, an open task that matches what you describe, or the goal's next one. New work gets its task straight away.
3. Ties the session to the task (link_session), so its time and agent spend count toward it from then on, whatever branch it is on.
4. Works on a branch named after the key (clk-12-export-invoices) and puts the key in commit scopes (feat(clk-12): …).
5. Checks the code, asks in one round the questions the task and the code leave open, and writes your answers into the task. Then it does the work, runs the repository's checks, and opens the pull request.

It stops to ask when a decision comes up that nothing settles, when checks fail, and before anything beyond a pull request, such as merging or deploying. When the session-start line prompts it in a session started for something else, it only picks up the task and sets up the branch, and leaves committing to you. Something unrelated found mid-session becomes a new task, without switching branch.

Name a goal by the number on its card (/clocktopus:start-work G-3) and the session works through the goal's open tasks in order, unattended, each in a background agent of its own. Before it starts, it says which tasks look ready and which need thinking first, and asks only when some do.

refine (/clocktopus:refine BLA-12 or /clocktopus:refine G-3) is the extra pass for when you aren't sure a task covers everything: it gets tasks ready for an agent to take to a pull request without asking. For a task, it checks the code, asks you the questions the code can't answer, writes the answers into the task (the problem, what to do, the decisions made, what is out of scope) and marks it refined. For a goal, it first proposes the order of its tasks, what to release, what is already delivered and can be closed, duplicates and missing tasks, all checked against what actually shipped; then it refines every task not yet refined, with all the questions in one round. It changes nothing until you confirm, and never labels the goal in your tracker.

create-goal (/clocktopus:create-goal "<goal>") drafts a goal from what you describe, with a light breakdown into the tasks its outcome needs, in order, each a title, a line on what and a kind, reusing open tasks that already cover part of it. You confirm it all once, and it creates the goal and its tasks.

Every task the skills create gets a kind: bug, feature, improvement or tech, chosen from your words, and in Linear or Jira set as the matching label or issue type. Refined is Clocktopus's own mark that a task's open questions are settled and written into it: start-work asks little of a refined task, and works through a goal of refined tasks without stopping to check.

Stacked pull requests. When a session works through a goal, each task branches from the previous one and its pull request targets that branch, managed with gh stack on GitHub, so each pull request shows only its own task. A stacked pull request that merges into the branch below marks its task merged, so review and merge the stack from the bottom up.

The skills never set a stage, and never block or rewrite a commit for want of a key. They change a task only to write your answers into it, mark it refined, or say what a Clocktopus task's pull request delivered.