pomodoro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

这是一款25分钟专注工作时段的计时器，会将每个会话保存到SQLite数据库中。支持历史跟踪、生产力分析以及长期的模式识别。

这是一个系统技能——它提供了操作个人数据系统的接口。随着命令的运行和会话的积累，上下文不断构建和丰富。系统会通过观察、定位、决策和行动的OODA循环来学习模式，并提供越来越有价值的见解。

Mental Model: The OODA Loop

思维模型：OODA循环

Operating this skill involves running a continuous cycle:

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

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

使用该技能需要遵循一个持续的循环：

观察 → 检查当前状态（
```
./pomodoro status
```
）并查看历史记录（
```
./pomodoro history
```
）
定位 → 分析数据中的模式（
```
./pomodoro stats --period week
```
）
决策 → 确定最优行动方案（例如：“上午时段的会话完成率达95%——安排深度工作在此时段”）
行动 → 开始会话（
```
./pomodoro start
```
）、提供建议、庆祝里程碑

每个循环都会基于积累的数据构建，让见解随着时间推移变得更有价值。

Dependencies

依赖项

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

二进制文件位置：
```
~/.claude/skills/pomodoro/pomodoro
```
数据库：首次运行时会自动在
```
~/.claude/skills/pomodoro/pomodoro.db
```
创建
无需外部依赖

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

用户任务 → 请求类型？
   ├─ 开始专注工作 → 先检查状态，再启动会话
   ├─ 查看当前计时器 → 使用status命令
   ├─ 查看生产力情况 → 使用stats命令（日/周/月/年）
   ├─ 查看过往会话 → 使用history命令
   └─ 提前结束 → 使用stop命令

Core Commands

核心命令

To see all available options: Run

./pomodoro --help

./pomodoro <command> --help

查看所有可用选项：运行

./pomodoro --help

或

./pomodoro <command> --help

Starting a Session

启动会话

Begin a Pomodoro session:

bash

undefined

开始一个Pomodoro会话：

bash

undefined

Traditional 25-minute Pomodoro

传统25分钟Pomodoro

./pomodoro start --task "Refactor authentication module"

./pomodoro start --task "重构认证模块"

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

./pomodoro start --task "快速审查" --work 5 --break 3 --cycles 2 ./pomodoro start --task "深度专注" --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:**
```bash
./pomodoro start --task "Write docs" --json

./pomodoro start --task "闪卡复习" --work 2 --break 1 --cycles 5


**选项说明：**
- `--work <minutes>` - 工作时长（默认：25）
- `--break <minutes>` - 休息时长（默认：5）
- `--cycles <count>` - 工作+休息的循环次数（默认：1）

**行为说明：**
- 同一时间只能运行一个会话
- 计时器在前台运行，每分钟显示进度
- 工作会话结束后自动开始休息
- 休息结束后自动开始下一个工作会话（如果还有剩余循环次数）
- 每个工作会话都会单独保存到数据库

**JSON输出示例：**
```bash
./pomodoro start --task "撰写文档" --json

Returns: {"status": "started", "task": "Write docs", "duration": 25, "started_at": "2025-10-22T14:30:00Z"}

返回：{"status": "started", "task": "撰写文档", "duration": 25, "started_at": "2025-10-22T14:30:00Z"}

undefined

undefined

Checking Status

查看状态

See if a timer is running:

bash

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

Output example:

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

查看计时器是否正在运行：

bash

./pomodoro status
./pomodoro status --json  # 供程序调用使用

输出示例：

活跃会话："撰写文档"
开始时间：下午2:30
剩余时间：18分钟

Viewing History

查看历史记录

Review past sessions:

bash

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

查看过往会话：

bash

./pomodoro history --days 7    # 最近7天
./pomodoro history --days 30   # 最近30天
./pomodoro history --json      # 供程序调用使用

输出包含：

任务名称
开始和完成时间
时长
完成状态（已完成 vs 提前结束）

Analyzing Productivity

分析生产力

