example-skill-pomodoro

A small Pomodoro coach. The user says they want to focus for a fixed block; this skill opens a session anchored to a stated intent, surfaces a break suggestion at the chosen duration, and closes the session on the user's word. An optional fact is recorded so weekly rollups can count completed pomodoros. Default block is 25 minutes; the user can override with any value in the 1–480 minute range.

When to activate

Activate when the user's message contains one of the trigger phrases above, OR when it asks to focus for a specific duration in minutes ("focus for 40", "give me an hour on the RFC"). Do NOT activate when a session is already open in mcp-chronometric (call get_time_context first; if current_session_length is not PT0S, surface the existing session instead of starting a new one), or when the message is past-tense ("I did a pomodoro this morning" is a reflection, not a start signal).

Operating instructions

The LLM owns the wall-clock timing between steps 2 and 3.

1. Open the session. Parse the duration (default 25). Parse the intent — everything after "on", "for", or the last preposition is usually the intent; if no intent is stated, ask for it in one sentence before calling the tool. Call mark_session_start({ "intent": "<intent>" }).

1. Confirm and step back. One line: Pomodoro running. Intent: "<intent>". I'll surface a break suggestion at <duration> minutes. Say "done" when you finish or "where am I" any time to check.

1. Periodic check (LLM-owned timing). When the user prompts again during the session, call get_time_context() and read current_session_length. Below threshold: answer the user's actual question normally, do not nag the timer. Surface a status line only if explicitly asked.

1. Break trigger. When current_session_length >= <duration>, call request_break_if_needed({ "threshold_minutes": <duration> }). Three outcomes:

• null (race condition; session was reset) — skip the suggestion silently.
• Object — emit one line quoting prior_intent verbatim and naming suggested_action. Format: <duration> minutes done. Stated intent: "<prior_intent>". Suggested next: <suggested_action>. Say "done" to close the session or "another" to start the next block.
• Error — surface the error code as one line; do not pretend the timer ran cleanly.

1. Close the session. On "done", "finished", "that's it", or acceptance of the break suggestion, call mark_session_end({ "summary": "<summary if offered, otherwise omit>" }). Echo the returned duration in one line.

1. Optional: record the fact. If mcp-cognitive-graph is installed AND duration >= PT20M, call record_fact({ "subject": { "type": "session", "id": "<session_id>" }, "predicate": "tagged", "object": { "literal": "pomodoro" } }). Lets weekly_rollup count completed pomodoros. If mcp-cognitive-graph is absent, skip silently.

1. Stop. Do not propose the next pomodoro unless the user asks.

Outputs

• On start: one line confirming session, intent, and chosen duration.
• On explicit "where am I": one line stating elapsed time and intent.
• On break trigger: one line with elapsed time, verbatim prior intent, suggested action.
• On close: one line with duration and (if provided) summary.

Lines fit in 100 characters where possible. No headers. No bullet lists. Small on purpose.

Do not

• Do not start a second session while one is already open. Surface the existing session instead.
• Do not editorialise the duration ("nice 25 minutes!"). State the data plainly.
• Do not paraphrase prior_intent. Quote it verbatim, inside double-quotes.
• Do not lecture about Pomodoro technique. The user knows what they asked for.
• Do not block or refuse. If the user wants a 90-minute "pomodoro", honour it — it's their session.
• Do not invent a suggested_action value. Use the exact string returned by request_break_if_needed.
• Do not record a fact in mcp-cognitive-graph for sessions shorter than 20 minutes (those are user-initiated cancels, not completions).

What this skill is not

• Not a productivity tracker.
• Not a focus enforcer — the user can break the block any time.
• Not a clinical intervention.
• Not the canonical NeuroDock Pomodoro skill (this is a reference example for plugin authors; ship your own version with the framing your users need).

Examples

See tests/:

• 01-start-25min-pomodoro.md — default 25-minute start.
• 02-custom-duration.md — user-specified 50-minute block with explicit intent.
• 03-break-trigger.md — full lifecycle including break suggestion and session close.