Flow Skill / 心流.skill

Language / 语言: 中文 | English

将模糊的雄心，转化为 25 分钟的清晰执行。 Translating vague ambitions into 25 minutes of clear execution.

目录 / Table of Contents

中文
English

中文

Flow Skill 是一个面向 Claude Code / Claude Skill 环境的本地模块化技能。它不是普通的“计划生成器”，而是一个用于用户明确请求心流状态、深度工作或专注执行 session 时的执行辅助系统。

本项目仍处于开发和测试阶段，欢迎大家试用、反馈触发效果、产出文件质量和真实工作流中的问题。

它会把模糊目标转换为一个可开始、可检查、可恢复的 Flow Session：先识别任务类型，再结合可用时间、当前精力、输出格式和执行权限，生成紧凑的终端指令与可复用的本地指导文件。

理论内核与架构映射

“心流（Flow）”由心理学家 Mihaly Csikszentmihalyi 提出，指人完全沉浸在活动中、注意力高度集中、行动与反馈形成闭环的状态。

Flow Skill 不声称能自动制造心流，但它会把终端里的任务协作设计成更接近心流触发条件的形态：目标更清晰、挑战更匹配当前状态、反馈更可见。

1. 清晰且结构化的目标（Clear Goals）

心理学阻碍： 面对“写个方案”“复习高数”“整理项目”这类模糊任务时，大脑容易因为不知道从何下手而进入分析瘫痪。

Flow Skill 映射： flow-skills/00_router.md 会把任务切成当前 session 可执行的阶段，并路由到 7 个 cognitive models 之一。终端默认只显示最短可执行卡片：Now、DoD、Next 2 minutes、Generated file 和 How to use。

2. 挑战与技能的动态平衡（Challenge-Skill Balance）

心理学阻碍： 任务太难会引发焦虑，任务太简单会引发无聊；两者都会破坏专注。

Flow Skill 映射： Flow Skill 明确触发后，如果用户没有提供可用时间和精力状态，会先做两步 intake：第一步选择可用时间，第二步选择当前精力。时间选项固定为 10 / 25 / 45 分钟，默认推荐 25 分钟；精力状态包括 Low / Medium / High，默认推荐 Medium。

Low energy 会自动降级输出策略：禁用 Python、Jupyter 和 complex HTML，默认使用短 Markdown 指令，必要时只允许轻量静态 HTML。

3. 即时且可见的反馈（Immediate Feedback）

心理学阻碍： 如果努力了一段时间却看不到进展，用户容易重新回到聊天、优化计划或拖延循环。

Flow Skill 映射： 当 execution_permission: allowed 且环境允许写入文件时，Flow Skill 必须在 flow-skill-output/ 下创建可复用的 Markdown 指导文件。普通任务默认生成 flow-guide-YYYYMMDD-HHMM.md，学习/复习任务默认生成 study-guide-YYYYMMDD-HHMM.md。

终端仍保持 compact，但必须告诉用户生成文件在哪里，以及如何使用它。

核心特色（Core Features）

明确触发边界： 只有显式提到 心流、flow、flow state、深度工作状态，或要求转成 focused session / workflow 时才使用。
消除启动摩擦： 每个 Session 优先输出 Next 2 minutes 指令，将下一步拆解为立刻可执行的物理动作。
物理产出物固化： 允许执行时生成 flow-guide-*.md 或 study-guide-*.md，避免只停留在终端对话里。
动态能量适配： 根据 10 / 25 / 45 分钟时间边界和 Low / Medium / High 精力状态调整输出复杂度。
认知模型解耦： 使用 7 个 cognitive models 区分生成、诊断、萃取、统合、内化、强化和统筹等不同脑力劳动。
导航式学习指导： 学习/复习任务不只输出问题，还会生成包含 Instruction、Where to work、How to work、Answer area 和 Checkpoint 的 study guide。

安装指南（Installation）

本项目作为本地 Claude Skill 使用。部署前请确认你的 Claude Code / Claude Skill 环境支持本地 skills。

步骤 1：复制项目文件

将整个 flow-skill 文件夹放入本地的 Claude Skills 目录（确保包含外层文件夹）：

Windows: C:\Users\你的用户名\.claude\skills\flow-skill
macOS / Linux: ~/.claude/skills/flow-skill

步骤 2：确认目录结构

安装后的目录应至少包含：

flow-skill/
  SKILL.md
  README.md
  evals/
  scripts/
  flow-skills/

步骤 3：重新打开会话并验证触发

重新打开 Claude Code 后，使用明确触发语句测试：

我想进入心流状态，用 25 分钟完成这个任务的第一轮执行。

如果自动触发不稳定，也可以显式使用 /flow-skill。

触发条件与使用示例（Usage & Triggers）

Flow Skill 采用严格触发边界，避免普通任务被过度包装为心流 session。

强制调用（推荐）

如果希望 100% 确保调用 Flow Skill，可以直接使用终端技能命令：

/flow-skill "我的目标或任务"
/flow-skill "帮我整理这些代码，25 分钟时间"

自然语言触发

“我想进入心流状态来完成这个任务。”
“Turn this into a flow state session.”
“帮我把这件事变成 25 分钟专注块。”
“请把这个目标转换成 deep-work session。”

不会触发

“帮我修 bug。”
“帮我规划项目。”
“总结这份材料。”

除非用户明确补充：把这些工作转成心流状态、深度工作或 focused execution session。

经典交互示例

User:
我想进入心流状态复习 NLP 课程里的 Transformer 机制，目标是能闭卷解释 self-attention。

System:
Before we start, choose the time for this session. This does not limit the full guide; it only sets today's execution boundary.

A. 10 minutes - minimum visible progress
B. 25 minutes - standard focus block (recommended/default)
C. 45 minutes - complete learning/review unit

User chooses B.

System:
Now choose your current energy state.

A. Low - tired, just help me start
B. Medium - steady progress (recommended/default)
C. High - complex understanding and organization are ok

User chooses B.

System:
Now: 25m - 理解并能复述 Transformer self-attention 的核心机制。

DoD:
- [ ] 补全学习指南中的 2 个填空。
- [ ] 闭卷回答 1 个主动回忆问题。

Next 2 minutes:
1. 将屏幕分屏，左侧打开生成的指南，右侧打开课程 PPT。
2. 找到介绍 Self-Attention 的幻灯片并阅读 1 分钟。

Generated file: flow-skill-output/study-guide-20260608-1000.md

How to use: 打开该文件，按 Next 2 minutes 开始，并用 DoD/进度标记检查完成状态。

产出物说明（Artifacts）

Flow Skill 的产出分为两层：终端里的 compact card 和本地文件里的完整指导材料。终端负责让用户马上开始，本地文件负责承载可复用的执行或学习脚手架。

终端 Compact Card

终端默认只展示最短可执行信息：

字段	含义
`Now`	当前 session 要完成的一个明确阶段，不是完整项目计划。
`DoD`	Definition of Done（完成定义），表示本轮 session 可观察的完成标准。
`Next 2 minutes`	接下来两分钟可以立刻做的物理动作，用于降低启动摩擦。
`Generated file`	已创建的本地指导文件路径；如果创建失败，会明确写 `Not created`。
`How to use`	告诉用户如何打开文件并用 DoD、复选框或进度标记推进。
`Optional details`	仅在必要时展示假设、风险、路由、状态快照或恢复信息。

默认 Markdown 指导文件

当 Flow Skill 被触发并且执行被允许时，默认会尝试在本地生成 Markdown 指导文件：

普通任务：flow-skill-output/flow-guide-YYYYMMDD-HHMM.md
学习/复习任务：flow-skill-output/study-guide-YYYYMMDD-HHMM.md

(提示：如果你的运行环境权限受限，导致无法自动创建 flow-skill-output/ 目录或文件，系统会通过终端返回可复制的纯文本 Markdown 内容供你手动保存。)

普通 Flow Guide 字段含义

字段	含义
phase goal / `Now`	阶段目标 / 当前目标：本轮专注块要完成的事情。
`DoD`	完成后能被用户检查到的结果，例如“已有标题和三条草稿 bullet”。
`Next 2 minutes`	第一组启动动作，通常不需要继续思考就能执行。
actionable steps	可执行步骤：当前 session 的后续动作，不应膨胀成完整项目管理计划。
fallback / recovery notes	兜底 / 恢复说明：中断、卡住或时间不足时的恢复方式；只有需要时出现。

Study Guide 字段含义

字段	含义
`Session boundary`	用户选择的 10 / 25 / 45 分钟只限定本次执行范围，不限制完整学习材料。
learning goal	学习动机，例如备考、完成小测、项目实操、概念理解或快速概览。
micro-lecture / cheat sheet	当材料不足时提供的简短讲义或速查表；必须标明不是从用户材料中读取的内容。
study steps	按依赖顺序排列的学习步骤，避免先答题后阅读定义。
`Instruction`	这一小步具体要做什么。
`Where to work`	去哪里读、在哪里写答案，例如某页 PPT、某个标题、生成文件中的回答区。
`How to work`	用什么方式学习，例如 skim、locate、extract、explain、recall、solve。
`Answer area`	用户填写答案、概念卡、填空或 teach-back 的位置。
`Checkpoint`	判断这一小步是否完成的可勾选标准。
progress / mastery markers	进度条、A/B/C 掌握度或 checkbox，用于产生可见反馈。
deferred / next-session steps	超出当前 session boundary 的后续步骤，标记为下一轮处理。

