LifeOS SuggestSkills 技能缺口扫描实战：从工作历史与挫败信号中发现“该建什么技能“

LifeOS SuggestSkills 技能缺口扫描实战：从工作历史与挫败信号中发现"该建什么技能"

【免费下载链接】LifeOS⛰️ The Life Operating System — an intent engineering platform that moves you from your current state to your ideal state, in life and work.项目地址: https://gitcode.com/GitHub_Trending/pe/LifeOS

技能不是越多越好，而是越贴合你真实的工作痛点越好。本文围绕 LifeOS 仓库中的 SuggestSkills 技能 及其 Scan 工作流、CollectSignals.ts 采集工具，完整讲解一套"只读分析、只提议、永不自动创建"的技能缺口发现机制：它如何从你的工作会话历史与满意度挫败信号中聚类出反复出现的痛点，如何与已有技能做基于正文的覆盖去重，以及如何输出带证据的候选清单交给 CreateSkill 去构建。读完本文，你将掌握 SuggestSkills 的完整调用方式、底层信号采集原理（含全部 CLI 参数与语料 JSON 结构），以及"挫败感是头等信号"这一设计哲学在源码中的落地方式。

技能定位：只读、只提议、永不创建

SuggestSkills 在 SKILL.md 的 YAML frontmatter 中声明自己为version: 1.0.0，核心描述是：

Discover WHICH new skills you should create, from your own work history plus your satisfaction/frustration signals. Read-only and proposal-only.

它回答且只回答一个问题：基于你实际在做的事和你在哪里受挫，是否存在一个反复出现、但还没有对应技能的问题？它提议，你决策，CreateSkill构建。按设计，它没有任何创建或编辑技能的能力。

frontmatter 同时给出了精确的触发边界：

• USE WHEN：should I create a skill / what skills do I need / suggest skills / skill gap / based on my recent work / am I missing a skill / what should I build；
• NOT FOR：创建、校验、测试或优化单个技能——那是 CreateSkill 的职责。SuggestSkills 只决定"建什么（WHAT）"，不决定"怎么建（HOW）"。

执行前的定制化检查

SKILL.md 要求在真正执行前先检查用户定制目录：

~/.claude/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/SuggestSkills/

若该目录存在，加载并应用其中找到的PREFERENCES.md（默认时间窗口、存储路径、评审位置等定制项）；若不存在，则按技能默认值执行。这与 LifeOS 全局的技能定制约定一致——详见 SkillSystem.md 中关于技能结构与定制分层的说明：技能正文保持通用，用户级配置通过LIFEOS/USER/CUSTOMIZATIONS/SKILLS/<SkillName>/在运行时叠加。

执行时的双通道通知

每次执行工作流时，SKILL.md 要求同时做两件事（这也是 LifeOS 技能的统一惯例，CreateSkill 中同样有强制通知要求）：

1. 发送语音通知（本地通知服务，默认端口 31337）：

   curl -s -X POST http://localhost:31337/notify \ -H "Content-Type: application/json" \ -d '{"message": "Running WORKFLOWNAME in SuggestSkills"}' \ > /dev/null 2>&1 &

2. 输出文本通知：

   Running **WorkflowName** in **SuggestSkills**...

与 CreateSkill 的权限边界：为什么发现与创建必须分离

SuggestSkills 与 CreateSkill 是两个独立技能，这种分离本身就是权限设计：

Discovery is read-only; creation mutates. Keeping the two apart is the permission boundary that makes "never auto-create" real rather than a promise in prose: this skill cannot write a skill even if asked.

发现（discovery）是只读的，创建（creation）会变更系统状态。把两者拆开，使得"绝不自动创建"从一句口头承诺变成结构性的硬约束——SuggestSkills 即使被要求写技能也无从下手，因为它的工具链（CollectSignals.ts）只输出 JSON 语料，不写任何文件（源码注释明确写着 "Writes nothing"）。被接受的候选清单会作为独立的、人工批准的步骤转交 CreateSkill（CreateSkill 的完整生命周期 覆盖 scaffold、validate、canonicalize、test、improve 全流程）。

