Workflow & Core Tools · daymade/claude-code-skills
ima-copilot
Installs, troubleshoots, and personalizes the official Tencent IMA skill (a wrapper layer that orchestrates upstream ima-skill, not a replacement). Use when the user mentions IMA, 腾讯 IMA, ima.qq.com, ima-skill, installing or configuring ima-skill, IMA API key / credentials, searching across IMA knowledge bases, 知识库搜索, 笔记搜索, fan-out search with preferred KBs / priority boosting, or wants to diagnose, repair, or personalize an ima-skill install. Also trigger on the missing-YAML-frontmatter bug in ima-skill submodule SKILL.md files and errors like "Skipped loading skill(s) due to invalid SKILL.md".
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
Operates as a "wrapper layer" rather than a fork: The directory contains no upstream ima-skill source code and only provides installation, diagnosis, repair, and search orchestration. Consequently, upstream updates are received cleanly without conflicts.
ima-copilot/SKILL.md
- **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.
What it actually does: Codifies "no vendoring, no pinning, and no silent upstream modifications" into a do-not-violate list within SKILL.md ('Architectural principles (do not violate)'). Fixes are delivered as runtime instructions as an architectural constraint rather than marketing wording—the directory strictly contains only 4 self-developed documents, 3 scripts, and 1 template.
Installation mechanics: Downloads the zip archive from the official IMA distribution domain → extracts to a /tmp staging directory → hands off to vercel-labs/skills npx CLI for distribution, with all steps being idempotent.
ima-copilot/scripts/install_ima_skill.sh
ZIP_URL="${BASE_URL}/ima-skills-${IMA_VERSION}.zip" ZIP_PATH="${STAGING_DIR}/ima-skills.zip" echo " Downloading ${ZIP_URL}" http_code=$(curl -sS -L --fail -o "$ZIP_PATH" -w "%{http_code}" "$ZIP_URL" || echo "000")
BASE_URL=https://app-dl.ima.qq.com/skills. Defaults to version 1.1.2, which can be overridden via IMA_VERSION or --version. The download only checks for HTTP 200 and file size >1000 bytes, with no checksum or signature verification.
Distribution decisions do not rely on programmatic probing of upstream zip structure: Prefers the conventional layout <staging>/ima-skill/SKILL.md, and only falls back to finding the shallowest SKILL.md recursively if the layout changes, avoiding misidentifying submodule files under notes/ and knowledge-base/.
ima-copilot/scripts/install_ima_skill.sh
SKILL_SRC="" if [ -f "$STAGING_DIR/ima-skill/SKILL.md" ]; then SKILL_SRC="$STAGING_DIR/ima-skill" else
Comments specify the rationale: The upstream 1.1.2 zip includes a SKILL.md at root, notes/, and knowledge-base/ (the root cause of ISSUE-001). A naive "first SKILL.md found" strategy would result in non-deterministic, incorrect installations.
Target agents are detected via directory existence (~/.claude, ~/.agents, openclaw commands) and installed only to detected agents; falls back to claude-code if none are detected.
ima-copilot/scripts/install_ima_skill.sh
AGENTS=() [ -d "$HOME/.claude" ] && AGENTS+=("claude-code") [ -d "$HOME/.agents" ] && AGENTS+=("codex") if [ -d "$HOME/.openclaw" ] || command -v openclaw >/dev/null 2>&1; then AGENTS+=("openclaw") fi
Detection serves as a proxy metric for "user has opted to use this agent"; comments explicitly state 'absence means skip silently rather than install anywhere they haven't opted in'.
Cross-agent sharing leverages the default symlink mode of vercel skills: A single npx call targets multiple -a options; the first successful installation becomes canonical, while the rest symlink to it, synchronizing repairs across all three runtimes.
ima-copilot/scripts/install_ima_skill.sh
if ! npx -y skills add "$SKILL_SRC" -g -y "${AGENT_FLAGS[@]}"; then
Documentation explicitly notes that --copy is omitted ('Notice what is **not** passed: `--copy`'). The installer's cleanup trap removes the /tmp staging directory, and inline comments explain that deletion will not break symlinks (the canonical path is decoupled from the staging source).
Credential management follows an XDG plaintext file approach with environment variable priority: Scripts first read env variables, then fall back to ~/.config/ima/{client_id,api_key}, failing with an error if both are missing.
ima-copilot/scripts/search_fanout.py
client_id = os.environ.get("IMA_OPENAPI_CLIENTID", "").strip() api_key = os.environ.get("IMA_OPENAPI_APIKEY", "").strip() config_dir = Path.home() / ".config" / "ima"
The diagnosis script follows the same sequence (CLIENT_ID="${IMA_OPENAPI_CLIENTID:-}" falling back to file reads with tr -d '\n' to trim newlines); credentials are sent to ima.qq.com via ima-openapi-clientid and ima-openapi-apikey headers.
Diagnostic scripts are strictly read-only: Prints item-by-item status with ✅/⚠️/❌ along with a summary, returning exit codes: 0 = all passed, 1 = requires manual intervention, 2 = diagnostic self-failure (missing network or required tools).
ima-copilot/scripts/diagnose.sh
# This script is strictly read-only. It will never modify, create, or delete # any file outside its own stdout. Safe to run as many times as you want.
Read-only enforcement: find_install inspects candidate paths for SKILL.md presence, reads the first line with head -n 1, and queries the liveness API once using curl—without any > redirections, sed -i, or chmod modifications.
Deduplicates symlink-shared paths: Normalizes paths across three agents using python3 os.path.realpath and scans each underlying physical directory only once to prevent duplicate issue reporting.
ima-copilot/scripts/diagnose.sh
canonical() { python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1" 2>/dev/null || echo "$1" }
Corresponds to SKILL.md 'diagnose.sh detects this sharing and dedupes its reports'; deduplication is achieved via SCANNED_REALS string matching.
ISSUE-001 detection uses a "tri-state state machine" rather than a boolean check: Distinguishes between unfixed (first line does not start with ---), Strategy A applied (renamed to MODULE.md), Strategy B applied (frontmatter added), along with a conflict state where both SKILL.md and MODULE.md coexist.
ima-copilot/scripts/diagnose.sh
if [ -f "$skill_md" ]; then local first_line first_line=$(head -n 1 "$skill_md" 2>/dev/null || echo "") if [ "$first_line" = "---" ]; then return 0 fi return 1 fi
Function comments specify return code semantics 0/1/2/3/4 (OK / broken / submodule absent / Strategy A applied / conflict), allowing differentiation between 'repair script was run' and 'repaired upstream'.
Fixes are delivered as documented shell commands to be executed by the agent only after explicit user consent rather than embedded in executable scripts: 'we ship instructions, not patches'.
ima-copilot/references/known_issues.md
4. **Do not** add the fix commands into any shipped script — keep them in this file so the agent reads and executes them at runtime under user consent. This preserves the contract: we ship instructions, not patches.
Operating disciplines: Prompting via AskUserQuestion is mandatory when multiple strategies exist; backups are made to /tmp/ima-copilot-backups/<timestamp>/ via cp before execution; all commands are idempotent (guarded by [ -f ]); and rollback cp commands are provided.
Fan-out search bypasses upstream API limitations: Because IMA OpenAPI lacks a cross-KB endpoint, the script enumerates all KBs via pagination, calls search_knowledge concurrently across each KB (default 12 workers), and sorts/groups results on the client side.
ima-copilot/scripts/search_fanout.py
with concurrent.futures.ThreadPoolExecutor(max_workers=args.workers) as pool:
Documentation puts three hard constraints up front (No cross-KB endpoint / No relevance score / Silent 100-hit truncation); client-side sorting only handles grouping and hit count ordering, explicitly stating that cross-KB relevance ranking is unsupported.
Detects silent 100-hit truncations via response heuristics: Considers a KB truncated and prints a distinct ⚠️ notice only if the hit count equals HARD_HIT_CAP (100) and the response contains neither is_end nor next_cursor.
ima-copilot/scripts/search_fanout.py
truncated = len(hits) >= HARD_HIT_CAP and not data.get("is_end") and not data.get("next_cursor")
Permission denials (code 220030 for read-only subscribed KBs) are bucketed separately into a trailing ℹ️ block without polluting valid hits—rank_groups categorizes results into four buckets: priority, others, denied, and empty.
Personalization is driven entirely by user-side configuration: Managed via priority_kbs, skip_kbs, and fanout_strategy in ~/.config/ima/copilot.json; absence of this file falls back to neutral defaults (fan-out all KBs, sort by hit count, no boosting).
ima-copilot/SKILL.md
The personalization file is **per-user** and private. This skill ships only a template — see `config-template/copilot.json.example`. A user with no config file gets a neutral default: fan out all accessible KBs, sort groups by hit count, no boosting.
The repository only provides an example template with placeholders (your-curated-kb-name / your-subset-kb-name), and SKILL.md explicitly forbids hardcoding user KB names.
2Core Capabilities
01One-click installation of upstream ima-skill to Claude Code / Codex / OpenClaw (auto-detection, silently skips uninstalled agents, shares a canonical copy via symlinks)
02Read-only health diagnostics: Checks installation presence (3 agents, 3 candidate paths), validates credential presence and live endpoint liveness, scans for ISSUE-001, and outputs clear semantic exit codes
03Credential configuration walkthrough: Ensures standard XDG layout (dir 700 / file 600) + printf writing + verifies connectivity by sending an empty query to search_knowledge_base expecting code:0
04Known-issues registry with dual repair strategies (Strategy A: rename to MODULE.md / Strategy B: inject frontmatter / skip without modifications), providing idempotent shell commands with rollback paths
05Personalized fan-out search: Pins results by priority_kbs order, sorts remaining by hit count descending (using KB name as a secondary key for deterministic reproducibility), and completely skips excluded KBs via skip_kbs
06Truncation and permission denial warnings: Surfaces dedicated ⚠️ warnings recommending narrower queries for KBs hitting the 100-hit cap; segregates 220030 subscription KBs into a dedicated ℹ️ block
07Dual text and JSON rendering: Outputs human-readable grouped format by default (🥇/📚 with snippets), and structured {priority, others, denied, skipped_by_config} JSON via --json for downstream pipelines
08Uninstallation and upgrade lifecycle: Documents vercel skills remove workflows and notes that repairs must be reapplied after Capability 1 upgrades (ephemeral repairs are by design, not a bug)
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | curl（下载官方 zip + 凭证 liveness 调用） |
| cli | unzip（解包官方发行 zip） |
| cli | npx（要求 Node.js 18+） |
| cli | python3（search_fanout.py 运行环境；diagnose.sh 用它做 realpath 规范化） |
| cli | sed / cp / mv / mktemp / head（修复命令链使用的系统工具，统一用 command 前缀绕过用户别名） |
| package | skills（vercel-labs/skills，npm 包名 skills；npx 按需现场拉取并执行） |
| network | 上游 ima-skill 官方发行包（zip） |
| api | IMA OpenAPI · search_knowledge_base（枚举 KB / 凭证 liveness） |
| api | IMA OpenAPI · search_knowledge（单库检索，扇出的基本调用） |
| network | 凭证发行页（用户手工创建 Client ID / API Key，非脚本请求） |
| network | 可达性探测/文档引用域（api_key_setup.md 建议用 curl 探 http 码） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Executes local script or command: bash scripts/install_ima_skill.sh: curl downloads official zip → unpacks via unzip into /tmp/ima-copilo
- 网络端点: Declares external network access: https://app-dl.ima.qq.com/skills/ima-skills-<version>.zip (curl downloads official distribution package; only validates
- 本地工作目录: File read/write and artifact output: /tmp/ima-copilot-staging/<ts>-<pid>/ (downloaded zip and extracted content; installer's cleanup() handled by
Audit Notes: Meets all three Level 4 criteria: (a) Plaintext credential reading - diagnose.sh and search_fanout.py read ~/.config/ima/client_id, ~/.config/ima/api_key (600), and IMA_OPENAPI_CLIENTID / IMA_OPENAPI_APIKEY, sending them as headers to ima.qq.com; (b) Remote package and unpinned dynamic execution - runs `npx -y skills add` (npm package skills, unpinned; latest=1.5.26 from vercel-labs/skills), and downloads zip archives from app-dl.ima.qq.com, validating only HTTP 200 and file size; (c) Controlled modification of upstream directories - repairs execute mv/sed on ~/.claude/skills/ima-skill/**, though safeguarded by timestamped backups, idempotency checks, and explicit user confirmation. It avoids a Red rating because there is no TLS downgrade, anti-scraping bypass, arbitrary code execution (no eval/exec/subprocess piping remote input), or covert exfiltration (credentials only sent to the official OpenAPI endpoint without telemetry). It exceeds Level 3 because plaintext credential ingestion and dynamic remote package execution surpass basic public API interactions. Note also references/api_key_setup.md warning: 'The IMA API currently does not scope credentials per-device — a leaked API key can be used from anywhere on the internet until it's rotated.'
5Second-Pass Verification
- [ok] 外部依赖调用点存在性（curl / unzip / npx / node 版本 / python3 / sed） — install_ima_skill.sh 对 curl/unzip/npx 做 `command -v` 前置检查、对 node 校验 `-lt 18`、用 `unzip -q -o` 解包、用 `npx -y skills add "$SKILL_SRC" -g -y ...` 分发；diagnose.sh 用 python3 打 realpath；known_issues.md 用 `command sed -i.bak`。逐条在源码内命中，无凭空依赖。
- [ok] npx 运行时依赖的真实身份与版本策略 — 实测 GET https://registry.npmjs.org/skills/latest 返回 name=skills、version=1.5.26、repository=git+https://github.com/vercel-labs/skills.git、description='The open agent skills ecosystem'，与脚本 `npx -y skills add` 及文档 [vercel-labs/skills] 指向一致；未 pin 版本，每次按需现拉。
- [discrepancy] SKILL.md 示例诊断输出 vs diagnose.sh 实际输出 — SKILL.md 示例写 `✅ upstream ima-skill installed (claude-code)`、`❌ upstream ima-skill NOT installed (openclaw)`；脚本实际打印 `✅ ima-skill installed (claude-code) at $CLAUDE_PATH`（带路径、无 upstream 前缀）与 `⚠️ ima-skill NOT installed (openclaw) — run install_ima_skill.sh`（warn 而非 fail，退出码经汇总后仍为 1）。示例仅示意，功能无差异，但照字面比对会对不上。
- [discrepancy] 备份路径描述 vs known_issues.md 实际命令 — SKILL.md 说修复会把原文件拷到 `/tmp/ima-copilot-backups/<timestamp>/<relative-path>`；实际命令是 `BACKUP="/tmp/ima-copilot-backups/$(date +%Y%m%d-%H%M%S)"` 后以扁平重命名保存（`$BACKUP/notes-SKILL.md`、`$BACKUP/knowledge-base-SKILL.md`），并不保留相对目录结构；回滚命令与之一致，功能成立但文档描述不准。
- [discrepancy] 『未探测到 agent 就跳过、不写用户未选择的路径』的表述 — SKILL.md 与 installation_flow.md 都强调未探测到的 agent 静默跳过；但脚本在『零 agent 探测到』时的实际兜底是 `echo " Defaulting to claude-code as the most common case."` 并继续安装到 claude-code。SKILL.md 的概述未点明这条例外（references 里写了），属概括与实现的轻微出入。
- [ok] diagnose.sh『严格只读』声明复核 — 全文复读：输出只用 echo/printf，读取只用 head -n 1、[ -f ] 探测、tr -d、curl 一次 POST 读响应、python3 打印 realpath；无 > 重定向、无 sed -i、无 chmod、无 rm、无 mkdir。修正结论：『never modify, create, or delete any file』成立。
- [ok] 凭证读取点与去向（是否外发第三方） — 只有 diagnose.sh 与 search_fanout.py 读 env/文件；请求头统一 ima-openapi-clientid / ima-openapi-apikey，目标域名仅 ima.qq.com。全目录 URL 扫描命中集合 = ima.qq.com（含 /openapi 与 /agent-interface）、app-dl.ima.qq.com、github.com/vercel-labs/skills（文档引用）+ npm registry（npx 隐式）；无第三方回调、无埋点、无硬编码密钥常量。
- [unlocatable] 站外 API 行为断言的可验证性（100 截断 / 220030 无权限 / 无跨库端点） — 『恰好 100 条即静默截断且无 is_end/next_cursor』『订阅型 KB 返回 code 220030』『无跨库端点』均为 IMA OpenAPI 的站外行为断言，仓库内无测试/fixture 可证；只能确认实现与断言自洽（HARD_HIT_CAP = 100、PERMISSION_DENIED_MARKER = "220030"、truncated 判定式）。要坐实需真实凭证实测，本侦查不硬写。
6Verdict & Scenarios
Best for: Best for: 1) Users of Tencent IMA (ima.qq.com) with OpenAPI credentials who switch between Claude Code, Codex, and OpenClaw—install once for multi-agent symlink sharing and repair once to fix all; 2) Users blocked by ima-skill submodule frontmatter parsing errors ('Skipped loading skill(s) due to invalid SKILL.md') seeking a safe, backed-up, and reversible fix; 3) Users with multiple KBs looking to boost priority KBs via priority_kbs and exclude KBs via skip_kbs; 4) Skill developers looking for a reference wrapper architecture pattern to fix upstream bugs without vendoring code.
Not for: Not suitable for: 1) Users without a Tencent IMA account or OpenAPI credentials—both secondary scripts strictly require credentials and exit with errors otherwise; 2) Users unwilling to let the agent read credentials from ~/.config/ima/ or modify installed skill directories; 3) Users expecting an integrated search backend or indexing engine—this is purely a client-side fan-out orchestrator without cross-KB relevance ranking, semantic deduplication, or chronological sorting; 4) Offline or air-gapped environments (requires app-dl.ima.qq.com, npm registry, and ima.qq.com OpenAPI access); 5) Users looking for a standalone replacement for ima-skill (this wrapper layer contains no upstream functionality implementations).
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload ima-copilot.tar.gz
sha256:
Option B · Copy Guide for Agent9677c96e7b3f34a4…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.