学习任务的目标不是“多给问题”，而是让用户知道每一步在哪里做、怎么做、做到什么程度可以进入下一步。

其他 Renderer 产出物

Markdown 是默认兜底格式，但 router 可以根据任务形态、用户请求、时间和精力选择其他 renderer：

Renderer	产出形态	适用场景	限制
`render_html.md`	轻量静态 HTML	用户明确要求 HTML，或卡片、检查清单、状态面板比 Markdown 更低摩擦。	低能量时只能使用轻量静态 HTML；不能变成仪表盘或复杂应用。
`render_csv.md`	CSV 表格	提取表、清单盘点、对比表、检查清单、Bug 分诊列表或练习队列。	低能量时仅在表格结构明显有用时使用。
`render_python.md`	Python 脚手架或脚本	诊断脚本、提取辅助、数据转换或自动化草图。	低能量和短时间块禁用。
`render_jupyter.md`	Jupyter notebook 脚手架	需要 notebook 形态的学习、实验、分析或分步执行。	低能量禁用。
Markdown + Mermaid	Markdown 中的 Mermaid 代码块	用户明确要求 Mermaid、流程图、图表或依赖图。	不存在独立的 `render_mermaid.md`。

学习/复习任务即使选择了 HTML、CSV、Python 或 Jupyter，也不能丢失导航式学习指导。除非该非 Markdown 产物完整包含 Instruction、Where to work、How to work、Answer area 和 Checkpoint，否则仍需要 Markdown 配套指导文件。

项目设计架构与思想（Architecture）

本项目采用“路由层 - 认知模型层 - 渲染层”的模块化结构，将触发边界、任务思考方式和输出格式分离。

第一层：总线路由层（Router）

flow-skills/00_router.md 是运行协议入口。它负责：

graph TD
    UserReq["User Request: Enter Flow State"] --> Router("00_router.md: Intake & Routing")
    Router -->|Assigns Time/Energy| Models{"Cognitive Models"}
    Models -->|Diagnostic| Renderers["Renderers"]
    Models -->|Generative| Renderers
    Models -->|...| Renderers
    Renderers --> Card["Terminal Compact Card"]
    Renderers --> Guide["Local Markdown Guide"]

判断 Flow Skill 是否已经被显式触发；
在需要时执行两步 pre-router intake；
解析时间、精力、材料、学习目标和输出格式；
路由到合适的 cognitive model；
选择 renderer；
保持 compact terminal output 与 guidance file policy。

第二层：认知引擎层（Cognitive Models）

Model ID	认知模式	适用场景	核心约束
`generative`	生发型	空白页、起草、从零生成第一版	先产生小而粗糙的可见版本，不追求完美
`diagnostic`	诊断型	Bug、错误、阻塞、日志或失败排查	假设驱动，用最小可逆测试缩小问题
`extractive`	萃取型	文献、长文档、会议记录、材料整理	只从已有材料提取事实、约束和问题，不重新创作
`synthesizing`	统合型	多来源信息合并、决策、框架、brief	收敛为一个清晰结构，暴露冲突和缺口
`internalizing`	内化型	学习、复习、备考、概念理解	使用 active recall、teach-back、fill-in 和 mastery check
`reinforcing`	强化型	复盘、恢复中断、维护节奏、低能量推进	保护 momentum，给出最小可继续动作
`orchestrating`	统筹型	项目规划、依赖排序、里程碑设计	规划范围和顺序，不替代全局 router

第三层：渲染输出层（Renderers）

Renderer 将 cognitive model 的输出转化为用户可使用的格式：

render_markdown.md：默认 fallback，适合终端卡片、指导文件、学习指南。
render_html.md：仅在静态 HTML 明显降低摩擦时使用；low energy 下不得复杂化。
render_csv.md：适合结构化事实、清单或表格提取。
render_python.md：适合高/中能量下的脚本型产物；low energy 禁用。
render_jupyter.md：适合 notebook 型学习或实验产物；low energy 禁用。

Renderer 可以改变呈现方式，但不能改变 cognitive model 给出的语义、约束、DoD、next action、timebox、energy state 或执行权限。

Mermaid 与图表

Flow Skill 不提供独立的 render_mermaid.md。