它存在的目的：击败两个盲区

SKILL.md 明确指出两个传统的"技能缺口检测"方法会漏掉的盲区：

1. 挫败感对"主题匹配"不可见。一个主题可能名义上被某个 build/test 技能覆盖了，但你仍会在其中反复撞同一堵墙。低评分与"regressed again"（又退步了）这类重复标记，才是技能缺失的最强信号——它们的权重应高于原始主题频率。
2. 纪律性缺口藏在"已覆盖"的主题之下。"App development"能映射到一个构建技能，但反复出现的痛点可能是一个无人认领的纪律（状态建模、错误处理、迁移安全），而那个构建技能从未真正处理它。所谓"覆盖"，指的是该纪律被真正处理，而不是主题共享一个关键词。

这两条直接决定了 Scan 工作流的去重与聚类方式（见下文 Step 2～4）：聚类时给挫败信号加权，去重时读覆盖单元的正文而非只看名字。

工作流路由与 Scan 五步法概览

SKILL.md 将 SuggestSkills 的全部执行入口收敛为一张路由表：

Workflow	Trigger	File
Scan	"what skills should I build"、"skill gap"、"suggest skills"、"am I missing a skill"	Workflows/Scan.md

Scan 的完整流程是五个步骤，SKILL.md 先给了浓缩版：

1. 确定性采集（Gather deterministically）：运行 Tools/CollectSignals.ts，产出一份规范化语料（近期会话、带情感倾向的低评分挫败记录、用于去重的技能/循环/工作流注册表，以及针对缺失或畸形存储的警告）。LLM 不参与采集，只对工具返回的结果做判断——因此两次运行看到的是同一份证据。
2. 按痛点聚类（Cluster by pain）：把语料归纳为反复出现的主题，同时携带两个数字：复现频率（多少次会话）与挫败强度（多少低评分 / 重复标记）。
3. 对照真实覆盖去重（Dedup against real coverage）：对每个候选，读取可能覆盖它的技能/循环/工作流的正文。名字匹配不等于覆盖，覆盖单元必须真正处理该失败类别。
4. 双通道独立校验，报告并集（Verify with two independent passes, report the UNION）：不要求两个通道一致才上报缺口——严格求交集恰恰会压制本技能要找的那些微妙的纪律性缺口。任一通道标记的缺口都要上报，并标注共识级别（both = 高置信，one = 需复核）。
5. 只提议，绝不创建（Propose, never create）：输出带证据的排序候选清单（会话数、挫败数、具体的反复失败模式），被接受的提议路由到 CreateSkill。所有写出的内容都要做脱敏（秘密、客户名、个人路径）。

接下来按 Scan.md 的细化步骤逐层展开。

Step 0：充分性检查（Sufficiency Check）

Scan.md 强调"语料即上下文"。如果工具报告评分存储（ratings store）缺失，那么本次运行的挫败信号不可用——必须如实写入报告，而不是把只有主题维度、没有挫败维度的结果包装成完整结论。

如果调用者问的是某个具体领域（如"我是不是缺少部署相关的东西？"），则将聚类范围收窄到该领域，并在报告里说明做了收窄。

Step 1：确定性采集（工具，而非散文）

Scan.md 给出的标准执行命令：

bun ~/.claude/skills/SuggestSkills/Tools/CollectSignals.ts --days 45 > /tmp/skill-scan-corpus.json

Scan.md 明确要求：不要手工 grep 存储来替代工具——手工采集会让运行不可复现，评估（eval）也就失去了意义。

意图到标志（Intent-to-flag）映射

工作流把用户的自然语言诉求映射到具体 CLI 参数：

用户说	Flag	效果
（默认）、"recently"、"lately"	--days 45	45 天窗口
"this quarter"、"last few months"	--days 90	更宽窗口；会话列表会明显变长
"all time"、"everything"	--days 3650	全量历史（上限被钳制在 3650）
"only the really bad ones"	--max-rating 2	收紧挫败截断线（默认 4）
"scan another install / another tree"	--root <dir>	在另一个根目录下重新解析所有存储
某个存储位于非标准位置	--ratings <file>--work <dir>--skills <dir>--loops <dir>	覆盖单个存储；显式路径无效会被报告，绝不静默回退到默认值

