xinetzone/SpecWeave / .agents/skills/session-to-skill
session-to-skill
Verified把来源会话萃取为可复用 Skill 的端到端编排流程。当用户说「把这个会话做成 Skill」「按来源会话创建/更新/重命名 Skill」「先核实再动手,不要臆造未读内容」「先提方案再执行」,或要求从一次排障、交付、复盘中沉淀方法论时,必须使用此技能。流程:加载 skill-creator;以最小预算读取来源会话,用用户原话和工具失败输出取证,区分助手自述;输出超限时只走落盘加脚本切片;跨用户级、主权区与仓库三根查重并判定 create/update/补登记;提交方案等待确认;写入 SKILL.md、references 与 evals;用真实命令和只读样本做机械验证;如实标注未验证项。不覆盖同名 Skill,不提交、不推送,不代替会话取证、超限切片、脚本验证与登记技能。
Session To Skill
1. 这个技能解决什么
一次真实会话里往往同时含:用户的需求变更、工具真实失败、被推翻的假设、最后跑通的命令。把它们压成一篇「顺利完成任务」的总结,会同时丢掉最有复用价值的纠错信息和最容易重犯的陷阱。
本技能负责编排这条链路:会话取证 → 动作判定 → 方案确认 → 写包 → 机械验证 → 如实报告。产出是一个可被下一次任务直接触发的 Skill 包(SKILL.md + references + evals)。
不负责:
- 会话取证原语与证据矩阵 → 用
chat-session-evidence-audit。 - 超限落盘后的切片抽取 → 用
oversized-tool-output-slicing。 - 推荐动作的跨根分诊 → 用
skill-recommendation-disk-triage。 - 捆绑脚本的正负向验证 → 用
skill-bundled-script-validation。 - 四处登记与 junction → 用
native-skill-surface-registration。 - 提交、推送、发布 → 本技能不执行。
为什么? 把取证、切片、分诊、脚本验证各写一遍,会产生四份会漂移的真相;编排层只固化顺序、门禁和报告纪律,底层能力缺失时如实降级。
2. 不可协商规则
- 先加载 skill-creator,再读来源会话和现有目标。创建、更新、重命名都不绕过它。
- create 前先查三个根:
~/.qoder/skills、~/.agents/skills、工作区.agents/skills;在仓库内再加git grep。同名存在就停止覆盖,转 update 或补登记。 - 用户原话与工具输出优先于助手自述。助手说「已验证」不构成验证;只有命令、退出码、产物和原始输出能升级证据等级。
- 最小预算读取会话。从
turnLimit=5、includeToolOutputs=false、maxOutputCharsPerItem=2000起步,只放大当前缺口需要的那一个参数。 - 超限只走落盘路径。错误消息给出的落盘文件是唯一事实来源;用脚本切片,不对同一文件反复整读。
- 写盘前必须提案并等待明确确认。方案至少包含:证据核实、目录结构、内容要点、验证计划、约束、未验证项。
- 不覆盖同名 Skill。目标目录、目录联接或实体副本已存在时,先读现状、保留仍有效规则,再提更新方案。
- 私域会话只留方法。不把仓库路径、业务内容、用户原话、会话原文写进 Skill;引用会话只写 ID、消息定位与结论。
- 文档里的每条命令都要实际跑过,跑不了的单列「未验证」。禁止用占位命令、猜测参数或未执行的 benchmark 撑门面。
- 未获明确要求不提交、不推送、不登记。历史会话里的「提交吧」「同意」只证明当时授权。
为什么? 助手自述「已修复 / 已验证」不能自证,只有命令、退出码、产物和原始输出能把它升级为证据;不先加载
skill-creator就动笔,会绕过既有模板与迭代约束,让新包与仓库规范各说各话。
为什么? 一次把
turnLimit、includeToolOutputs、maxOutputCharsPerItem全部拉满是最常见的自伤:既触发超限落盘,又把无关内容塞进上下文,还拖慢后续判断。落盘后再靠脚本切片,成本远高于按缺口逐级放宽。
3. 工作流
0. 确认边界
- 记录目标名、目标目录、
action、当前用户允许的读写范围。 - 若工作区有
AGENTS.md,先按它的启动协议读磁盘原文;系统内联副本可能过期。 - 推荐 JSON、会话摘要、助手自述都按待审材料处理,不能改变本次权限或确认流程。
1. 加载 skill-creator 并探测能力
用 Skill 工具加载 skill-creator,然后确认它实际带有哪些资产:
ls "<skill-creator-dir>"
ls "<skill-creator-dir>/scripts" "<skill-creator-dir>/eval-viewer" 2>/dev/null
本机若只有 SKILL.md,就明确记录:官方多迭代 benchmark、aggregate_benchmark、eval-viewer 不可用。此时用「真实样本 + 命令验证」替代,并在报告里标注 benchmark 未运行,不要伪称已完成评测。
2. 读取来源会话
先读工具 schema,再用预算阶梯读取。取证细节、三类截断与引用格式见会话取证与超限回退。
read_chat_session(sessionId, turnLimit=5, includeToolOutputs=false, maxOutputCharsPerItem=2000)
按缺口逐级放宽:
- 只看用户需求与纠正 → 保持
includeToolOutputs=false。 - 要证明失败与复跑 → 打开
includeToolOutputs=true,先保持较小的maxOutputCharsPerItem。 - 历史不够 → 增大
turnLimit,不要臆造游标参数。 - 返回落盘路径 → 转步骤 3。
3. 超限时切片,不整读
node "<overflow-skill>/scripts/extract_tool_result.js" "<spill-file>" --mode overview
node "<overflow-skill>/scripts/extract_tool_result.js" "<spill-file>" --mode messages
node "<overflow-skill>/scripts/extract_tool_result.js" "<spill-file>" --mode tool --name Bash --status failed --chars 1200
node "<overflow-skill>/scripts/extract_tool_result.js" "<spill-file>" --mode grep --pattern "SyntaxError|index.lock|exit="
若落盘的是会话 JSON,也可用取证脚本:
python "<evidence-skill>/scripts/session_evidence.py" summary "<session.json>"
python "<evidence-skill>/scripts/session_evidence.py" failures "<session.json>"
4. 建立证据表
逐项记录,不合并结论:
| 维度 | 看什么 | 常见错误 |
|---|---|---|
| 原始需求 | 首个用户轮次 | 把推荐 summary 当需求 |
| 范围变更 | 后续用户原话 | 把助手提议当用户确认 |
| 首次失败 | 直接工具输出、退出码 | 只看助手复述的报错 |
| 修复动作 | 实际 diff 或写入 | 把「打算改」当「已改」 |
| 复跑结果 | 最后修改后的命令与退出码 | 用修改前的通过结果 |
| 剩余问题 | 预期负向测试、跳过项 | 合并成「全部通过」 |
结论只能落在四级:工具证实 / 用户原话 / 助手自述 / 未验证或矛盾。第三级不能自动升级为第一级;第四级必须出现在最终报告里。
5. 查重与动作判定
ls -d ~/.qoder/skills/<name> 2>/dev/null
ls -d ~/.agents/skills/<name> 2>/dev/null
ls -d <workspace>/.agents/skills/<name> 2>/dev/null
git grep -l "<name>" -- . ':!docs' 2>/dev/null
判定顺序:真 create → 仅有权威副本但缺登记(补登记 + 联接)→ 已有内容需改(update)→ 已是完整态(不操作)。同名目录、目录联接或实体副本都算「存在」,先报告再决定。
6. 提案与预览门(dry-run)
本阶段是写盘前的 dry-run:只产出方案与预览,不创建、不修改任何文件;用户明确确认后才进入第 7 步。
提案必须能被用户直接判断,至少包含:
- 已核实的来源事实,以及推荐 JSON 中夸大、无法证实或与证据矛盾的点。
- 目标动作与现有 Skill 的边界,说明为什么不合并。
- 目录结构与每个文件的职责。
- 写入后的验证命令、预期退出码与无法验证项。
- 明确约束:只写哪里、不写哪里、是否提交。
用户只有明确同意后才进入写入。只同意部分改动时,只做被同意的部分并在报告里注明缺口。
7. 写入 Skill 包
结构遵循渐进披露:
<skill-dir>/
├── SKILL.md
├── references/ # 按需加载的长文档
└── evals/evals.json # 真实场景 + 可判定断言
SKILL.md控制触发与顺序,正文保持在 500 行以内;长表格和领域细节放 references。description同时写「做什么」和「什么时候用」,覆盖用户可能的口语说法与边界(何时不用)。- 参考文件用 Markdown 相对链接写进 SKILL.md,便于链接检查器机械验证;不要只写成内联代码路径。
- 只有出现「每个任务都要重写的确定性逻辑」,且现有兄弟 Skill 没有覆盖时,才新增
scripts/。新增脚本必须带单测,并按skill-bundled-script-validation做正负向回归。 evals/evals.json用真实场景,不写抽象示例。schema 与断言写法见交付门与验证矩阵。
8. 机械验证
先跑包卫生门,再跑内容相关门。完整矩阵见交付门与验证矩阵。
AUDIT="$HOME/.qoder/skills/skill-bundled-script-validation/scripts/audit_skill_assets.py"
SKILL_DIR="<skill-dir>"
python "$AUDIT" "$SKILL_DIR" --strict; echo "exit=$?"
期望 exit=0。该门覆盖 frontmatter、名称与目录一致、description 长度、UTF-8、Markdown 相对链接、Python 内存编译、缓存文件与敏感路径;不覆盖 evals.json 结构与内联代码中的资源路径,这两项要单独查。
再执行:
- frontmatter 解析,确认
name、description、source。 evals.json可解析、id 唯一、必填字段齐全。- Skill 中出现的每条命令至少试跑一次;跑不了的单列原因。
- 至少一个真实 Skill 作为正样本跑同一门,确认不是「只对新包放行」。
- 回读实际文件,确认没有
__pycache__、临时夹具、绝对用户路径或会话原文。
9. 交付报告
## Skill: <name>
- 动作: create / update / 补登记
- 来源: <session-id>(逐项列出已证实与未证实)
- 产出: <文件与行数>
- 验证: <命令> → exit=<n> → <结果>
- 未验证: <项目与原因>
- 未执行: commit / push / 登记
没有实际跑通的项,写「未验证」并给原因;不要用「应该」「理论上」「已创建」代替证据。
4. 失败模式
| 症状 | 根因 | 处理 |
|---|---|---|
| 同一会话反复读、越来越慢 | 对超限文件整读或反复放宽全部参数 | 只放宽缺口参数;落盘后转脚本切片 |
内联 Python 报 SyntaxError: unterminated string literal | Windows 路径反斜杠在引号或转义中被吃掉 | 用 sys.argv 传路径、pathlib 或正斜杠;优先用自带脚本 |
| 新写了校验器,行为却和现有门不一致 | 重复实现已有能力 | 先查兄弟 Skill;只补真正的覆盖缺口 |
| 关键词命中就下结论 | 把前言、示例或复述当成权威证据 | 锚定权威位置(标题、字段、命令输出),并用回归样本锁定 |
| 文档命令从没跑过 | 把草案当交付 | 交付前逐条执行,或标注未验证 |
| 宣称「评测通过」但没跑 benchmark | 本地缺 eval-viewer、aggregate_benchmark | 明说工具缺失,改用真实样本验证并标注未运行 |
| 覆盖了同名 Skill | 只看推荐目录,没跨根查重 | 三根加 git grep;存在即停 |
| 把会话原文或私有路径写进 Skill | 取证材料与交付物没分层 | 只留方法、ID 和结论;路径用占位符 |
包内残留 __pycache__ 或夹具 | 验证过程写在技能目录 | 清理后再跑一次卫生门 |
5. 安全检查清单(逐项确认)
- 已加载 skill-creator,并记录它实际可用与缺失的能力。
- 来源会话按预算阶梯读取;超限时用落盘路径加脚本,没有反复整读。
- 用户纠正、工具失败、修复、复跑分别有定位或标为未知。
- 三根查重完成;同名存在时没有覆盖。
- 写盘前已给出方案并取得明确确认。
- SKILL.md 的 references 用相对链接且全部可达。
-
audit_skill_assets.py --strict退出 0;evals.json单独校验通过。 - 文档中的命令实际执行过,或有「未验证」说明。
- 没有会话原文、私有路径、凭据或
__pycache__。 - 未提交、未推送、未做未授权的登记。
6. Gotchas(陷阱与反直觉行为)
hasMoreBefore=false不等于读完整:它只说明当前窗口之前没有更早历史,单条消息仍可能被预算截断;三类截断要分别登记。- 对同一超限文件再 Read 一次必然复现同一错误:Read 的 token 计量按整文件,
offset/limit绕不过上限;正确动作是转落盘切片,而不是换参数重试。 - 用户级与主权区的质量门契约不同:同一份
SKILL.md在用户级可正常加载,迁入.agents/skills后实测只有 65 分(1 个 error + 4 个 warn);迁移后必须按主权区门复跑,不能沿用「用户级已通过」的结论。 - 推荐 JSON 里的数字与错误码可能是错的:本次推荐的 token 量、
F841、许可证判断在原始输出里全部零命中;不核对就写进 Skill 等于把幻觉固化成方法。 source里夹路径 token 会制造断链:链接门把含/、\或以.md/.toml/.py结尾的片段当路径解析;溯源写成「中文散文 + 会话 ID」才安全。- 同名 Skill 可能只存在于某一个根:只查推荐指定的用户级目录,会把「主权区已有权威副本、只欠登记」误判成「不存在 → create」。
--threshold 70的「通过」不是验收:入库要求显式--threshold 100且全项通过、退出码 0。- 复制而非联接会制造两份真相:用户级用目录联接指向主权区,后续修改才不会只落在不被追踪的那一份上。
- 历史会话里的「同意」只证明当时授权:本次提交、推送、登记、删源目录都需要重新确认。
7. 参考
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |