deep-work

# Deep Work — Time-Block the Day, Budget the Shallow

> **Portability:** Reasoning-led skill with 3 stdlib Python scripts. No external APIs, no LLM calls in scripts. Works in Claude Code CLI and Claude.ai web. The scripts fix the arithmetic; you keep the judgment.

## What this does

A calendar full of reactions is not a plan. This skill turns a raw task list into a day where
attention is the protected resource: deep tasks get the earliest hours in blocks of at least 90
minutes, shallow work is batched into at most two windows, buffers absorb attention residue, and the
schedule flatly refuses more than 4 hours of deep demand — the trained daily ceiling. A local ledger
of focus sessions keeps the weekly deep-hours target measured, not felt.

## Step 1 — Classify and budget the shallow

Ask for today's task list with rough minutes per task (or take it from `$ARGUMENTS`). The auditor
classifies each task deep vs shallow (keyword heuristics; an explicit `:deep`/`:shallow` suffix always
wins), computes the shallow share against the budget, and prints the forcing question for every
shallow item — *how long would it take to train a smart recent graduate to do this?*

```bash
python scripts/shallow_work_auditor.py \
  --task "Write investor update:60" --task "Email triage:45" \
  --task "Analyze churn cohort:90:deep" --budget 50
```

`OVER-BUDGET` (exit 2) means cut, batch, or delegate before any schedule is built.

## Step 2 — Block the day

Feed the surviving tasks to the planner with the day's hard start and hard end (fixed-schedule
productivity: the end time does not move). Deep first and earliest, 10-minute buffers, shallow in
two batches (late morning + end of day), an optional fixed lunch:

```bash
python scripts/time_block_planner.py --start 08:30 --end 17:00 --lunch 12:30 \
  --task "Write product spec:120:deep" --task "Email sweep:30:shallow"
```

Two refusals, both exit 2: deep demand past the 4-hour cap (the planner names what to defer), and shallow overflow past `--end` (the planner names what to drop — the day never silently extends).

## Step 3 — Log the session, keep the streak

After each real focus block, log it. `status` shows this week's deep hours against the target (default 15); `streak` counts consecutive days with at least one session:

```bash
python scripts/focus_session_logger.py log --minutes 90 --label "Write product spec"
python scripts/focus_session_logger.py status --target 15
```

## Step 4 — Shutdown ritual

End the day with the shutdown checklist (`assets/shutdown_checklist.md`): capture every open loop, glance at tomorrow, say the closing phrase. An incompletely closed day steals tomorrow's first block.

## Scripts

| Script | Role |
|---|---|
| `scripts/shallow_work_auditor.py` | Deep/shallow classification + shallow share vs budget → WITHIN-BUDGET / OVER-BUDGET (exit 2) + the recent-graduate forcing question per shallow item. |
| `scripts/time_block_planner.py` | Energy-first schedule: deep blocks ≥90 min earliest, 4-hour deep cap (refuses, exit 2), ≤2 shallow batches, 10-min buffers, fixed lunch, overflow refusal. |
| `scripts/focus_session_logger.py` | JSON ledger of focus sessions: `log` / `status` (weekly hours vs target) / `streak`; atomic writes. |

## References

- [`references/deep_work_canon.md`](references/deep_work_canon.md) — deep vs shallow, the deep work hypothesis, the 4-hour ceiling, attention residue (6 sources)
- [`references/time_blocking_method.md`](references/time_blocking_method.md) — plan every minute, block sizes, buffers, guilt-free revision, fixed-schedule productivity (6 sources)
- [`references/shallow_work_budget.md`](references/shallow_work_budget.md) — the 30-50% band, saying no, batching, the recent-graduate heuristic, why the shutdown ritual works (6 sources)

## Assets

- [`assets/example_time_block_plan.md`](assets/example_time_block_plan.md) — a full worked day (audit → plan → mid-day revision → shutdown)
- [`assets/shutdown_checklist.md`](assets/shutdown_checklist.md) — end-of-day shutdown ritual template

## Rules

- **Depth first, earliest.** Deep blocks take the best hours; shallow work gets what is left, never the reverse.
- **Respect the refusals.** More than 4 deep hours is fake depth; overflow past the hard stop is a broken budget, not extra output.
- **Batch, never sprinkle.** Shallow work lives in at most two windows; a sprinkled inbox costs a full refocus each time.
- **Revise, don't abandon.** A broken block means redraw the rest of the day, not "the plan failed."
- **Close the day.** No shutdown ritual, no evening — open loops steal tomorrow's first block.