存储解析优先级：flag > env > 惯例默认值

每个存储的解析顺序固定为：显式 CLI 标志 > 环境变量 >--root下第一个存在的惯例默认路径。可用的环境变量有五个：

SKILLSCAN_MEMORY_ROOT SKILLSCAN_RATINGS_FILE SKILLSCAN_WORK_DIR SKILLSCAN_SKILLS_DIR SKILLSCAN_LOOPS_DIR

而各存储的惯例默认值（在--root下按顺序尝试）：

存储	默认候选路径
ratings	LIFEOS/MEMORY/LEARNING/SIGNALS/ratings.jsonl，再试裸的MEMORY/LEARNING/SIGNALS/ratings.jsonl
work	LIFEOS/MEMORY/WORK，再试MEMORY/WORK
skills	skills
loops	无默认，opt-in——若安装保留了循环目录，必须显式传--loops或设置环境变量

源码里两个细节值得注意：默认候选同时尝试LIFEOS/MEMORY/...与裸MEMORY/...，是因为不同安装的记忆树嵌套层级不同（见 CollectSignals.ts 第 72-78 行注释）；而显式传入一个不存在的路径会被记为 warning 并返回 null，绝不静默回退到默认值——这是"路径是发现的，不是假设的"原则的强制保障（源码resolveStore实现，CollectSignals.ts 第 79-99 行）。

语料 JSON 结构（stdout 契约）

CollectSignals.ts 的头部注释给出了完整的输出契约（第 21-33 行）：

{ "window": { "days": 45, "since": "2026-08-01" }, "sessions": [ { "slug": "2026-09-01-project-x", "mtime": "2026-09-01" } ], "frustrations": [ { "date": "2026-08-15", "rating": 2, "note": "migration regressed again" } ], "registries": [ { "kind": "skill|loop|workflow", "name": "...", "description": "..." } ], "warnings": [ "..." ], "missing": [ "ratings" ], "sources": { "root": "...", "ratings": "...", "work": "...", "skills": "...", "loops": "..." } }

工作流要求先读warnings和missing再进入分析——畸形行、超大文件、缺失存储都以非致命方式报告，但必须被看见。

确定性从何而来：源码级的 tie-breaking

"确定性"不是一句空话，而是可验证的实现细节：

• ratings 排序：按rating升序、date升序、note字典序完全打破平局（第 133 行）；
• sessions 排序：按mtime降序、slug字典序（第 148 行），且跳过.与_前缀的系统目录（第 142 行）；
• registries 排序：按kind、name字典序（第 200 行）。

