ima copilot

Other Community

Skill notes

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: Installs ima-skill to Claude Code, Codex, and OpenClaw in a single command via the vercel-labs/skills open installer.

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.

What this skill does

Capability · Entry point · Detail Install upstream ima-skill to 3 agents · scripts/install_ima_skill.sh · See references/installation_flow.md Configure API credentials (XDG style) · Inline workflow below · See references/api_key_setup.md Diagnose and fix known upstream issues · scripts/diagnose.sh + workflow below · See references/known_issues.md Fan-out search with priority boosting · scripts/search_fanout.py · See references/search_best_practices.md

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: The script auto-detects which of the three target agents are installed on the user's machine.

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.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Other
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@daymade · no license declared
Token usage
Lean
Setup complexity
Manual integration
External API key
Required · Vendor-specific
Operating systems
macOS · Linux · Windows
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
  • Env read
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Step 1 — Run the read-only diagnosis

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

02
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

03
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.

04
Step 4 — Execute the chosen strategy

Every repair command in `references/known_issues.md` is written to be: Idempotent — rerunning after the fix is already applied does nothing harmful and prints a clear "already fixed" message. Backed up — the repair copies the original file to `/tmp/ima-copilot-backups/<timestamp>/<relative-path>` before modifying anything, then tells the user the backup location. Reversible — the user can restore from the backup with a single `cp` command shown at the end.

05
Step 5 — Re-run diagnose to confirm

After the repair, run `diagnose.sh` a second time and show the user the diff. The issue should flip from `⚠️` to `✅`. If it does not, stop and surface the raw before/after to the user instead of silently retrying — unexpected failures here usually mean upstream shipped an unforeseen change.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.