Ima Copilot

IMA Copilot

One-command installer, troubleshooter, and personalization layer for the official Tencent IMA skill.

Overview

The official Tencent IMA skill (ima-skill) exposes a powerful OpenAPI for notes and knowledge base operations, but its installation flow is designed for a specific proprietary agent and recent releases have shipped submodule files that fail strict SKILL.md loaders. IMA Copilot solves both problems:

1. Installs ima-skill to Claude Code, Codex, and OpenClaw in a single command via the vercel-labs/skills open installer.
2. Walks the user through API key setup with a live validation call.
3. Detects known upstream issues and — with explicit user consent — fixes them in place, without ever forking, vendoring, or mirroring any part of the upstream package.
4. Provides a fan-out search strategy that respects user-configured knowledge base priorities and boosts, with awareness of the 100-result per-KB truncation limit.

Architectural principles (do not violate)

This skill is a wrapper layer around ima-skill. The wrapper contract is non-negotiable:

• Never vendor upstream files. This skill directory does not contain any copy, fork, or excerpt of ima-skill's own content. When ima-skill ships a new release, users get the new release without any interference from this wrapper.
• Repairs happen at runtime, not at ship time. If an upstream bug needs patching, this skill carries the instructions for how to patch, not the patched files. Running a repair is idempotent: rerunning after an upstream update re-detects and re-fixes anything that came back.
• Always ask before touching upstream files. Modifying ~/.claude/skills/ima-skill/**, ~/.agents/skills/ima-skill/**, or any other upstream install directory requires explicit user consent via AskUserQuestion. No silent patching.
• Teach rather than hide. When a fix is applied, show the user exactly what changed and where the backup was saved. This is how users learn to maintain their own installs.

What this skill does

Routing

When this skill is triggered, classify the user's intent and jump to the corresponding capability:

When in doubt, start with Capability 3 (diagnose) — it surfaces exactly which capabilities are blocked and in what order.

Capability 1: Install upstream ima-skill

The installer downloads the latest official release from https://app-dl.ima.qq.com/skills/, stages it in a temp directory, and hands off to npx skills add <local-path> to distribute it across Claude Code, Codex, and OpenClaw.

To run it:

bash scripts/install_ima_skill.sh

The script auto-detects which of the three target agents are installed on the user's machine. For agents that are not present, it skips silently rather than installing anywhere the user hasn't opted in. For agents that are present, it installs globally (-g) in vercel skills' default symlink mode: the first detected agent's directory becomes the canonical copy, and the remaining agents are symlinked to it. This means a repair or an upgrade applied once propagates automatically to every agent — diagnose.sh detects this sharing and dedupes its reports so you don't see the same issue multiple times.

For a version override, detection logic, troubleshooting, and the full file-by-file layout produced by the installer, read references/installation_flow.md.

Capability 2: Configure API credentials

Credentials are stored in XDG style, decoupled from any agent's skill directory:

• ~/.config/ima/client_id (mode 600)
• ~/.config/ima/api_key (mode 600)
• ~/.config/ima/ (mode 700)

Environment variables IMA_OPENAPI_CLIENTID and IMA_OPENAPI_APIKEY act as fall-back overrides — the wrapper reads the environment first, then the config file.

Step through the setup with the user:

1. Open https://ima.qq.com/agent-interface and create a new Client ID and API Key.
2. Write both values into the XDG config path (or export the environment variables).
3. Make a single liveness call against https://ima.qq.com/openapi/wiki/v1/search_knowledge_base with {"query": "", "cursor": "", "limit": 1} to confirm the credentials are accepted — a code: 0, msg: success response means ready.

The full script and the exact request/response schema lives in references/api_key_setup.md.

Capability 3: Diagnose and fix known issues

This is the reason this skill exists. The upstream package has real bugs that break loading on certain agents, and the fixes are well-understood but need user consent to apply. The diagnose/repair workflow is the core contract of this skill.

Step 1 — Run the read-only diagnosis

bash scripts/diagnose.sh

diagnose.sh never modifies any file. It prints a structured report with one line per check:

✅ upstream ima-skill installed (claude-code)
✅ upstream ima-skill installed (codex)
❌ upstream ima-skill NOT installed (openclaw)
✅ API credentials valid (search_knowledge_base returned 12 KBs)
⚠️ ISSUE-001: notes/SKILL.md missing YAML frontmatter (claude-code)
⚠️ ISSUE-001: knowledge-base/SKILL.md missing YAML frontmatter (claude-code)
⚠️ ISSUE-001: notes/SKILL.md missing YAML frontmatter (codex)
⚠️ ISSUE-001: knowledge-base/SKILL.md missing YAML frontmatter (codex)

Step 2 — Parse the report and ask the user

For each ⚠️ or ❌ line, look up the issue in references/known_issues.md. That file is the source of truth for:

• What the issue is (symptom, root cause)
• Which repair strategies exist (A, B, skip)
• The exact shell commands for each strategy
• What files each strategy touches
• Why the upstream maintainer probably hasn't fixed it yet

Step 3 — Ask for explicit consent before touching upstream files

Use AskUserQuestion for every issue that has more than one repair strategy. Frame it plainly — the user may not know what "YAML frontmatter" means. Describe what the bug does to them in user terms ("loader skips two files silently, so note-search and knowledge-base-search don't actually work"), then describe each strategy in terms of the outcome, not the mechanism.

Never offer a single "just fix it" option when multiple strategies exist. The user's pick may legitimately differ based on factors the skill cannot observe — e.g., they might prefer Strategy B (minimal diff) if they plan to manually compare with upstream.