对挫败记录还有两道防御：MAX_RATINGS_BYTES = 10_000_000（防止超大/FIFO 评分存储拖垮进程，第 37 行）与MAX_NOTE_CHARS = 500（笔记截断，第 38 行）；评分文件中无法解析的时间戳按"畸形行"而非"窗口外"处理，避免误判。注册表解析还支持 YAML frontmatter 中的折叠/块标量描述（description: >/|），并把每个技能目录下Workflows/*.md也注册为可复用覆盖单元（第 178-201 行）。

退出码约定：即使存储缺失也以 0 退出（全新安装是一份合法的空语料），仅在出现意外的内部错误时才非零退出。

完整 CLI 帮助文本

--help/-h会直接输出工具的自带帮助（第 203-222 行）：

Usage: bun CollectSignals.ts [--root <dir>] [--days <n>] [--max-rating <n>] [--ratings <file>] [--work <dir>] [--skills <dir>] [--loops <dir>] --root <dir> base for conventional store defaults (default: $HOME/.claude) --days <n> lookback window, 1-3650 (default: 45) --max-rating <n> highest rating still counted as frustration, 1-10 (default: 4) --ratings <file> ratings JSONL store --work <dir> work-session dirs --skills <dir> skills tree --loops <dir> loop catalog (opt-in; no default)

所有整数参数都经过严格的解析与钳制：非整数输入会被警告并回退默认值，越界值会被钳制到合法区间（intArg实现，第 62-70 行），绝不静默接受垃圾输入。

Step 2-3：按痛点聚类与三分类判定

采集到语料后，把sessions与frustrations合并归纳为反复出现的主题。每个主题携带两个数字：

• recurrence（复现）：涉及多少会话；
• friction（摩擦）：多少低评分 / 重复标记（如 "regressed again"）。

挫败信号的权重高于原始主题频率——这正是"挫败感是头等信号"的落地。

随后对每个聚类做三分类判定（Scan.md 定义）：

• BEHAVIOR-FEEDBACK——啰嗦、误读范围、提醒频率等行为问题。不是技能缺口，路由到 memory/preferences，排除。
• COVERED——某个现有技能/循环/工作流真正处理了这个纪律。确认方式：读覆盖单元的正文，而不是看名字；把具体失败类别映射到正文中的显式指导。如果正文没有处理该失败，就不算覆盖。
• GAP——既反复出现（按严重度加权；高严重度的重复痛点即使低于约 3 次也算）又无覆盖，包括"藏在某个 build/test 技能名义覆盖主题之下的纪律性缺口"。

Step 4：双通道独立校验，报告并集

用两个独立 agent 基于同一份语料对聚类分别分类。凡是任一通道标记为 GAP 的聚类都要上报，并按共识级别打标：both（高置信）或one（需复核）。

严格求交集会漏掉本技能存在的意义——那些微妙的纪律性缺口。SKILL.md 的表述是：Do not require both passes to agree before surfacing a gap (strict intersection suppresses exactly the subtle discipline gaps this exists to find).

Step 5：提议，绝不创建

输出排序候选清单，每个提议包含三要素：名称、一句话描述、证据（复现次数、挫败次数、它要防止的那个具体反复失败）。所有写入评审位置的内容必须脱敏：秘密、客户/项目名、个人路径。

被接受的提议作为独立的人工批准步骤转交 CreateSkill。本工作流不写任何技能文件。

标准输出模板

Scan.md 给出了可直接套用的报告格式：

## Skill-gap scan (last N days, M sessions; frustration store: present/absent) ### Gaps worth building - <Name> [confidence: both|one] — <desc>. Evidence: N sessions, K frustration signals, recurring failure = "<...>". → CreateSkill? ### Covered (verified against bodies, no action) - <theme> → <skill/loop/workflow> ### Behavior-feedback (route to memory, not a skill) - <theme> ### Recommendation <1-2 sentences; "nothing new" is valid ONLY when the frustration signals are also clean>

注意最后一条：只有当挫败信号也是干净的，"nothing new"才成立——主题覆盖干净但挫败信号脏，就是 SKILL.md Gotchas 里说的 FALSE NEGATIVE。

信号从哪来：ratings.jsonl 与满意度采集链路

SuggestSkills 读的挫败信号不是凭空存在的，它来自 LifeOS 的满意度采集钩子。在 SatisfactionCapture.hook.ts 中，评分的写入目标正是LIFEOS/MEMORY/LEARNING/SIGNALS/ratings.jsonl（源码第 81-82 行），每条记录形如：

{ "timestamp": "...", "rating": 3, "session_id": "...", "source": "explicit", "comment": "...", "response_preview": "..." }

这正对应 CollectSignals 解析的字段（rating、timestamp、sentiment_summary/comment）。钩子的主要信号路径包括：

• 显式评分快速路径：用户直接给 1-10 评分（支持裸数字、"8 nice"、"9/10"、英文数字词等形态，含对编号列表、中文计数等误判场景的防御）；
• 正面表扬快速路径："great job" 等短语直接折算为评分 8（source: "implicit"）；
• 显式纠错路径：命中 "that's wrong"、"didn't work" 等高精度短语时，把原话作为失败记录捕获——零推断、零 API 调用，避免污染 FAILURES 语料库；
• 低评分学习捕获：评分低于 5 时写入 LEARNING 目录，评分 ≤3 时额外经 FailureCapture.ts 生成完整上下文失败档案。

MemorySystem.md 从存储侧印证了这条链路：LEARNING/SIGNALS/ratings.jsonl是"所有用户满意度评分"的落点（第 443 行），SatisfactionCapture负责写入，LearningPatternSynthesis负责把评分聚合成模式报告（第 690 行）；日常可直接用tail ~/.claude/LIFEOS/MEMORY/LEARNING/SIGNALS/ratings.jsonl检查评分记录（第 764 行）。这套闭环让 SuggestSkills 的"挫败感加权"有了真实、可持续的数据来源，而不是靠会话主题推断。

典型使用示例

示例 1：例行缺口扫描

User: "What skills should I build based on my recent work?" → Invokes Scan workflow → Runs Tools/CollectSignals.ts over the last 45 days → Clusters sessions + low ratings, dedups against existing skills/workflows → Returns a ranked shortlist with evidence per proposal; nothing is created

示例 2：挫败驱动的扫描

User: "I keep hitting the same wall — am I missing a skill?" → Invokes Scan workflow with the frustration store as the lead signal → Surfaces discipline gaps hiding under topics that look covered → User accepts one proposal → handed to CreateSkill as a separate step

Gotchas：使用 SuggestSkills 的六条铁律

SKILL.md 的## Gotchas部分浓缩了最容易犯的六个错误，逐条展开如下：

1. 主题覆盖干净 + 挫败信号脏 = FALSE NEGATIVE。如果评分显示某个被你标记为"已覆盖"的领域仍有反复挫败，必须重新打开它——该主题下的纪律才是真正的缺口。这正是本技能被构建出来要修复的失败模式。
2. 复现按严重度加权，不是裸计数。三次琐碎会话不如一次漫长、痛苦、反复的迁移。一个高严重度、在少数会话中反复出现的痛点，即使低于某个任意阈值也够格。
3. 行为不是技能。"太啰嗦"、"误读范围"、"重复提醒"是导向/反馈问题，不是技能缺口。把它们分离出来路由到 memory/preferences，而不是 CreateSkill。
4. 采集必须是确定性的。如果发现自己在工作流里手工 grep 存储，改用工具——手工采集让运行不可复现，评估失去意义。
5. 路径是发现的，不是假设的。工具通过 flag/env/root 解析存储，跨安装可用；不要硬编码某个 home 目录。
6. 工作存储越大，会话列表越长，而不是分析更好。默认的 45 天窗口就是杠杆——扩大窗口要刻意为之，并预期聚类步骤承担相应成本。

从一次扫描到一次构建：SuggestSkills 与 CreateSkill 的衔接

一次完整的"技能缺口闭环"实际横跨两个技能：SuggestSkills 产出带证据的缺口清单（只读层），CreateSkill 负责实际构建（变更层）。CreateSkill 强制要求：创建任何技能前先读 SkillSystem.md 的结构规范（TitleCase 命名、扁平目录、SKILL.md 路由表、Gotchas 段），并遵守公开/私有技能划分（TitleCasevs_ALLCAPS）与SkillHygieneGate卫生门禁。把两个技能放在一起看，就能理解 SuggestSkills 为何刻意保持"无创建能力"：发现与构建的权限分离，才是整个技能治理体系不失控的根基。

小结

SuggestSkills 用一个只读工具（CollectSignals.ts）加一个五步工作流（Scan.md），把"我该建什么技能"从拍脑袋变成了可复现的、以证据驱动的分析：确定性采集保证两次运行看到同一份语料，挫败信号加权让"看起来覆盖了"的假象无处遁形，双通道并集上报守住纪律性缺口的召回率，而"只提议不创建"则让权限边界成为硬约束。配合 SatisfactionCapture.hook.ts 持续沉淀的 ratings.jsonl 信号，它构成了 LifeOS 技能生态中"先问 WHAT、再用 CreateSkill 解决 HOW"的完整一环。

【免费下载链接】LifeOS⛰️ The Life Operating System — an intent engineering platform that moves you from your current state to your ideal state, in life and work.项目地址: https://gitcode.com/GitHub_Trending/pe/LifeOS