/pomodoro

name: pomodoro
description: Simple Pomodoro timer for focused work sessions with session tracking and productivity analytics. Use when users request focus timers, ask about productivity patterns, or want to track work sessions over time. Demonstrates the System Skill Pattern (CLI + SKILL.md + Database).
license: MIT
allowed-tools:
  - Bash
  - Read

Pomodoro Timer Skill

Overview

A 25-minute timer for focused work sessions that saves every session to SQLite. Enables history tracking, productivity analytics, and pattern recognition over time.

**This is a System Skill** - it provides handles to operate a personal data system. As commands run and sessions accumulate, context builds and compounds. The system learns patterns and provides increasingly valuable insights through an OODA loop of observation, orientation, decision, and action.

Mental Model: The OODA Loop

Operating this skill involves running a continuous cycle:

1. **Observe** → Check current status (`./pomodoro status`) and review history (`./pomodoro history`) 2. **Orient** → Analyze patterns in the data (`./pomodoro stats --period week`) 3. **Decide** → Determine optimal actions (e.g., "Morning sessions have 95% completion - schedule deep work then") 4. **Act** → Start sessions (`./pomodoro start`), provide recommendations, celebrate milestones

Each cycle builds on accumulated data, making insights more valuable over time.

Dependencies

• Binary location: `~/.claude/skills/pomodoro/pomodoro`
• Database: Auto-created at `~/.claude/skills/pomodoro/pomodoro.db` on first run
• No external dependencies required

Quick Decision Tree

User task → What kind of request?
   ├─ Start focused work → Check status first, then start session
   ├─ Check current timer → Use status command
   ├─ Review productivity → Use stats command (day/week/month/year)
   ├─ View past sessions → Use history command
   └─ Stop early → Use stop command

Core Commands

**To see all available options**: Run `./pomodoro --help` or `./pomodoro <command> --help`

Starting a Session

Begin a Pomodoro session:

# Traditional 25-minute Pomodoro
./pomodoro start --task "Refactor authentication module"

# Custom durations and cycles
./pomodoro start --task "Quick review" --work 5 --break 3 --cycles 2
./pomodoro start --task "Deep focus" --work 50 --break 10 --cycles 1

# Flash cards (rapid cycles)
./pomodoro start --task "Flash cards" --work 2 --break 1 --cycles 5

**Options:**

• `--work <minutes>` - Work duration (default: 25)
• `--break <minutes>` - Break duration (default: 5)
• `--cycles <count>` - Number of work+break rounds (default: 1)

**Behavior:**

• Only one session can run at a time
• Timer runs in foreground showing progress every minute
• Breaks start automatically after work sessions
• Next work session starts automatically after break (if cycles remaining)
• Each work session saved separately to database

**JSON output example:**

./pomodoro start --task "Write docs" --json
# Returns: {"status": "started", "task": "Write docs", "duration": 25, "started_at": "2025-10-22T14:30:00Z"}

Checking Status

See if a timer is running:

./pomodoro status
./pomodoro status --json  # For programmatic use

**Output example:**

Active session: "Write documentation"
Started: 2:30 PM
Time remaining: 18 minutes

Viewing History

Review past sessions:

./pomodoro history --days 7    # Last 7 days
./pomodoro history --days 30   # Last 30 days
./pomodoro history --json      # For programmatic use

**Output includes:**

• Task names
• Start and completion times
• Duration
• Completion status (completed vs. stopped early)

Analyzing Productivity

Get insights from accumulated data:

./pomodoro stats --period day     # Today's stats
./pomodoro stats --period week    # This week
./pomodoro stats --period month   # This month
./pomodoro stats --period year    # This year
./pomodoro stats --json           # For programmatic use

**Statistics include:**

• Total and completed sessions
• Completion rate (% of sessions finished)
• Total focus time
• Most productive hours of day
• Task distribution (which tasks completed most often)

**JSON output example:**

{
  "period": "week",
  "total_sessions": 23,
  "completed": 19,
  "completion_rate": 0.826,
  "focus_hours": 7.9,
  "productive_hours": [9, 10, 11],
  "top_tasks": ["Refactoring", "Documentation", "Code review"]
}

Stopping Early

End the current session before completion:

./pomodoro stop

Use when interruptions occur or task completes early. Session marked as incomplete in database.

Essential Workflows

Starting Focused Work

To help a user start a Pomodoro session:

1. **Check for active session**: `./pomodoro status` 2. **If clear, start with appropriate options**:

• Traditional: `./pomodoro start --task "Deep work on authentication"`
• Custom: `./pomodoro start --task "Sprint planning" --work 15 --break 5 --cycles 3`
• Flash cards: `./pomodoro start --task "Vocabulary review" --work 2 --break 1 --cycles 10`

3. **Confirm to user**: "25-minute Pomodoro started for [task name]. Timer running."

Daily Review

To provide daily productivity summary:

1. **Fetch today's data**: `./pomodoro stats --period day --json` 2. **Parse and present insights**:

• "Completed 6 Pomodoros today (3.0 hours of focus time)"
• "5/6 sessions completed - 83% completion rate"
• "Most work on: Refactoring, Documentation"
• "Productive hours: 9-11 AM"

Weekly Analysis

To provide weekly productivity review:

1. **Fetch week's data**: `./pomodoro stats --period week --json` 2. **Identify patterns**:

• Compare to previous weeks if data available
• Note peak productive hours
• Identify which task types have highest completion rates

3. **Make recommendations**:

• "Schedule deep work during your peak hours (9-11 AM)"
• "Coding sessions have 90% completion vs 70% for