Pomodoro - System Skill Reference Implementation

A working example of the System Skill Pattern – an approach for building Claude Skills that persist state, learn from history, and provide increasingly useful insights over time.

The Pattern: CLI + SKILL.md + Database

Give Claude a command-line tool to run, instructions on how to operate a system, and a database to remember things. Watch it turn the crank, running its own OODA loop (Observe, Orient, Decide, Act) - building context that compounds across sessions.

This Pomodoro timer demonstrates the pattern in ~600 lines of code. It’s deliberately simple so you can see how the pieces fit together, then build your own.

Quick Install

# Add the marketplace (one-time setup)
/plugin marketplace add jakedahn/pomodoro

# Run the install script
~/.claude/plugins/marketplaces/pomodoro/install.sh

The Pomodoro skill will be installed to ~/.claude/skills/pomodoro/ and available immediately in Claude Code.

Requirements: macOS with Apple Silicon (arm64). For other platforms, see Building From Source.

Usage

Once installed, just ask Claude to help with Pomodoros:

"Start a pomodoro for writing documentation"
"What did I work on today?"
"How productive was I this week?"
"What times do I work best?"
"Let's do flash cards, start 5 2min/1min pomodoro cycles"

Claude will use the Pomodoro skill to:

• Start 25-minute focus timers
• Track all your sessions
• Analyze productivity patterns
• Suggest optimal work times

The System Skill Pattern

This implementation demonstrates three components working together to create a system that Claude can animate:

1. The CLI Binary

A standalone executable that provides handles for Claude to operate the system:

./pomodoro start --task "Deep work on authentication"
./pomodoro stats --period week
./pomodoro history --days 30

Key attributes:

• Self-contained (no runtime dependencies, no configuration)
• Helpful --help documentation for each command

The Pomodoro CLI provides five essential commands:

• start - Begin a 25-minute focus session
• stop - End current session early
• status - Check if timer is running
• history - View past sessions
• stats - Analyze productivity patterns

2. SKILL.md

The tutorial that teaches Claude how to think about and operate the system:

• What the system is and when to use it
• Which commands to run in different situations
• How to interpret output and look for patterns
• The mental model and decision flow

This is where you share the operating procedure. Claude uses this to run its OODA loop - observing sessions, orienting to patterns, deciding when to intervene, and acting by running CLI commands.

3. SQLite Database

Persistent storage that accumulates value over time. In this case, a simple schema: