ima-skill 是腾讯IMA（ima.qq.com）官方OpenAPI的统一封装技能，提供笔记管理和知识库两大核心能力。该skill通过标准化的HTTP POST+JSON方式与官方API通信，所有请求仅发送至ima.qq.com域名，文件上传流程使用IMA API返回的短期临时凭证对接COS（*.myqcloud.com），用户的主凭证（Client ID/API Key）不会直接传输至COS端点。
核心用法：用户需先在 https://ima.qq.com/agent-interface 获取Client ID和API Key，通过环境变量或配置文件（~/.config/ima/）配置后，即可调用notes模块（搜索/创建/编辑/追加笔记）和knowledge-base模块（上传文件、添加网页、搜索知识库内容、关联笔记到知识库）。技能内置ima_api.cjs脚本统一处理API调用、错误分层处理（程序错误-100/更新检查-200/业务错误）及自动更新检测机制。
显著优点：官方原生API封装，功能完整覆盖IMA核心场景；凭证隔离设计明确，主凭证仅用于身份认证不进入文件上传链路；内置UTF-8编码强制校验（notes写入）和PowerShell 5.1环境检测，避免常见中文乱码陷阱；错误处理分层清晰，-200更新状态与业务错误分离。
潜在缺点/局限：需用户自行申请和管理API凭证，有一定使用门槛；不支持视频文件、Bilibili/YouTube链接、file://协议URL，需引导用户使用桌面客户端；PowerShell 5.1环境必须显式处理UTF-8字节数组，否则中文内容必乱码；涉及notes与knowledge-base交叉场景（如"查看知识库中的笔记原文"）需先后读取两个子模块SKILL.md，路由判断逻辑较复杂。
适合人群：已拥有IMA账号、需要自动化笔记/知识库管理的技术用户或效率工具集成者；需在AI Agent工作流中嵌入个人知识管理的开发者；熟悉API凭证配置、能接受命令行/脚本交互的中高级用户。
常规风险：凭证配置错误导致API调用失败（code -100）；非UTF-8内容写入notes导致不可逆乱码；PowerShell 5.1未做环境检测导致内容损坏；混淆"笔记内容操作"与"知识库条目操作"的模块边界导致路由错误。