oh-my-pi manage_skill 工具完全指南在会话中直接创建、更新与删除托管技能【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本篇技术指南以 oh-my-picoding agentIDE 内嵌的编码智能体中的manage_skill内置工具为核心讲解如何利用它在运行时直接创建、更新和删除“托管技能”Managed Skill实现可复用的流程沉淀、调试配方与项目级工作流的自动固化。读完本文你将掌握manage_skill的触发条件、入参契约、文件布局与安全约束并能结合源码理解其背后的写入原子性、名称规范化与技能发现优先级机制。什么是托管技能Managed Skill在 oh-my-pi 中技能Skill是一份遵循SKILL.md约定的 Markdown 文档用于把可重复执行的过程固化为 Agent 可发现、可调用的能力。普通技能由用户手工编写并放置在用户技能目录中而托管技能则不同——它是由 Agent 在会话运行过程中自动生成或增强的SKILL.md存放于隔离目录~/.omp/agent/managed-skills与用户自撰技能所在的~/.omp/agent/skills完全分离。这一隔离设计是托管技能最重要的安全边界自动管理机制永远无法触碰用户自撰技能。从源码看所有托管技能写入都被限制在getManagedSkillsDir()即agent-dir/managed-skills之内该目录默认位于~/.omp/agent/managed-skills参见 managed-skills.ts。托管技能适用的典型场景包括安装/设置流程setup sequence把多步骤的环境初始化固化为可复用的技能调试配方debugging recipe沉淀排查特定类型问题的操作步骤项目专属工作流project-specific workflow记录当前代码库特有的构建、测试或发布流程。manage_skill工具本身正是托管技能体系的运行时入口。它的模型面提示词位于 prompts/tools/manage-skill.md完整参考文档见 docs/tools/manage_skill.md。工具注册与可见性何时可用manage_skill并不是默认开启的工具其可用性受以下条件约束实现见 manage-skill.ts依赖autolearn.enabled true默认false。ManageSkillTool.createIf(...)仅在session.settings.get(autolearn.enabled)为真时才返回工具实例该开关独立于memory.backend记忆后端配置。顶层会话自动注入在autolearn.enabled开启且任务深度为 0顶层会话时工具注册表会强制把manage_skill加入显式工具列表参见 tools/index.ts确保受限顶层会话也能暴露控制器提示词所指向的工具。子代理不自动获得子代理subagent不会自动发现或接收该工具只有当其 requested-tools / frontmatter 列表中显式包含manage_skill时才能使用。这是因为自动学习控制器只在顶层运行绝不静默扩大子代理的写能力工具白名单。工具元数据方面approval write属于写操作需要批准、strict true启用严格结构化输出、loadMode essential作为必备工具加载并保持顶层注册而非挂载在xd://协议之下。执行是单次完成的不会发出进度更新。入参契约action、name、description、bodymanage_skill接受四个字段完整 schema 见 manage-skill.ts字段类型必填说明actioncreate \| update \| delete是托管技能的三种变更操作namestring是kebab-case 的托管技能名descriptionstringcreate/update 必填一行描述用于技能发现bodystringcreate/update 必填SKILL.md的 Markdown 正文不得包含 frontmatter三种action的语义由模型提示词明确规定见 prompts/tools/manage-skill.mdaction: create— 创建新技能若同名技能已存在则失败action: update— 覆盖技能正文若技能不存在则失败action: delete— 删除技能若技能不存在则失败。在工具层的 schema 校验中create/update必须同时携带description与bodydelete仅需name。这一约束通过跨字段 narrow 校验在验证期强制执行而非推迟到执行期同时保持线协议为单一根对象以兼容严格结构化输出模式与 Anthropic 工具 schema 构建器。命名规则严格的 kebab-casename必须是 kebab-case即仅含小写字母、数字与连字符长度 1–64 个字符且以字母或数字开头。底层正则^[a-z0-9][a-z0-9-]{0,63}$在 managed-skills.ts 中定义sanitizeSkillName会先trim()并转小写再校验从而阻止..、斜杠、空名与大小写混入——确保任何名称都无法逃逸出managed-skills隔离目录路径穿越防护。命名示例如setup-dev-env、debug-bazel-build、release-checksum。描述与正文的净化规则描述净化sanitizeManagedDescription会剔除控制字符与格式字符\p{Cc}\p{Cf}、尖括号、防止system-directive//skills逃逸出系统提示词的技能列表、反引号与重复波浪线防 Markdown 围栏逃逸并折叠为单行。该净化在写入和读取两端都执行保证历史文件同样安全managed-skills.ts。正文要求body会被trim()且不能为空。不要在 body 中写 YAML frontmatter——工具会自动生成只含规范化name与净化后description的 frontmatter 块通过仓库的 YAML 助手序列化managed-skills.ts。操作流程从参数校验到技能热更新一次成功的manage_skill调用遵循如下内部流程对应 manage-skill.ts工具创建ManageSkillTool.createIf(...)在autolearn.enabled为真时暴露工具并捕获会话的可选refreshSkills回调。Schema 校验create/update必须同时提供description与bodydelete只需name。delete分支调用deleteManagedSkill(name)递归删除技能目录存在refreshSkills回调时刷新活动技能列表。create的名冲突预检create前先规范化名称并调用isNameClaimedByAuthoredSkill检查是否已有同名自撰技能占用——因为托管技能在发现中永远排在最后、自撰技能同名必胜被遮蔽的托管技能写出来也永远不会浮现因此工具选择前置拒绝而非上报虚假的 Created返回isError: true且details.shadowed true不写入任何文件。create/update执行调用writeManagedSkill(...)其内部完成名称规范化/校验、frontmatter 生成、同名写入的进程内串行化并把SKILL.md写入托管根目录。热更新成功写入/删除后若存在refreshSkills回调则刷新活动技能使交互会话立即发现变更。返回值约定三种操作的成功返回文本与 details 如下同样记录于 docs/tools/manage_skill.mddeleteDeleted managed skill name.details { action: delete, name }createCreated managed skill name (managed-skills/name/SKILL.md).details { action: create, name }updateUpdated managed skill name (managed-skills/name/SKILL.md).details { action: update, name }自撰技能遮蔽create 时isError: truedetails { action: create, name, shadowed: true }三种操作模式与底层原子性保障managed-skills.ts 对三种模式提供了不同的安全实现create独占创建使用fs.writeFile(file, content, { flag: wx })即O_CREAT|O_EXCL实现原子独占创建若文件已存在则直接抛EEXIST错误already exists. Use action update to change it.从根上关闭了“先检查后写入”的竞态窗口同时拒绝把内容写入符号链接目标。update先校验、后以已检查句柄覆盖update要求目标文件已存在且必须是普通单链接文件拒绝符号链接打开时用O_NOFOLLOW标志并拦截ELOOP、拒绝非普通文件、拒绝硬链接数大于 1 的文件防止覆盖可能同时指向用户自撰文件的 inode。实现先lstat校验再打开文件句柄后再次stat校验最后才truncate(0)writeFile覆盖——打开的是已校验的句柄路径在 lstat 与截断之间被替换也无法把写入重定向到符号链接或新硬链接目标managed-skills.ts。delete递归删除但拒绝符号链接目录delete通过fs.rm(dir, { recursive: true })删除整个技能目录但删除前会lstat检查目录本身是否为符号链接避免rm误删链接目标目录不存在时抛 does not exist 错误。同名单写操作的串行化writeManagedSkill与deleteManagedSkill内部通过 per-name 的 promise 链serializeSkillMutation实现进程内串行化同一规范化名称的并发变更按提交顺序依次执行不同名称仍可并行。这解决了同一回合内多个工具批量调用对同一技能并发读写例如 update 在 delete 中途观察到文件的问题跨进程竞态则不在处理范围内managed-skills.ts。大小与安全上限64000 字节硬顶托管技能并非无界写入最终生成的SKILL.md文件含 frontmatter 与描述有64,000 UTF-8 字节的硬性上限MAX_MANAGED_SKILL_BYTES见 managed-skills.ts。注意上限以 UTF-8 字节数而非 UTF-16 码元长度计算Buffer.byteLength(content, utf8)精确反映磁盘上的真实字节数超限抛Managed skill is bytes bytes; the limit is 64000.安全校验链完整覆盖三类路径风险托管根目录本身为符号链接→ 拒绝防止写入逃逸到自撰技能目录技能目录为符号链接→ 拒绝中间组件符号链接同样会造成路径逃逸SKILL.md 为符号链接/非普通文件/多硬链接→ 拒绝update 场景。技能发现中的优先级托管技能永远最后解析托管技能虽然在行为上“像普通技能一样被发现在未来会话中呈现”但其发现优先级有明确约束skills.ts托管技能使用 provider idomp-managed标记与其他来源区分发现时死排在最后dead-last遵循 first-wins 规则——同名的自撰技能总是优先托管技能发现是无条件的OMP 原生不受其他技能开关的 toggle 影响即使某个更高优先级的自撰技能被禁用托管技能也必须保持可见绝不遮蔽被启用的自撰技能磁盘上读到的名称会再次经过isValidManagedSkillName校验手工放置的SKILL.md若携带不安全名称不会被转义进系统提示词读取时的描述同样会经过sanitizeManagedDescription净化。因此一个重要的实践结论是update并不能绕过自撰技能优先级——若已存在同名自撰技能托管技能在发现中仍会被遮蔽。这也是create时前置拒绝同名自撰技能写法的根本原因。测试验证热注册与热注销的真实行为仓库测试对manage_skill的运行时行为做了端到端验证sdk-skills.test.ts会话内通过manage_skill创建名为runtime-managed-skill的技能后session.skills与getActiveSkills()都能立刻看到该技能且系统提示词中包含其名称——证明refreshSkills 热注册生效随后可用skill://runtime-managed-skill协议路径读取该技能内容调用delete后活动技能列表与系统提示词中均不再出现该技能再通过skill://读取会失败——证明删除同样即时生效。这一测试链路正是“管理操作 → 活动技能热更新 → 系统提示词/技能协议可感知”完整闭环的直接证据。常见错误速查错误场景错误信息节选触发原因非法名称Invalid skill name raw...名称不匹配[a-z0-9][a-z0-9-]{0,63}create/update 缺字段action requires both description and body.schema 校验拒绝描述净化后为空Managed skill name needs a non-empty description.描述全为空白/控制字符正文 trim 后为空Managed skill name needs a non-empty body.body 为空文件超限Managed skill is bytes bytes; the limit is 64000.最终文件超 64 KBcreate 已存在Managed skill name already exists. Use action update to change it.独占创建冲突update/delete 不存在Managed skill name does not exist.目标缺失自撰技能同名Cannot create managed skill ... shadowedisError: true名称被自撰技能占用安全风险路径root/dir/file 的 symlink、非普通文件、多硬链接错误目录或文件不符合安全模型总结manage_skill是 oh-my-pi 自动学习auto-learn体系的核心写入口它把技能固化从“离线手工编辑文件”升级为“Agent 在会话中直接编排”并借助~/.omp/agent/managed-skills隔离目录、独占创建、O_NOFOLLOW更新、符号链接拒绝、64000 字节硬顶与自撰技能优先级保护形成一套完整的安全边界。理解其入参契约与底层机制后你既可以用它沉淀可重复流程也能准确预判在何种条件下一次create/update/delete会成功、失败或被前置拒绝。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
oh-my-pi manage_skill 工具完全指南在会话中直接创建、更新与删除托管技能【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本篇技术指南以 oh-my-picoding agentIDE 内嵌的编码智能体中的manage_skill内置工具为核心讲解如何利用它在运行时直接创建、更新和删除“托管技能”Managed Skill实现可复用的流程沉淀、调试配方与项目级工作流的自动固化。读完本文你将掌握manage_skill的触发条件、入参契约、文件布局与安全约束并能结合源码理解其背后的写入原子性、名称规范化与技能发现优先级机制。什么是托管技能Managed Skill在 oh-my-pi 中技能Skill是一份遵循SKILL.md约定的 Markdown 文档用于把可重复执行的过程固化为 Agent 可发现、可调用的能力。普通技能由用户手工编写并放置在用户技能目录中而托管技能则不同——它是由 Agent 在会话运行过程中自动生成或增强的SKILL.md存放于隔离目录~/.omp/agent/managed-skills与用户自撰技能所在的~/.omp/agent/skills完全分离。这一隔离设计是托管技能最重要的安全边界自动管理机制永远无法触碰用户自撰技能。从源码看所有托管技能写入都被限制在getManagedSkillsDir()即agent-dir/managed-skills之内该目录默认位于~/.omp/agent/managed-skills参见 managed-skills.ts。托管技能适用的典型场景包括安装/设置流程setup sequence把多步骤的环境初始化固化为可复用的技能调试配方debugging recipe沉淀排查特定类型问题的操作步骤项目专属工作流project-specific workflow记录当前代码库特有的构建、测试或发布流程。manage_skill工具本身正是托管技能体系的运行时入口。它的模型面提示词位于 prompts/tools/manage-skill.md完整参考文档见 docs/tools/manage_skill.md。工具注册与可见性何时可用manage_skill并不是默认开启的工具其可用性受以下条件约束实现见 manage-skill.ts依赖autolearn.enabled true默认false。ManageSkillTool.createIf(...)仅在session.settings.get(autolearn.enabled)为真时才返回工具实例该开关独立于memory.backend记忆后端配置。顶层会话自动注入在autolearn.enabled开启且任务深度为 0顶层会话时工具注册表会强制把manage_skill加入显式工具列表参见 tools/index.ts确保受限顶层会话也能暴露控制器提示词所指向的工具。子代理不自动获得子代理subagent不会自动发现或接收该工具只有当其 requested-tools / frontmatter 列表中显式包含manage_skill时才能使用。这是因为自动学习控制器只在顶层运行绝不静默扩大子代理的写能力工具白名单。工具元数据方面approval write属于写操作需要批准、strict true启用严格结构化输出、loadMode essential作为必备工具加载并保持顶层注册而非挂载在xd://协议之下。执行是单次完成的不会发出进度更新。入参契约action、name、description、bodymanage_skill接受四个字段完整 schema 见 manage-skill.ts字段类型必填说明actioncreate \| update \| delete是托管技能的三种变更操作namestring是kebab-case 的托管技能名descriptionstringcreate/update 必填一行描述用于技能发现bodystringcreate/update 必填SKILL.md的 Markdown 正文不得包含 frontmatter三种action的语义由模型提示词明确规定见 prompts/tools/manage-skill.mdaction: create— 创建新技能若同名技能已存在则失败action: update— 覆盖技能正文若技能不存在则失败action: delete— 删除技能若技能不存在则失败。在工具层的 schema 校验中create/update必须同时携带description与bodydelete仅需name。这一约束通过跨字段 narrow 校验在验证期强制执行而非推迟到执行期同时保持线协议为单一根对象以兼容严格结构化输出模式与 Anthropic 工具 schema 构建器。命名规则严格的 kebab-casename必须是 kebab-case即仅含小写字母、数字与连字符长度 1–64 个字符且以字母或数字开头。底层正则^[a-z0-9][a-z0-9-]{0,63}$在 managed-skills.ts 中定义sanitizeSkillName会先trim()并转小写再校验从而阻止..、斜杠、空名与大小写混入——确保任何名称都无法逃逸出managed-skills隔离目录路径穿越防护。命名示例如setup-dev-env、debug-bazel-build、release-checksum。描述与正文的净化规则描述净化sanitizeManagedDescription会剔除控制字符与格式字符\p{Cc}\p{Cf}、尖括号、防止system-directive//skills逃逸出系统提示词的技能列表、反引号与重复波浪线防 Markdown 围栏逃逸并折叠为单行。该净化在写入和读取两端都执行保证历史文件同样安全managed-skills.ts。正文要求body会被trim()且不能为空。不要在 body 中写 YAML frontmatter——工具会自动生成只含规范化name与净化后description的 frontmatter 块通过仓库的 YAML 助手序列化managed-skills.ts。操作流程从参数校验到技能热更新一次成功的manage_skill调用遵循如下内部流程对应 manage-skill.ts工具创建ManageSkillTool.createIf(...)在autolearn.enabled为真时暴露工具并捕获会话的可选refreshSkills回调。Schema 校验create/update必须同时提供description与bodydelete只需name。delete分支调用deleteManagedSkill(name)递归删除技能目录存在refreshSkills回调时刷新活动技能列表。create的名冲突预检create前先规范化名称并调用isNameClaimedByAuthoredSkill检查是否已有同名自撰技能占用——因为托管技能在发现中永远排在最后、自撰技能同名必胜被遮蔽的托管技能写出来也永远不会浮现因此工具选择前置拒绝而非上报虚假的 Created返回isError: true且details.shadowed true不写入任何文件。create/update执行调用writeManagedSkill(...)其内部完成名称规范化/校验、frontmatter 生成、同名写入的进程内串行化并把SKILL.md写入托管根目录。热更新成功写入/删除后若存在refreshSkills回调则刷新活动技能使交互会话立即发现变更。返回值约定三种操作的成功返回文本与 details 如下同样记录于 docs/tools/manage_skill.mddeleteDeleted managed skill name.details { action: delete, name }createCreated managed skill name (managed-skills/name/SKILL.md).details { action: create, name }updateUpdated managed skill name (managed-skills/name/SKILL.md).details { action: update, name }自撰技能遮蔽create 时isError: truedetails { action: create, name, shadowed: true }三种操作模式与底层原子性保障managed-skills.ts 对三种模式提供了不同的安全实现create独占创建使用fs.writeFile(file, content, { flag: wx })即O_CREAT|O_EXCL实现原子独占创建若文件已存在则直接抛EEXIST错误already exists. Use action update to change it.从根上关闭了“先检查后写入”的竞态窗口同时拒绝把内容写入符号链接目标。update先校验、后以已检查句柄覆盖update要求目标文件已存在且必须是普通单链接文件拒绝符号链接打开时用O_NOFOLLOW标志并拦截ELOOP、拒绝非普通文件、拒绝硬链接数大于 1 的文件防止覆盖可能同时指向用户自撰文件的 inode。实现先lstat校验再打开文件句柄后再次stat校验最后才truncate(0)writeFile覆盖——打开的是已校验的句柄路径在 lstat 与截断之间被替换也无法把写入重定向到符号链接或新硬链接目标managed-skills.ts。delete递归删除但拒绝符号链接目录delete通过fs.rm(dir, { recursive: true })删除整个技能目录但删除前会lstat检查目录本身是否为符号链接避免rm误删链接目标目录不存在时抛 does not exist 错误。同名单写操作的串行化writeManagedSkill与deleteManagedSkill内部通过 per-name 的 promise 链serializeSkillMutation实现进程内串行化同一规范化名称的并发变更按提交顺序依次执行不同名称仍可并行。这解决了同一回合内多个工具批量调用对同一技能并发读写例如 update 在 delete 中途观察到文件的问题跨进程竞态则不在处理范围内managed-skills.ts。大小与安全上限64000 字节硬顶托管技能并非无界写入最终生成的SKILL.md文件含 frontmatter 与描述有64,000 UTF-8 字节的硬性上限MAX_MANAGED_SKILL_BYTES见 managed-skills.ts。注意上限以 UTF-8 字节数而非 UTF-16 码元长度计算Buffer.byteLength(content, utf8)精确反映磁盘上的真实字节数超限抛Managed skill is bytes bytes; the limit is 64000.安全校验链完整覆盖三类路径风险托管根目录本身为符号链接→ 拒绝防止写入逃逸到自撰技能目录技能目录为符号链接→ 拒绝中间组件符号链接同样会造成路径逃逸SKILL.md 为符号链接/非普通文件/多硬链接→ 拒绝update 场景。技能发现中的优先级托管技能永远最后解析托管技能虽然在行为上“像普通技能一样被发现在未来会话中呈现”但其发现优先级有明确约束skills.ts托管技能使用 provider idomp-managed标记与其他来源区分发现时死排在最后dead-last遵循 first-wins 规则——同名的自撰技能总是优先托管技能发现是无条件的OMP 原生不受其他技能开关的 toggle 影响即使某个更高优先级的自撰技能被禁用托管技能也必须保持可见绝不遮蔽被启用的自撰技能磁盘上读到的名称会再次经过isValidManagedSkillName校验手工放置的SKILL.md若携带不安全名称不会被转义进系统提示词读取时的描述同样会经过sanitizeManagedDescription净化。因此一个重要的实践结论是update并不能绕过自撰技能优先级——若已存在同名自撰技能托管技能在发现中仍会被遮蔽。这也是create时前置拒绝同名自撰技能写法的根本原因。测试验证热注册与热注销的真实行为仓库测试对manage_skill的运行时行为做了端到端验证sdk-skills.test.ts会话内通过manage_skill创建名为runtime-managed-skill的技能后session.skills与getActiveSkills()都能立刻看到该技能且系统提示词中包含其名称——证明refreshSkills 热注册生效随后可用skill://runtime-managed-skill协议路径读取该技能内容调用delete后活动技能列表与系统提示词中均不再出现该技能再通过skill://读取会失败——证明删除同样即时生效。这一测试链路正是“管理操作 → 活动技能热更新 → 系统提示词/技能协议可感知”完整闭环的直接证据。常见错误速查错误场景错误信息节选触发原因非法名称Invalid skill name raw...名称不匹配[a-z0-9][a-z0-9-]{0,63}create/update 缺字段action requires both description and body.schema 校验拒绝描述净化后为空Managed skill name needs a non-empty description.描述全为空白/控制字符正文 trim 后为空Managed skill name needs a non-empty body.body 为空文件超限Managed skill is bytes bytes; the limit is 64000.最终文件超 64 KBcreate 已存在Managed skill name already exists. Use action update to change it.独占创建冲突update/delete 不存在Managed skill name does not exist.目标缺失自撰技能同名Cannot create managed skill ... shadowedisError: true名称被自撰技能占用安全风险路径root/dir/file 的 symlink、非普通文件、多硬链接错误目录或文件不符合安全模型总结manage_skill是 oh-my-pi 自动学习auto-learn体系的核心写入口它把技能固化从“离线手工编辑文件”升级为“Agent 在会话中直接编排”并借助~/.omp/agent/managed-skills隔离目录、独占创建、O_NOFOLLOW更新、符号链接拒绝、64000 字节硬顶与自撰技能优先级保护形成一套完整的安全边界。理解其入参契约与底层机制后你既可以用它沉淀可重复流程也能准确预判在何种条件下一次create/update/delete会成功、失败或被前置拒绝。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
)