Get insights from accumulated data:

bash

./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:

json

{
  "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"]
}

从积累的数据中获取见解：

bash

./pomodoro stats --period day     # 今日统计
./pomodoro stats --period week    # 本周统计
./pomodoro stats --period month   # 本月统计
./pomodoro stats --period year    # 本年统计
./pomodoro stats --json           # 供程序调用使用

统计内容包括：

总会话数和已完成会话数
完成率（完成会话的百分比）
总专注时长
一天中最高效的时段
任务分布（完成次数最多的任务类型）

JSON输出示例：

json

{
  "period": "week",
  "total_sessions": 23,
  "completed": 19,
  "completion_rate": 0.826,
  "focus_hours": 7.9,
  "productive_hours": [9, 10, 11],
  "top_tasks": ["重构", "文档撰写", "代码审查"]
}

Stopping Early

提前结束

End the current session before completion:

bash

./pomodoro stop

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

在会话完成前结束当前会话：

bash

./pomodoro stop

当出现中断或任务提前完成时使用。会话会在数据库中标记为未完成。

Essential Workflows

核心工作流

Starting Focused Work

启动专注工作

To help a user start a Pomodoro session:

Check for active session:
```
./pomodoro status
```

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

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

帮助用户启动Pomodoro会话：

检查是否有活跃会话：
```
./pomodoro status
```

如果无活跃会话，使用合适的选项启动：

传统模式：

./pomodoro start --task "认证模块深度工作"

自定义模式：

./pomodoro start --task "冲刺规划" --work 15 --break 5 --cycles 3

闪卡模式：

./pomodoro start --task "词汇复习" --work 2 --break 1 --cycles 10

向用户确认：“已为[任务名称]启动25分钟Pomodoro会话。计时器正在运行。”

Daily Review

每日回顾

To provide daily productivity summary:

Fetch today's data:
```
./pomodoro stats --period day --json
```
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"

提供每日生产力总结：

获取今日数据：
```
./pomodoro stats --period day --json
```
解析并呈现见解：
- “今日完成了6个Pomodoro会话（3.0小时专注时长）”
- “6个会话中完成了5个——完成率83%”
- 主要工作内容：重构、文档撰写
- 高效时段：上午9-11点

Weekly Analysis

周分析

To provide weekly productivity review:

Fetch week's data:
```
./pomodoro stats --period week --json
```
Identify patterns:
- Compare to previous weeks if data available
- Note peak productive hours
- Identify which task types have highest completion rates
Make recommendations:
- "Schedule deep work during your peak hours (9-11 AM)"
- "Coding sessions have 90% completion vs 70% for meetings - consider task segmentation"

提供每周生产力回顾：

获取本周数据：
```
./pomodoro stats --period week --json
```
识别模式：
- 如果有数据，与前几周进行比较
- 记录峰值高效时段
- 找出完成率最高的任务类型
提出建议：
- “建议在你的峰值高效时段（上午9-11点）安排深度工作”
- “编码会话完成率90%，而会议仅70%——考虑任务拆分”

Pattern Recognition Over Time

长期模式识别

As sessions accumulate, provide increasingly valuable insights:

After a few sessions (1-5):

"Completed 3 Pomodoros today"
"Building momentum with focus sessions"

After several days (5-20 sessions):

"7 completed out of 9 sessions - 78% completion rate"
"Most productive between 9-11 AM"

After a week (20-50 sessions):

"Strong week: 23 sessions with 85% completion"
"Peak productivity: 9-11 AM (95% completion) vs 2-4 PM (65% completion)"
"Consider scheduling deep work in morning hours"

After a month (50+ sessions):

"Coding tasks: 90% completion rate"
"Documentation tasks: 70% completion rate"
"Consider shorter Pomodoros (15 min) for documentation work"

After several months (100+ sessions):

"Completion rate improving: 72% → 85% over last 3 months"
"Wednesday is most productive day (92% completion)"
"Afternoon sessions improve when limited to 15 minutes"
"80% more sessions completed on coding vs documentation tasks"

Commands to use for pattern recognition:

bash

./pomodoro stats --period month --json  # Get monthly data
./pomodoro history --days 90 --json     # Review last 90 days

随着会话的积累，提供越来越有价值的见解：

几次会话后（1-5次）：

“今日完成了3个Pomodoro会话”
“专注会话习惯正在养成！”

几天后（5-20次会话）：

“9个会话中完成了7个——完成率78%”
“最高效时段为上午9-11点”

一周后（20-50次会话）：

“本周表现出色：23个会话，完成率85%”
“峰值生产力：上午9-11点（完成率95%） vs 下午2-4点（完成率65%）”
“考虑在上午时段安排深度工作”

一个月后（50+次会话）：

“编码任务：完成率90%”
“文档任务：完成率70%”
“考虑为文档工作使用更短的Pomodoro（15分钟）”

几个月后（100+次会话）：

“完成率持续提升：过去3个月从72%提升至85%”
“周三是最高效的一天（完成率92%）”
“下午会话限制在15分钟时表现更好”
“编码任务完成次数比文档任务多80%”

用于模式识别的命令：

bash

./pomodoro stats --period month --json  # 获取月度数据
./pomodoro history --days 90 --json     # 查看过去90天记录

Milestone Celebrations

里程碑庆祝

Acknowledge progress at key milestones:

10 sessions: "First 10 Pomodoros complete - building the habit!"
50 sessions: "50 sessions milestone - over 20 hours of focused work!"
100 sessions: "100 Pomodoros! That's 40+ hours of deep focus time."
High completion rates: "95% completion this week - excellent focus!"

To check milestone status:

./pomodoro stats --period year --json

在关键里程碑处认可用户的进步：

10次会话：“完成首个10个Pomodoro会话——习惯正在养成！”
50次会话：“达成50次会话里程碑——超过20小时的专注工作！”
100次会话：“100个Pomodoro会话！这相当于40+小时的深度专注时长。”
高完成率：“本周完成率95%——专注力极佳！”

查看里程碑状态：

./pomodoro stats --period year --json

Common Pitfalls

常见陷阱

Starting When Session Already Active

已有活跃会话时启动新会话

❌ Don't start a new session without checking status first ✅ Do run

./pomodoro status

before starting

Why: Only one session can run at a time. Starting when active causes error.

Pattern to follow:

bash

undefined

❌ 不要在未检查状态的情况下启动新会话 ✅ 务必在启动前运行

./pomodoro status

原因：同一时间只能运行一个会话。在已有活跃会话时启动会导致错误。

应遵循的流程：

bash

undefined

Check first

先检查状态

./pomodoro status

If "No active session", then start

如果显示“无活跃会话”，再启动

./pomodoro start --task "New task"

undefined

./pomodoro start --task "新任务"

undefined

Non-Descriptive Task Names

任务名称描述模糊

❌ Don't use vague names: "Work", "Stuff", "Things" ✅ Do use specific names: "Refactor auth module", "Write API docs", "Review PR #123"

Why: Descriptive names enable better analytics. Pattern recognition needs specificity to identify which task types work best.

❌ 不要使用模糊名称：“工作”、“事情”、“任务” ✅ 务必使用具体名称：“重构认证模块”、“撰写API文档”、“审查PR #123”

原因：描述性名称能实现更好的分析。模式识别需要具体信息来确定哪种任务类型效果最佳。

Interrupting Long-Running Sessions

中断长期运行的会话

❌ Don't let terminal close or process be killed during session ✅ Do use

./pomodoro stop

if interruption is necessary

Why: Interrupted sessions aren't saved to database. Use stop command to record partial session.

❌ 不要在会话运行时关闭终端或终止进程 ✅ 务必在需要中断时使用

./pomodoro stop

原因：中断的会话不会保存到数据库。使用stop命令可以记录部分会话。

Ignoring Completion Rate Signals

忽略完成率信号

❌ Don't ignore consistent low completion rates for certain task types ✅ Do adjust session length based on task type patterns

Why: If documentation tasks show 60% completion vs 90% for coding, shorter sessions (15 min) may work better for documentation.

How to identify:

bash

./pomodoro stats --period month --json

❌ 不要忽略某些任务类型持续较低的完成率 ✅ 务必根据任务类型的模式调整会话时长

原因：如果文档任务完成率为60%，而编码任务为90%，那么文档工作可能更适合使用较短的会话（15分钟）。

如何识别：

bash

./pomodoro stats --period month --json

Review completion rates by task type

按任务类型查看完成率

Suggest duration adjustments based on patterns

根据模式建议调整时长

undefined

undefined

Best Practices

最佳实践

Session Management

会话管理

Use descriptive task names for better analytics
Complete full 25 minutes when possible
Take breaks between sessions
Adjust duration based on task type (use
```
--work
```
flag)
Stop explicitly if interrupted (don't let process be killed)

使用描述性任务名称以获得更好的分析结果
尽可能完成完整的25分钟会话
会话之间适当休息
根据任务类型调整时长（使用
```
--work
```
参数）
中断时明确停止会话（不要直接终止进程）

User Interaction

用户交互

Celebrate milestones (10, 50, 100, 250, 500 sessions)
Acknowledge completion rates: "Excellent focus - 90% this week!"
Suggest optimal times based on historical data
Encourage consistent practice
Point out improvements: "Completion rate up from 75% to 85%"

庆祝里程碑（10、50、100、250、500次会话）
认可完成率：“专注力极佳——本周完成率90%！”
根据历史数据建议最佳时段
鼓励持续练习
指出进步：“完成率从75%提升至85%”

Data Analysis

数据分析

Review daily stats at end of each day
Check weekly patterns for scheduling insights
Track trends over time (month, year)
Use JSON output for custom analytics
Cross-reference task types with completion rates
Identify peak productive hours

每天结束时查看当日统计
检查每周模式以获取日程安排见解
跟踪长期趋势（月、年）
使用JSON输出进行自定义分析
交叉参考任务类型与完成率
确定峰值高效时段

Command Composition

命令组合

Combine commands for deeper insights:

bash

undefined

组合命令以获得更深入的见解：

bash

undefined

Morning check-in: status + daily stats

晨间检查：状态 + 当日统计

./pomodoro status ./pomodoro stats --period day

Weekly review: history + stats

每周回顾：历史记录 + 统计

./pomodoro history --days 7 --json ./pomodoro stats --period week --json

Long-term analysis: monthly trends

长期分析：月度趋势

./pomodoro stats --period month --json ./pomodoro history --days 90 --json

undefined

./pomodoro stats --period month --json ./pomodoro history --days 90 --json

undefined

Technical Notes

技术说明

JSON Output

JSON输出

All commands support

--json

flag for programmatic access:

bash

./pomodoro status --json
./pomodoro history --json
./pomodoro stats --json

Use JSON output when:

Parsing data programmatically
Building custom analytics
Feeding into other tools
Need structured output

所有命令都支持

--json

参数以用于程序调用：

bash

./pomodoro status --json
./pomodoro history --json
./pomodoro stats --json

在以下场景使用JSON输出：

以编程方式解析数据
构建自定义分析
集成到其他工具
需要结构化输出

Database

数据库

Location:
```
~/.claude/skills/pomodoro/pomodoro.db
```
Format: SQLite database with single
```
sessions
```
table
Persistence: All sessions saved permanently
Growth: Database grows with use (each session ~100 bytes)
Analytics: Richer insights as data accumulates
Maintenance: No cleanup or archiving needed

Schema:

sql

CREATE TABLE sessions (
  id INTEGER PRIMARY KEY,
  task TEXT NOT NULL,
  duration INTEGER NOT NULL,
  started_at TEXT NOT NULL,
  completed_at TEXT
);

位置：
```
~/.claude/skills/pomodoro/pomodoro.db
```
格式：SQLite数据库，包含单个
```
sessions
```
表
持久性：所有会话永久保存
增长：数据库会随着使用而增长（每个会话约100字节）
分析：数据积累越多，见解越丰富
维护：无需清理或归档

表结构：

sql

CREATE TABLE sessions (
  id INTEGER PRIMARY KEY,
  task TEXT NOT NULL,
  duration INTEGER NOT NULL,
  started_at TEXT NOT NULL,
  completed_at TEXT
);

Timer Behavior

计时器行为

Runs in foreground process (blocks terminal)
Shows progress every minute during work sessions
Shows progress every minute during break sessions
Automatically transitions from work → break → work
Each work session saved separately to database
Supports custom durations via flags

Example session flow (3 cycles):

Work 25min → Break 5min → Work 25min → Break 5min → Work 25min → Break 5min → Done

Result: 3 separate database entries (one per work session)

在前台进程运行（占用终端）
工作会话期间每分钟显示进度
休息会话期间每分钟显示进度
自动从工作→休息→工作切换
每个工作会话单独保存到数据库
支持通过参数自定义时长

会话流程示例（3个循环）：

工作25分钟 → 休息5分钟 → 工作25分钟 → 休息5分钟 → 工作25分钟 → 休息5分钟 → 结束

结果：数据库中生成3条独立记录（每个工作会话一条）

Binary Location

二进制文件位置

Path:
```
~/.claude/skills/pomodoro/pomodoro
```
Always use:
```
./pomodoro
```
when running from skill directory
Full path:
```
~/.claude/skills/pomodoro/pomodoro
```
from anywhere

To run from skill directory:

bash

cd ~/.claude/skills/pomodoro
./pomodoro start --task "Task name"

路径：
```
~/.claude/skills/pomodoro/pomodoro
```
技能目录内运行：始终使用
```
./pomodoro
```
全局运行：从任意位置使用完整路径
```
~/.claude/skills/pomodoro/pomodoro
```

在技能目录内运行：

bash

cd ~/.claude/skills/pomodoro
./pomodoro start --task "任务名称"

The System Skill Pattern in Action

系统技能模式的实际应用

This skill demonstrates the System Skill Pattern (CLI + SKILL.md + Database):

CLI Binary: Handles to operate the system - start sessions, query history, analyze patterns
SKILL.md: Operating procedure for the OODA loop (Observe → Orient → Decide → Act)
SQLite Database: Persistent memory where every session adds context

The key insight: With these three components, the skill animates a system rather than just responding to requests. Each interaction builds on the last. Analytics become richer. Insights get sharper. The tool compounds in value.

Example of compounding value:

Week 1: "Started 5 sessions"
Week 4: "Morning sessions: 95% completion. Afternoon: 70%. Schedule deep work mornings."
Month 3: "Coding: 90% completion. Docs: 72%. Try 15-minute sessions for documentation."

This pattern works for any skill where accumulating data adds value and where giving Claude handles to operate a system creates more utility than one-time responses.

See also: README.md for deeper technical details and implementation guide.

该技能演示了系统技能模式（CLI + SKILL.md + 数据库）：

CLI二进制文件：系统操作接口——启动会话、查询历史、分析模式
SKILL.md：OODA循环的操作流程（观察→定位→决策→行动）
SQLite数据库：持久化存储，每个会话都会添加上下文

核心见解：通过这三个组件，该技能能够激活一个系统，而不仅仅是响应用户请求。每次交互都会基于上一次交互构建。分析会变得更丰富，见解会更深刻。工具的价值会不断复合增长。

价值复合示例：

第1周：“启动了5个会话”
第4周：“上午会话完成率95%，下午70%。建议在上午安排深度工作。”
第3个月：“编码任务完成率90%，文档任务72%。建议文档工作使用15分钟会话。”

这种模式适用于任何积累数据能增加价值的技能，以及让Claude操作系统比单次响应更具实用性的场景。

另请参阅：README.md以获取更深入的技术细节和实现指南。