## Distinct From (don't reach for the wrong skill)

- **`productivity/andreessen`** — the 3x5 card picks WHAT matters today. Deep-work plans WHEN and HOW, with attention protected. Run the card first, then block the day here.
- **`project-management` capacity planning** — team-level capacity and sprint math. This is one person's attention across one day and one week.

---

**Version:** 1.0.0
**Build pattern:** Path-B method skill — Newport discipline preserved + deterministic scheduling scripts added.

[today's task list]

{
  "format": "aiskill/v1",
  "skill": {
    "name": "deep-work",
    "slug": "deep-work",
    "version": "1.0.0",
    "description": "Use when someone wants to plan a deep work day, time-block their calendar or task list, budget or cut shallow work, protect focus hours, track deep-work sessions and streaks, run an end-of-day shutdown ritual, or says \"/deep-work\" or \"/time-block\". Classifies tasks deep vs shallow, builds an energy-first time-blocked schedule that refuses deep demand past the 4-hour ceiling, batches shallow work into at most two windows, and logs focus sessions against a weekly target.",
    "category": "Productivity",
    "tags": [
      "productivity"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Deep Work — Time-Block the Day, Budget the Shallow\r\n\r\n> **Portability:** Reasoning-led skill with 3 stdlib Python scripts. No external APIs, no LLM calls in scripts. Works in Claude Code CLI and Claude.ai web. The scripts fix the arithmetic; you keep the judgment.\r\n\r\n## What this does\r\n\r\nA calendar full of reactions is not a plan. This skill turns a raw task list into a day where\r\nattention is the protected resource: deep tasks get the earliest hours in blocks of at least 90\r\nminutes, shallow work is batched into at most two windows, buffers absorb attention residue, and the\r\nschedule flatly refuses more than 4 hours of deep demand — the trained daily ceiling. A local ledger\r\nof focus sessions keeps the weekly deep-hours target measured, not felt.\r\n\r\n## Step 1 — Classify and budget the shallow\r\n\r\nAsk for today's task list with rough minutes per task (or take it from `$ARGUMENTS`). The auditor\r\nclassifies each task deep vs shallow (keyword heuristics; an explicit `:deep`/`:shallow` suffix always\r\nwins), computes the shallow share against the budget, and prints the forcing question for every\r\nshallow item — *how long would it take to train a smart recent graduate to do this?*\r\n\r\n```bash\r\npython scripts/shallow_work_auditor.py \\\r\n  --task \"Write investor update:60\" --task \"Email triage:45\" \\\r\n  --task \"Analyze churn cohort:90:deep\" --budget 50\r\n```\r\n\r\n`OVER-BUDGET` (exit 2) means cut, batch, or delegate before any schedule is built.\r\n\r\n## Step 2 — Block the day\r\n\r\nFeed the surviving tasks to the planner with the day's hard start and hard end (fixed-schedule\r\nproductivity: the end time does not move). Deep first and earliest, 10-minute buffers, shallow in\r\ntwo batches (late morning + end of day), an optional fixed lunch:\r\n\r\n```bash\r\npython scripts/time_block_planner.py --start 08:30 --end 17:00 --lunch 12:30 \\\r\n  --task \"Write product spec:120:deep\" --task \"Email sweep:30:shallow\"\r\n```\r\n\r\nTwo refusals, both exit 2: deep demand past the 4-hour cap (the planner names what to defer), and shallow overflow past `--end` (the planner names what to drop — the day never silently extends).\r\n\r\n## Step 3 — Log the session, keep the streak\r\n\r\nAfter each real focus block, log it. `status` shows this week's deep hours against the target (default 15); `streak` counts consecutive days with at least one session:\r\n\r\n```bash\r\npython scripts/focus_session_logger.py log --minutes 90 --label \"Write product spec\"\r\npython scripts/focus_session_logger.py status --target 15\r\n```\r\n\r\n## Step 4 — Shutdown ritual\r\n\r\nEnd the day with the shutdown checklist (`assets/shutdown_checklist.md`): capture every open loop, glance at tomorrow, say the closing phrase. An incompletely closed day steals tomorrow's first block.\r\n\r\n## Scripts\r\n\r\n| Script | Role |\r\n|---|---|\r\n| `scripts/shallow_work_auditor.py` | Deep/shallow classification + shallow share vs budget → WITHIN-BUDGET / OVER-BUDGET (exit 2) + the recent-graduate forcing question per shallow item. |\r\n| `scripts/time_block_planner.py` | Energy-first schedule: deep blocks ≥90 min earliest, 4-hour deep cap (refuses, exit 2), ≤2 shallow batches, 10-min buffers, fixed lunch, overflow refusal. |\r\n| `scripts/focus_session_logger.py` | JSON ledger of focus sessions: `log` / `status` (weekly hours vs target) / `streak`; atomic writes. |\r\n\r\n## References\r\n\r\n- [`references/deep_work_canon.md`](references/deep_work_canon.md) — deep vs shallow, the deep work hypothesis, the 4-hour ceiling, attention residue (6 sources)\r\n- [`references/time_blocking_method.md`](references/time_blocking_method.md) — plan every minute, block sizes, buffers, guilt-free revision, fixed-schedule productivity (6 sources)\r\n- [`references/shallow_work_budget.md`](references/shallow_work_budget.md) — the 30-50% band, saying no, batching, the recent-graduate heuristic, why the shutdown ritual works (6 sources)\r\n\r\n## Assets\r\n\r\n- [`assets/example_time_block_plan.md`](assets/example_time_block_plan.md) — a full worked day (audit → plan → mid-day revision → shutdown)\r\n- [`assets/shutdown_checklist.md`](assets/shutdown_checklist.md) — end-of-day shutdown ritual template\r\n\r\n## Rules\r\n\r\n- **Depth first, earliest.** Deep blocks take the best hours; shallow work gets what is left, never the reverse.\r\n- **Respect the refusals.** More than 4 deep hours is fake depth; overflow past the hard stop is a broken budget, not extra output.\r\n- **Batch, never sprinkle.** Shallow work lives in at most two windows; a sprinkled inbox costs a full refocus each time.\r\n- **Revise, don't abandon.** A broken block means redraw the rest of the day, not \"the plan failed.\"\r\n- **Close the day.** No shutdown ritual, no evening — open loops steal tomorrow's first block.\r\n\r\n## Distinct From (don't reach for the wrong skill)\r\n\r\n- **`productivity/andreessen`** — the 3x5 card picks WHAT matters today. Deep-work plans WHEN and HOW, with attention protected. Run the card first, then block the day here.\r\n- **`project-management` capacity planning** — team-level capacity and sprint math. This is one person's attention across one day and one week.\r\n\r\n---\r\n\r\n**Version:** 1.0.0\r\n**Build pattern:** Path-B method skill — Newport discipline preserved + deterministic scheduling scripts added.",
    "user_template": "[today's task list]"
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The deep-work/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/deep-work",
    "exported_at": "2026-11-03T07:41:22.405Z"
  }
}

format: aiskill/v1
skill:
  name: deep-work
  slug: deep-work
  version: 1.0.0
  description: >-
    Use when someone wants to plan a deep work day, time-block their calendar or task list, budget
    or cut shallow work, protect focus hours, track deep-work sessions and streaks, run an
    end-of-day shutdown ritual, or says "/deep-work" or "/time-block". Classifies tasks deep vs
    shallow, builds an energy-first time-blocked schedule that refuses deep demand past the 4-hour
    ceiling, batches shallow work into at most two windows, and logs focus sessions against a weekly
    target.
  category: Productivity
  tags:
    - productivity
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Deep Work — Time-Block the Day, Budget the Shallow\r\n\r\n> **Portability:** Reasoning-led skill with 3 stdlib Python scripts. No external APIs, no LLM calls in scripts. Works in Claude Code CLI and Claude.ai web. The scripts fix the arithmetic; you keep the judgment.\r\n\r\n## What this does\r\n\r\nA calendar full of reactions is not a plan. This skill turns a raw task list into a day where\r\nattention is the protected resource: deep tasks get the earliest hours in blocks of at least 90\r\nminutes, shallow work is batched into at most two windows, buffers absorb attention residue, and the\r\nschedule flatly refuses more than 4 hours of deep demand — the trained daily ceiling. A local ledger\r\nof focus sessions keeps the weekly deep-hours target measured, not felt.\r\n\r\n## Step 1 — Classify and budget the shallow\r\n\r\nAsk for today's task list with rough minutes per task (or take it from `$ARGUMENTS`). The auditor\r\nclassifies each task deep vs shallow (keyword heuristics; an explicit `:deep`/`:shallow` suffix always\r\nwins), computes the shallow share against the budget, and prints the forcing question for every\r\nshallow item — *how long would it take to train a smart recent graduate to do this?*\r\n\r\n```bash\r\npython scripts/shallow_work_auditor.py \\\r\n  --task \"Write investor update:60\" --task \"Email triage:45\" \\\r\n  --task \"Analyze churn cohort:90:deep\" --budget 50\r\n```\r\n\r\n`OVER-BUDGET` (exit 2) means cut, batch, or delegate before any schedule is built.\r\n\r\n## Step 2 — Block the day\r\n\r\nFeed the surviving tasks to the planner with the day's hard start and hard end (fixed-schedule\r\nproductivity: the end time does not move). Deep first and earliest, 10-minute buffers, shallow in\r\ntwo batches (late morning + end of day), an optional fixed lunch:\r\n\r\n```bash\r\npython scripts/time_block_planner.py --start 08:30 --end 17:00 --lunch 12:30 \\\r\n  --task \"Write product spec:120:deep\" --task \"Email sweep:30:shallow\"\r\n```\r\n\r\nTwo refusals, both exit 2: deep demand past the 4-hour cap (the planner names what to defer), and shallow overflow past `--end` (the planner names what to drop — the day never silently extends).\r\n\r\n## Step 3 — Log the session, keep the streak\r\n\r\nAfter each real focus block, log it. `status` shows this week's deep hours against the target (default 15); `streak` counts consecutive days with at least one session:\r\n\r\n```bash\r\npython scripts/focus_session_logger.py log --minutes 90 --label \"Write product spec\"\r\npython scripts/focus_session_logger.py status --target 15\r\n```\r\n\r\n## Step 4 — Shutdown ritual\r\n\r\nEnd the day with the shutdown checklist (`assets/shutdown_checklist.md`): capture every open loop, glance at tomorrow, say the closing phrase. An incompletely closed day steals tomorrow's first block.\r\n\r\n## Scripts\r\n\r\n| Script | Role |\r\n|---|---|\r\n| `scripts/shallow_work_auditor.py` | Deep/shallow classification + shallow share vs budget → WITHIN-BUDGET / OVER-BUDGET (exit 2) + the recent-graduate forcing question per shallow item. |\r\n| `scripts/time_block_planner.py` | Energy-first schedule: deep blocks ≥90 min earliest, 4-hour deep cap (refuses, exit 2), ≤2 shallow batches, 10-min buffers, fixed lunch, overflow refusal. |\r\n| `scripts/focus_session_logger.py` | JSON ledger of focus sessions: `log` / `status` (weekly hours vs target) / `streak`; atomic writes. |\r\n\r\n## References\r\n\r\n- [`references/deep_work_canon.md`](references/deep_work_canon.md) — deep vs shallow, the deep work hypothesis, the 4-hour ceiling, attention residue (6 sources)\r\n- [`references/time_blocking_method.md`](references/time_blocking_method.md) — plan every minute, block sizes, buffers, guilt-free revision, fixed-schedule productivity (6 sources)\r\n- [`references/shallow_work_budget.md`](references/shallow_work_budget.md) — the 30-50% band, saying no, batching, the recent-graduate heuristic, why the shutdown ritual works (6 sources)\r\n\r\n## Assets\r\n\r\n- [`assets/example_time_block_plan.md`](assets/example_time_block_plan.md) — a full worked day (audit → plan → mid-day revision → shutdown)\r\n- [`assets/shutdown_checklist.md`](assets/shutdown_checklist.md) — end-of-day shutdown ritual template\r\n\r\n## Rules\r\n\r\n- **Depth first, earliest.** Deep blocks take the best hours; shallow work gets what is left, never the reverse.\r\n- **Respect the refusals.** More than 4 deep hours is fake depth; overflow past the hard stop is a broken budget, not extra output.\r\n- **Batch, never sprinkle.** Shallow work lives in at most two windows; a sprinkled inbox costs a full refocus each time.\r\n- **Revise, don't abandon.** A broken block means redraw the rest of the day, not \"the plan failed.\"\r\n- **Close the day.** No shutdown ritual, no evening — open loops steal tomorrow's first block.\r\n\r\n## Distinct From (don't reach for the wrong skill)\r\n\r\n- **`productivity/andreessen`** — the 3x5 card picks WHAT matters today. Deep-work plans WHEN and HOW, with attention protected. Run the card first, then block the day here.\r\n- **`project-management` capacity planning** — team-level capacity and sprint math. This is one person's attention across one day and one week.\r\n\r\n---\r\n\r\n**Version:** 1.0.0\r\n**Build pattern:** Path-B method skill — Newport discipline preserved + deterministic scheduling scripts added."
  user_template: "[today's task list]"
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The deep-work/ folder contains
        SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/deep-work
  exported_at: "2026-11-03T07:41:22.405Z"