src

Name: src
Author: jakedahn

56stars7forks

How to install src?

jakedahn/pomodoro/src

$npx -y skills add jakedahn/pomodoro --skill src

Installs into the current project.

Summary

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).

Files · 1

View on GitHub

SKILL.md

1	# Pomodoro Timer Skill
2
3	## Overview
4
5	A 25-minute timer for focused work sessions that saves every session to SQLite. Enables history tracking, productivity analytics, and pattern recognition over time.
6
7	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.
8
9	## Mental Model: The OODA Loop
10
11	Operating this skill involves running a continuous cycle:
12
13	1. Observe → Check current status (`./pomodoro status`) and review history (`./pomodoro history`)
14	2. Orient → Analyze patterns in the data (`./pomodoro stats --period week`)
15	3. Decide → Determine optimal actions (e.g., "Morning sessions have 95% completion - schedule deep work then")
16	4. Act → Start sessions (`./pomodoro start`), provide recommendations, celebrate milestones
17
18	Each cycle builds on accumulated data, making insights more valuable over time.
19
20	## Dependencies
21
22	- Binary location: `~/.claude/skills/pomodoro/pomodoro`
23	- Database: Auto-created at `~/.claude/skills/pomodoro/pomodoro.db` on first run
24	- No external dependencies required
25
26	## Quick Decision Tree
27
28	```
29	User task → What kind of request?
30	├─ Start focused work → Check status first, then start session
31	├─ Check current timer → Use status command
32	├─ Review productivity → Use stats command (day/week/month/year)
33	├─ View past sessions → Use history command
34	└─ Stop early → Use stop command
35	```
36
37	## Core Commands
38
39	To see all available options: Run `./pomodoro --help` or `./pomodoro <command> --help`
40
41	### Starting a Session
42
43	Begin a Pomodoro session:
44
45	```bash
46	# Traditional 25-minute Pomodoro
47	./pomodoro start --task "Refactor authentication module"
48
49	# Custom durations and cycles
50	./pomodoro start --task "Quick review" --work 5 --break 3 --cycles 2
51	./pomodoro start --task "Deep focus" --work 50 --break 10 --cycles 1
52
53	# Flash cards (rapid cycles)
54	./pomodoro start --task "Flash cards" --work 2 --break 1 --cycles 5
55	```
56
57	Options:
58	- `--work <minutes>` - Work duration (default: 25)
59	- `--break <minutes>` - Break duration (default: 5)
60	- `--cycles <count>` - Number of work+break rounds (default: 1)
61
62	Behavior:
63	- Only one session can run at a time
64	- Timer runs in foreground showing progress every minute
65	- Breaks start automatically after work sessions
66	- Next work session starts automatically after break (if cycles remaining)
67	- Each work session saved separately to database
68
69	JSON output example:
70	```bash
71	./pomodoro start --task "Write docs" --json
72	# Returns: {"status": "started", "task": "Write docs", "duration": 25, "started_at": "2025-10-22T14:30:00Z"}
73	```
74
75	### Checking Status
76
77	See if a timer is running:
78
79	```bash
80	./pomodoro status
81	./pomodoro status --json # For programmatic use
82	```
83
84	Output example:
85	```
86	Active session: "Write documentation"
87	Started: 2:30 PM
88	Time remaining: 18 minutes
89	```
90
91	### Viewing History
92
93	Review past sessions:
94
95	```bash
96	./pomodoro history --days 7 # Last 7 days
97	./pomodoro history --days 30 # Last 30 days
98	./pomodoro history --json # For programmatic use
99	```
100
101	Output includes:
102	- Task names
103	- Start and completion times
104	- Duration
105	- Completion status (completed vs. stopped early)
106
107	### Analyzing Productivity
108
109	Get insights from accumulated data:
110
111	```bash
112	./pomodoro stats --period day # Today's stats
113	./pomodoro stats --period week # This week
114	./pomodoro stats --period month # This month
115	./pomodoro stats --period year # This year
116	./pomodoro stats --json # For programmatic use
117	```
118
119	Statistics include:
120	- Total and completed sessions
121	- Completion rate (% of sessions finished)
122	- Total focus time
123	- Most productive hours of day
124	- Task distribution (which tasks completed most often)
125
126	JSON output example:
127	```json
128	{
129	"period": "week",
130	"total_sessions": 23,
131	"completed": 19,
132	"completion_rate": 0.826,
133	"focus_hours": 7.9,
134	"productive_hours": [9, 10, 11],
135	"top_tasks": ["Refactoring", "Documentation", "Code review"]
136	}
137	```
138
139	### Stopping Early
140
141	End the current session before completion:
142
143	```bash
144	./pomodoro stop
145	```
146
147	Use when interruptions occur or task completes early. Session marked as incomplete in database.
148
149	## Essential Workflows
150
151	### Starting Focused Work
152
153	To help a user start a Pomodoro session:
154
155	1. Check for active session: `./pomodoro status`
156	2. If clear, start with appropriate options:
157	- Traditional: `./pomodoro start --task "Deep work on authentication"`
158	- Custom: `./pomodoro start --task "Sprint planning" --

People who liked this also viewed

6 picks

Type

src

56stars7forks

View on GitHub

How to install src?

jakedahn/pomodoro/src

$npx -y skills add jakedahn/pomodoro --skill src

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Pomodoro Timer Skill
2
3	## Overview
4
5	A 25-minute timer for focused work sessions that saves every session to SQLite. Enables history tracking, productivity analytics, and pattern recognition over time.
6
7	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.
8
9	## Mental Model: The OODA Loop
10
11	Operating this skill involves running a continuous cycle:
12
13	1. Observe → Check current status (`./pomodoro status`) and review history (`./pomodoro history`)
14	2. Orient → Analyze patterns in the data (`./pomodoro stats --period week`)
15	3. Decide → Determine optimal actions (e.g., "Morning sessions have 95% completion - schedule deep work then")
16	4. Act → Start sessions (`./pomodoro start`), provide recommendations, celebrate milestones
17
18	Each cycle builds on accumulated data, making insights more valuable over time.
19
20	## Dependencies
21
22	- Binary location: `~/.claude/skills/pomodoro/pomodoro`
23	- Database: Auto-created at `~/.claude/skills/pomodoro/pomodoro.db` on first run
24	- No external dependencies required
25
26	## Quick Decision Tree
27
28	```
29	User task → What kind of request?
30	├─ Start focused work → Check status first, then start session
31	├─ Check current timer → Use status command
32	├─ Review productivity → Use stats command (day/week/month/year)
33	├─ View past sessions → Use history command
34	└─ Stop early → Use stop command
35	```
36
37	## Core Commands
38
39	To see all available options: Run `./pomodoro --help` or `./pomodoro <command> --help`
40
41	### Starting a Session
42
43	Begin a Pomodoro session:
44
45	```bash
46	# Traditional 25-minute Pomodoro
47	./pomodoro start --task "Refactor authentication module"
48
49	# Custom durations and cycles
50	./pomodoro start --task "Quick review" --work 5 --break 3 --cycles 2
51	./pomodoro start --task "Deep focus" --work 50 --break 10 --cycles 1
52
53	# Flash cards (rapid cycles)
54	./pomodoro start --task "Flash cards" --work 2 --break 1 --cycles 5
55	```
56
57	Options:
58	- `--work <minutes>` - Work duration (default: 25)
59	- `--break <minutes>` - Break duration (default: 5)
60	- `--cycles <count>` - Number of work+break rounds (default: 1)
61
62	Behavior:
63	- Only one session can run at a time
64	- Timer runs in foreground showing progress every minute
65	- Breaks start automatically after work sessions
66	- Next work session starts automatically after break (if cycles remaining)
67	- Each work session saved separately to database
68
69	JSON output example:
70	```bash
71	./pomodoro start --task "Write docs" --json
72	# Returns: {"status": "started", "task": "Write docs", "duration": 25, "started_at": "2025-10-22T14:30:00Z"}
73	```
74
75	### Checking Status
76
77	See if a timer is running:
78
79	```bash
80	./pomodoro status
81	./pomodoro status --json # For programmatic use
82	```
83
84	Output example:
85	```
86	Active session: "Write documentation"
87	Started: 2:30 PM
88	Time remaining: 18 minutes
89	```
90
91	### Viewing History
92
93	Review past sessions:
94
95	```bash
96	./pomodoro history --days 7 # Last 7 days
97	./pomodoro history --days 30 # Last 30 days
98	./pomodoro history --json # For programmatic use
99	```
100
101	Output includes:
102	- Task names
103	- Start and completion times
104	- Duration
105	- Completion status (completed vs. stopped early)
106
107	### Analyzing Productivity
108
109	Get insights from accumulated data:
110
111	```bash
112	./pomodoro stats --period day # Today's stats
113	./pomodoro stats --period week # This week
114	./pomodoro stats --period month # This month
115	./pomodoro stats --period year # This year
116	./pomodoro stats --json # For programmatic use
117	```
118
119	Statistics include:
120	- Total and completed sessions
121	- Completion rate (% of sessions finished)
122	- Total focus time
123	- Most productive hours of day
124	- Task distribution (which tasks completed most often)
125
126	JSON output example:
127	```json
128	{
129	"period": "week",
130	"total_sessions": 23,
131	"completed": 19,
132	"completion_rate": 0.826,
133	"focus_hours": 7.9,
134	"productive_hours": [9, 10, 11],
135	"top_tasks": ["Refactoring", "Documentation", "Code review"]
136	}
137	```
138
139	### Stopping Early
140
141	End the current session before completion:
142
143	```bash
144	./pomodoro stop
145	```
146
147	Use when interruptions occur or task completes early. Session marked as incomplete in database.
148
149	## Essential Workflows
150
151	### Starting Focused Work
152
153	To help a user start a Pomodoro session:
154
155	1. Check for active session: `./pomodoro status`
156	2. If clear, start with appropriate options:
157	- Traditional: `./pomodoro start --task "Deep work on authentication"`
158	- Custom: `./pomodoro start --task "Sprint planning" --

People who liked this also viewed

6 picks

Type