Ima Skill

ima-skill

Unified IMA OpenAPI skill. Currently supports: notes, knowledge-base.

---

Step 1: 确定模块

IF 用户意图是笔记相关（搜索/浏览/创建/编辑笔记内容）

→ 加载 notes/SKILL.md

IF 用户意图是知识库相关（上传文件/添加链接/搜索知识库）

→ 加载 knowledge-base/SKILL.md

IF 用户意图同时涉及笔记和知识库

→ 必须先加载两个子模块，再按顺序操作

判断规则：

• 目标是笔记的内容（读/写/追加）→ notes
• 目标是知识库的条目（上传/添加/关联）→ knowledge-base
• 用户提到"知识库"只是描述笔记位置（如"知识库里的那篇笔记"）→ notes

易混淆场景：

• "帮我记一下"、"记录一下"（未指定已有笔记）→ 需要确认：创建新笔记还是追加到哪篇？
• "把这篇笔记添加到知识库" → notes 搜索获取 noteid → knowledge-base addknowledge
• "查看原文"（知识库中的笔记类型媒体）→ knowledge-base getmediainfo → notes getdoccontent

🔴 CHECKPOINT：确认模块选择正确

---

Step 2: 检查本地依赖与凭证

IMA skill 的 .cjs 脚本需要外部 Node.js 运行时。Node.js 不是 Codex 自带能力；调用 API 前先运行 node --version 或当前平台等价检查。若缺失，先安装 Node.js，或说明 IMA 脚本暂不可运行。

检查是否存在 ~/.config/ima/client_id 与 ~/.config/ima/api_key，或环境变量 IMA_OPENAPI_CLIENTID / IMA_OPENAPI_APIKEY。macOS/Linux 与 Windows PowerShell 的命令见 [../../references/platform-commands.md](../../references/platform-commands.md)。

IF 缺少凭证

→ 引导用户设置（二选一）：

方式 A — 配置文件（推荐）： → 按 [../../references/platform-commands.md](../../references/platform-commands.md) 的"IMA 凭证"写入 ~/.config/ima/。

方式 B — 环境变量： → 按当前平台设置 IMA_OPENAPI_CLIENTID 与 IMA_OPENAPI_APIKEY。

凭证优先级：环境变量 → 配置文件

---

Step 3: 调用 API

node /ima_api.cjs "openapi/list_docs" '{"limit":10}'

把 ` 换成当前 ima-skill` 目录的绝对路径。路径应从已加载的本 skill 文件位置解析，不要依赖任何 agent 平台的默认 skills 目录，也不要依赖特定 shell 的脚本路径变量。

IF 进程退出码非 0（脚本执行错误）

• stderr 是 JSON，读取其中 code 与 msg
• code -200：skill 需要更新，从 stdout 读取 instruction 引导用户更新后重试
• code -100：程序错误，直接将 msg 展示给用户

IF 返回 stdout（后端业务错误）

• code=0：成功，从 data 提取业务字段
• code≠0：直接将 msg 展示给用户

---

Step 4: 强制规则

每次操作前检查：

1. UTF-8 编码（仅 notes 写入）：调用 import_doc/append_doc 前，所有字符串字段必须验证为合法 UTF-8

• 详细转码方法见 [references/platform-specific-rules.md](references/platform-specific-rules.md)

1. 文件命名：上传文件时 title 必须等于 file_name（含扩展名），不要修改
2. 不支持的类型：视频、B站/YouTube URL、file:// URL → 直接拒绝，建议用 IMA 桌面客户端
3. 文件完整性：上传文件时保持原始内容，不做编码转换

IF 在 PowerShell 环境

→ 必须先检测版本。PS 5.1 会静默将 Body 转为 GBK 导致乱码 → 详细处理方法见 [references/platform-specific-rules.md](references/platform-specific-rules.md)

---

Step 5: 更新检查

ima_api 内置每天首次调用自动检查更新。

IF 返回 -200（skill 需要更新）

→ 从 stdout 读取更新上下文 JSON → 按 instruction 引导用户完成更新 → 重试原请求

IF 需要主动触发更新检查

node /ima_api.cjs "" '' '{}' --force-update-check

---

反模式

• ❌ 不要只加载一个子模块就开始跨模块操作 → 必须加载两个
• ❌ 不要在 notes 写入前跳过 UTF-8 校验 → 非法编码导致乱码且不可修复
• ❌ 不要修改上传文件的 filename → title 必须等于 file_name
• ❌ 不要在 PowerShell 5.1 下直接发请求 → 必须检测版本并用 UTF-8 字节数组模式
• ❌ 不要往 IMA 写入内容（用户说"入库"= 本地知识库，用 design-shi-wiki skill）

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: montewaltrip188-hash
• Source: montewaltrip188-hash/claudecode-wiki-skills
• License: MIT

Install and usage instructions live in the source repository linked above.