本地技能文件管理器
目的
维护用户的个人本地技能文件,作为一个轻量级的、自改进的记忆系统。默认目标不是生成可投放市场的通用技能;而是保留可帮助此用户、此团队或此工作区在后续会话中复用的行为。一个良好的候选技能可能包含个人工作流偏好、项目约定、样式合约、工具选择或审查门禁,这些内容可能对其他用户无用,但只要对预期所有者可复用且经其批准即可。
此技能不依赖于项目特定代码、服务器、向量存储、数据库或存储布局。它仅操作普通的本地技能文件夹:
<skill-root>/
<skill-name>/
SKILL.md
agents/openai.yaml (可选)
scripts/ (可选)
references/ (可选)
assets/ (可选)
使用此技能来决定会话何时包含可复用的技能材料,查找是否已存在相似技能,然后丢弃、改进、合并或创建本地技能。模型应在出现信号时主动启动此检查;不应等待用户询问。检查必须保持轻量级和非阻塞性,除非用户明确要求专注于技能维护。
相关技能协调
此技能拥有生命周期决策权:何时提取、是否丢弃、是否改进或合并、以及写入位置。与已安装的邻近技能协调:
- 使用
skill-creator进行新技能结构、命名、资源放置、agents/openai.yaml和验证。 - 使用
skill-improvement或等效的改进指导进行现有技能迭代、测试提示、失败分析、触发描述调优以及修改前后对比。 - 使用
skill-finder、find-skills或等效的发现工具在创建重复技能之前搜索本地或外部技能生态系统。 - 仅将自我改进模式作为决策启发式借用:事件分类、去重、重复性、优先级、价值检查和晋升门禁。除非用户要求,否则不要采用其他技能的存储路径、守护进程假设或代码结构。
- 如果这些辅助技能不可用,应用下面的内置流程。不要因为缺少辅助技能而阻塞。
- 不要让辅助技能削弱提取边界:只应保存可复用的、有用户证据支持的能力变更。
安全与同意
本地技能可以影响未来的代理行为,并可能包含可执行脚本。将技能编辑视作持久的行为变更。
- 未经用户同意,不得安装、导入或启用第三方技能。
- 不得添加令人意外的能力、隐藏网络访问、凭证处理、数据窃取或破坏性命令。
- 如果技能添加了脚本或工具集成,使它们的目地在
SKILL.md中可见。 - 当编辑可能共享给团队的技能时,保留组织策略,并在更改安全敏感行为之前询问。
- 默认将每个候选技能标记为
personal;仅在证据支持更广泛受众时标记为team或public。 - 未经用户明确批准,不得发布、推荐为广泛可复用的技能,或移除用户特定技能的个人范围。
- 在首次在新本地约定中写入持久化的学习笔记或技能之前,告知用户将要写入的路径并请求批准。
- 不要在常规维护期间静默修改此
autoskill管理器本身。仅当用户明确要求改进此技能时才进行改进。
技能根目录
在写入任何内容之前,确定本地技能的位置。
- 首先使用用户明确提供的路径。
- 否则检查常用根目录,如
${CODEX_HOME}/skills、~/.codex/skills、./skills、.agents/skills以及任何包含*/SKILL.md的当前工作区技能目录。 - 如果恰好存在一个合理的根目录,则使用它。
- 如果存在多个合理的根目录且目标不明确,询问用户要维护哪个根目录。
- 绝不重新组织无关的技能根目录或编辑所选根目录之外的技能。
触发策略
使用三层触发策略:
- 静默扫描:在每个实质性用户轮次后,简要询问该轮次是否包含可复用的个人偏好、规则、纠正、工作流、失败或技能质量相关问题。
- 提取检查:当以下任一触发器被触发时,对经验进行分类,分配证据和价值,搜索相似技能,并测试其是否满足提取边界。
- 写入/更新:仅在候选技能通过边界、目标技能根目录明确且用户批准确切更改后,才编辑本地技能文件。
模型应主动发起扫描和提取检查。不要询问用户“我应该检查技能吗?”。仅当目标根目录不明确、编辑可能覆盖不确定的行为,或用户必须批准外部安装或敏感脚本时才提问。
候选生命周期
使生命周期与特定存储系统分离:观察信号,可选地要求用户选择候选标题/主题,草拟候选技能,通过模式去重,决定 discard/keep_note/improve/merge/create,展示完整的提案技能或差异,然后应用最小的已批准更改并验证。
通过任务族、触发器、工具、失败模式、输出合约和目标技能进行去重,而不是基于确切的措辞。不要为此技能创建私有数据库、守护进程、调度器或隐藏的后台存储。
标题选择门控
在完全提取之前,当可复用的主题不明确或存在多个合理技能时,展示 2-5 个简洁的可复用能力标题,附带一行证据理由,外加 none of these 和 custom topic。如果用户选择了一个标题或输入了一个主题,将其视作方向指导:针对该方向重新运行提取边界和相似技能搜索;如果失败则丢弃,或如果通过则展示完整的提案 SKILL.md/差异以供最终批准。如果用户选择了 none of these,则丢弃或保留一个非持久笔记;不写入文件。
语言一致性
对于新技能,以用户证据的主要语言撰写候选标题、提案 SKILL.md、agents/openai.yaml 和小型资源;中文输入产生中文技能,英文输入产生英文技能。对于更新或合并,保留目标技能的主要语言,除非用户明确要求翻译;如果混合证据导致语言歧义,在草拟前询问。不要默认将提取的技能内容转为英文。
后台执行
技能提取和维护不得阻塞用户的主要任务。
- 尽可能将提取检查、相似技能搜索、候选草拟和触发器评估准备视为后台维护工作。
- 后台工作可以准备候选技能、查找相似技能和草拟差异,但未经用户确认不得写入、更新、删除、安装或启用技能。
- 首先继续处理用户的主要请求;除非用户明确要求专注于技能维护,否则不要让用户等待技能提取。
- 仅在存在可操作的候选决策、提案文件差异或需要澄清/同意的问题时,才向用户呈现后台结果。
- 除非用户要求批量处理,否则每个活跃对话最多运行一个后台技能维护作业;对额外信号进行排队或合并。
- 不要在前台启动昂贵的搜索、广泛评估或大规模重写。先使用轻量级检查,然后将更深入的验证推迟到自然暂停或明确的维护阶段。
- 如果运行时环境无法实际运行后台工作,则通过将维护检查推迟到当前答案完成或下一个自然暂停后进行模拟。
- 绝不为了完成候选提取而阻塞用户请求的工作交付,除非请求的工作本身就是技能维护。
确认门控
在创建、更新、删除、导入、安装、启用或实质性重写任何技能文件之前,需要用户确认。先草拟,再询问:在任何标题/主题选择之后,永远不要问“我应该添加/更新技能吗?”,直到提案内容或变更已写出来供审查。
对于 create,在写入前展示:
- 提案技能名称和目标路径
- 目标受众:
personal、team或public,以及可移植性限制 - 候选技能通过可复用技能边界的原因
- 证据级别、重复性信号、优先级和价值信号
- 已检查的相似技能以及为何不是重复项
- 完整的提案
SKILL.md内容 - 完整的提案
agents/openai.yaml以及每个提案的脚本、参考或资产文本(如果这些文件足够小以便内联审查);对于大型资产,显示确切的文件列表、目的、来源以及生成的差异或清单
对于 improve 或 merge,在写入前展示:
- 确切的目标技能路径
- 决策类型:
improve或merge - 变更属于该现有技能的原因
- 证据级别、重复性信号、优先级和价值信号
- 完整的统一差异,或当统一差异不可用时,每个变更部分的完整前后文本
- 将被添加、修改、删除或保持不变的每个文件
- 批准后要运行的验证计划或命令
仅在展示完整的提案工件或差异后,才要求用户给出明确的 yes/no 批准。如果用户不批准,不要编辑技能;将候选技能报告为已推迟或已丢弃。
即时触发器
当以下任何情况发生时,立即运行提取检查,或如果用户正在等待主要任务,则在下一个自然暂停时运行:
- 用户以应该影响未来类似任务的方式纠正、拒绝或完善模型的方法。
- 用户给出了持久的偏好、输出合约、工作流、命名规则、工具规则或质量门禁。
- 命令、脚本、集成或工作流失败,且会话发现了可复用的修复方案。
- 代理重复了非平凡的设置、脚本编写、转换或验证工作,这些工作应成为可复用资源。
- 类似的本地技能触发不足、触发过度或产生了不完整的指导。
- 会话揭示了一个缺失的参考、模板、脚本或检查清单,这可以防止未来的重复工作。
- 用户使用了面向未来的语言,例如“将此作为技能记住”、“保存此工作流”、“更新本地技能”、“下次这样做”、“这是我的标准流程”或“从此对话创建技能”。
仍将提取视为检查,而非要求:通常不做技能更改是正确的结果。
当用户说规则是临时的、要求不记住它,或只需要一次性答案时,不要提取。
计划检查
使用计划检查来捕获任何单个轮次不明显的渐进式学习:
- 对话长度检查:自上次检查后,大约每 6 个实质性用户消息、12 个总轮次或 2-3 个不同的任务尝试后。
- 令牌/容量检查:在较长的新上下文块之后,尤其是当对话可能很快被总结或压缩时。
- 任务边界检查:当交付物完成、调试循环结束、计划被接受或用户切换到新任务时。
- 会话结束检查:在实质性会话的最终响应之前,审查是否有任何内容应被丢弃、改进、合并、创建或记录。
保持计划检查轻量级。它们通常应静默发生,仅当存在可操作的决策或需要澄清时才向用户呈现。
去抖与批处理
防止嘈杂的重复提取:
- 不要在一个会话中反复检查同一信号。
- 将多个弱信号批处理到任务边界或计划检查。
- 除非用户明确要求批量处理,否则每次检查最多创建一个或更新一个技能。
- 对于边界信号,优先选择
keep_note或discard,直到重复训练加强了证据。 - 如果候选技能接近但尚不够可复用,在完成笔记中记住理由,而不是创建技能。
- 将同时触发的触发器合并到一次后台维护操作中。
- 当多个候选技能竞争时,首先处理最高优先级的重复失败或用户确认的偏好。
经验分类
在更改技能之前,对会话经验进行分类。持久类别为 error、correction、best_practice、knowledge_gap 和 preference。one_off_result 表示会话产生了有用的工作,但未产生持久的过程变更。
只有持久类别可以成为技能变更,且仅在通过提取边界后。一次性结果不应被晋升。
价值与优先级门控
- 优先级
P0:防止不安全、破坏性、隐私敏感或反复失败的行为。 - 优先级
P1:防止重大的重复性错误、错过的触发器、糟糕的合并或昂贵的重复工作流。 - 优先级
P2:改进重复性任务族的质量、速度或清晰度。 - 优先级
P3:便利性或样式改进,证据有限。
根据持久价值而非新颖性进行晋升。价值必须是可解释的可靠性、安全性、速度、质量、一致性或减少重复工作。如果没有明确的价值维度,则丢弃或保留非持久笔记。
在改进现有技能时,一次更改一个行为杠杆:触发器措辞、工作流步骤、验证门禁、资源放置或安全约束。
晋升规则
不要将每个经验都变成技能编辑。谨慎晋升经验:
- 当用户明确表示规则应适用于下次时,立即晋升。
- 当纠正阻止了严重的重复性失败、不安全操作或破坏性工作流时,立即晋升。
- 当同一错误、纠正或最佳实践在多个类似任务中出现时,在重复后晋升。作为默认设置,在晋升前至少等待两次独立重复,除非安全或严重的重复性失败需要立即晋升。
结论
此技能管理个人本地技能文件,作为一个轻量级的、自改进的记忆系统,确保安全、用户同意和高效去重。它通过非阻塞后台检查、明确用户确认和严格的价值评估来平衡主动提取与用户自主性。