Mermaid 是 Markdown renderer 的显式图表模式。当用户明确请求 Mermaid、流程图、图表或依赖图时，router 会设置 preferred_format: markdown，并设置非 none 的 diagram_request，随后 Markdown renderer 可以输出 Mermaid fenced code block。

如果用户没有明确请求 Mermaid 或图表，不应输出 Mermaid。

开发、测试与验证（Development & Evaluation）

静态结构验证

从项目根目录运行：

python scripts/validate_flow_skill.py

验证脚本会检查：

必需文件是否存在；
SKILL.md 与模块 frontmatter 是否完整；
cognitive model 和 renderer metadata 是否对齐；
router schema、diagram_request、intake 和 output skeleton 是否符合约束；
不存在 render_mermaid.md；
guidance file、study guide、navigable study guide 的关键规则是否覆盖；
eval schema 和关键断言是否存在。

结构化评估

代表性 eval 位于：

evals/evals.json

Eval 覆盖：

显式 flow 触发；
普通任务不触发；
low-energy session；
任务转 flow；
renderer 选择；
Mermaid / diagram 请求；
guidance file；
study guide file；
navigable study guide。

扩展新模块

新增 cognitive model 或 renderer 时，请先参照：

flow-skills/interfaces/module_contract_template.md

保持输入/输出字段、frontmatter、energy modes、renderer fallback 和语义边界一致。

打包说明（Packaging）

打包为 .skill artifact 时，应包含：

SKILL.md
README.md
flow-skills/
evals/
scripts/

打包前请运行：

python scripts/validate_flow_skill.py

具体 .skill 打包命令取决于目标 Claude Skill 工具链。

开源协议与致谢（License & Acknowledgements）

本项目基于 MIT License 开源。

感谢 Mihaly Csikszentmihalyi 教授提出的“心流”理论。Flow Skill 借鉴其关于清晰目标、挑战-技能平衡和即时反馈的思想，并将其转化为 Claude Skill 环境中的任务执行协议。

Back to top / 返回顶部

English

Flow Skill is a local modular Claude Skill for explicitly requested flow-state, deep-work, or focused execution sessions. It is not a generic planning generator. It turns a vague goal into a bounded session with compact terminal guidance and a reusable local Markdown guide.

This project is still in active development and testing. Feedback is welcome, especially on trigger behavior, generated guide quality, and real workflow fit.

Core Idea

Flow Skill maps three flow-friendly conditions into a Claude Skill workflow:

Clear goals: route the task into one current phase with Now, DoD, and Next 2 minutes.
Challenge-skill balance: adapt output complexity using fixed 10 / 25 / 45 minute session boundaries and Low / Medium / High energy states.
Immediate feedback: create a local guidance file under flow-skill-output/ when execution is allowed.

When It Triggers

Direct Invocation (Highly Recommended) To guarantee that Flow Skill is triggered, invoke it directly using the slash command in your terminal:

/flow-skill "my goal or task"
/flow-skill "Refactor these components, 25 minutes"

Natural Language Triggers Use this skill only when the user explicitly mentions 心流, flow, flow state, 进入心流, 深度工作状态, or asks to convert work into a focused execution/session/workflow format.

Examples:

"把这个任务转换成心流执行流程"
"Turn this into a flow state session"
"把这件事变成 25 分钟专注块"
"Help me turn this goal into a deep-work session"

When It Does Not Trigger

Flow Skill is not designed for ordinary debugging, planning, summarizing, extraction, or task decomposition unless the user explicitly requests to turn that work into a flow/deep-work session.

Examples that should not trigger:

"帮我修 bug"
"帮我规划项目"
"总结这份材料"

Artifacts

Flow Skill produces two layers of output: a compact terminal card for immediate action, and local files for reusable execution or study scaffolding.

Terminal Compact Card

Field	Meaning
`Now`	The current session phase, not the whole project plan.
`DoD`	Definition of Done: observable completion criteria for this session.
`Next 2 minutes`	The first physical actions the user can take without more planning.
`Generated file`	The local guide path, or `Not created` if file creation failed.
`How to use`	A short instruction for using the guide, DoD, checkboxes, or progress markers.
`Optional details`	Assumptions, risks, route details, snapshots, or recovery notes only when useful.

Default Markdown Guides

When execution is allowed, Flow Skill creates a reusable Markdown guidance file by default:

Ordinary sessions: flow-skill-output/flow-guide-YYYYMMDD-HHMM.md
Learning/review sessions: flow-skill-output/study-guide-YYYYMMDD-HHMM.md

If file creation fails (e.g., due to environment restrictions), the terminal output will state this clearly and provide copy-ready Markdown content as a fallback.

Flow Guide Fields

Field	Meaning
phase goal / `Now`	The current focus-block objective.
`DoD`	The observable result that proves the session is complete.
`Next 2 minutes`	The first startup actions.
actionable steps	The remaining actions for the current session, not a full project plan.
fallback / recovery notes	How to recover from interruption, stuckness, or insufficient time when relevant.

Study Guide Fields

Field	Meaning
`Session boundary`	The selected 10 / 25 / 45 minutes limit the current session, not the whole guide.
learning goal	The user's purpose, such as exam prep, quiz prep, practical use, project delivery, concept understanding, or overview.
micro-lecture / cheat sheet	A compact built-in note when source material is insufficient; it must be labeled as general rather than extracted from user materials.
study steps	Prerequisite-first learning steps.
`Instruction`	What to do in this step.
`Where to work`	Where to read and where to write, such as a slide, section, heading, file, or answer area.
`How to work`	The cognitive action, such as skim, locate, extract, explain, recall, or solve.
`Answer area`	The place for answers, concept cards, fill-ins, or teach-back notes.
`Checkpoint`	The observable completion check for this step.
progress / mastery markers	Visible progress feedback, such as checkboxes or A/B/C mastery markers.
deferred / next-session steps	Later steps outside the current session boundary.

Other Renderer Artifacts

Markdown is the fallback, but the router can choose other renderers based on task shape, user request, time, and energy:

Renderer	Artifact	Good For	Limits
`render_html.md`	Lightweight static HTML	A card, checklist, or status panel when it is lower friction than Markdown.	Low energy allows only lightweight static HTML, not dashboards or app-like layouts.
`render_csv.md`	CSV table	Extraction tables, inventories, comparisons, checklists, bug triage, or practice queues.	Low energy only when tabular structure clearly helps.
`render_python.md`	Python scaffold/script	Diagnostic scripts, extraction helpers, data transforms, or automation sketches.	Disabled for low energy and short timeboxes.
`render_jupyter.md`	Jupyter notebook scaffold	Notebook-shaped learning, experiments, analysis, or step-by-step execution.	Disabled for low energy.
Markdown + Mermaid	Mermaid fenced code block	Explicit Mermaid, flowchart, diagram, or dependency-graph requests.	There is no standalone `render_mermaid.md`.

For learning/review tasks, non-Markdown artifacts must not drop navigable study guidance. Unless the non-Markdown artifact fully includes Instruction, Where to work, How to work, Answer area, and Checkpoint, a Markdown companion guide is still required.

Recommended prompt:

I want to enter a flow state to study <topic/materials>. My goal is <exam prep / quiz prep / practical application / project delivery / conceptual understanding>. Please create an actionable study guide file.

Architecture

Flow Skill uses a router-model-renderer architecture:

graph TD
    UserReq["User Request: Enter Flow State"] --> Router("00_router.md: Intake & Routing")
    Router -->|Assigns Time/Energy| Models{"Cognitive Models"}
    Models -->|Diagnostic| Renderers["Renderers"]
    Models -->|Generative| Renderers
    Models -->|...| Renderers
    Renderers --> Card["Terminal Compact Card"]
    Renderers --> Guide["Local Markdown Guide"]

SKILL.md is the Claude Skill entrypoint.
flow-skills/00_router.md handles intake, routing, renderer selection, output skeleton, and guidance file policy.
flow-skills/cognitive_models/ contains seven task-specific cognitive models.
flow-skills/renderers/ turns approved model output into Markdown, HTML, CSV, Python, or Jupyter artifacts.
flow-skills/interfaces/module_contract_template.md defines shared module contracts.

Cognitive Models

Model ID	Use Case
`generative`	Blank-page drafting and first visible versions
`diagnostic`	Bugs, failures, errors, and blocked work
`extractive`	Pulling facts, constraints, decisions, and questions from materials
`synthesizing`	Combining multiple inputs into one plan, brief, or recommendation
`internalizing`	Learning, review, active recall, and teach-back
`reinforcing`	Restarting, consolidating, and protecting momentum
`orchestrating`	Planning dependencies, milestones, and scope

Validation

Run from the project root:

python scripts/validate_flow_skill.py

The validator checks required files, frontmatter, routing schema, renderer constraints, guidance file behavior, navigable study guide markers, Mermaid-as-Markdown behavior, and structured eval coverage.

Packaging

To package this as a .skill artifact, include the root SKILL.md and supporting files under flow-skills/, evals/, and scripts/. Do not add render_mermaid.md; Mermaid support intentionally stays inside Markdown.