Back to search
claude-vision-skill
SkillWorks with Claude CodeGitHub
Use when the user shares, pastes, or references an image (local path or URL) and you need to describe, analyze, or recognize its content, especially when the current model cannot read images directly. Run the bundled vision.js helper to convert the image into text.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked yesterday
Badge for your README
Markdown
[](/listings/asuojun--claude-vision-skill)HTML
<a href="/listings/asuojun--claude-vision-skill"><img src="/api/listings/asuojun--claude-vision-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 65 lines
- ---
- name: claude-vision-skill
- description: Use when the user shares, pastes, or references an image (local path or URL) and you need to describe, analyze, or recognize its content, especially when the current model cannot read images directly. Run the bundled vision.js helper to convert the image into text.
- ---
- # Vision Helper
- The current model may not support native image input. This skill is a
- sidecar workflow: it sends the image to a separate vision model and returns
- text to the current model. It does not add native image input to the current
- model.
- When this skill is installed as a Claude Code skill, use the bundled script
- through `${CLAUDE_SKILL_DIR}` so the command works from personal, project, or
- plugin installations:
- ```bash
- node "${CLAUDE_SKILL_DIR}/vision.js" "<absolute image path>" "<prompt>"
- ```
- If the repository was installed using the project-root setup described in
- the README, use the copied script instead:
- ```bash
- node vision.js "<absolute image path>" "<prompt>"
- ```
- For an image URL:
- ```bash
- node "${CLAUDE_SKILL_DIR}/vision.js" --url "<image url>" "<prompt>"
- ```
- Use `node vision.js --url` instead when using the project-root setup.
- When the user pastes an image into the chat but no file path or URL is visible,
- do not pass the raw image to the text-only model. Read the image from the
- clipboard first:
- ```bash
- node "${CLAUDE_SKILL_DIR}/vision.js" --clipboard "<prompt>"
- ```
- Use `node vision.js --clipboard` instead when using the project-root setup.
- `--clipboard` reads the current image from the system clipboard (macOS uses a bundled Swift helper, Windows uses a bundled PowerShell script; the pasted image is usually still there). If it fails, ask the user to save the image to a file and provide the absolute path.
- Fallback rules (automatic):
- - If a local path is given but the file does not exist, vision.js automatically falls back to the clipboard.
- - If no image path or URL is given at all, vision.js automatically tries the clipboard.
- - Pass `--no-fallback` to disable this behavior and fail with an explicit error instead.
- Rules:
- - Use `${CLAUDE_SKILL_DIR}/vision.js` for a bundled skill installation, or the
- project-root `vision.js` for the manual setup. Never use a path tied to the
- maintainer's machine.
- - Use an absolute image path for local files, or `--url` for remote images.
- - Prefer `--clipboard` when the user pasted an image with no accessible path.
- - Pass the user's original question as the prompt instead of replacing it with
- a generic description request. Use Chinese for descriptions unless the user
- asks otherwise.
- - Configuration lives in `.env` next to `vision.js` (`DASHSCOPE_API_KEY`, `VISION_MODEL`, `DASHSCOPE_BASE_URL`). Never print or commit the API key.
- - If the API call fails, report the error to the user and ask them to check the key, model, or base URL.
README.md · README · 89 lines
- # Claude Vision Skill
- 让没有识图能力的模型获得识图能力——把图片发给有 vision 的模型,用文字描述回来。
- ---
- ## 如果你是 AI(Claude Code),请读这里
- 用户把这个链接发给你,是想让你帮他配置识图。先确认信息,再按场景执行。
- ### 先确认
- 问用户:
- 1. 想用哪个识图服务?
- - **推荐千问**(`qwen3.5-omni-plus` / `qwen-vl-max`):阿里云百炼,新用户 100 万 token 免费,约 0.02 元/次
- - 也可以用 OpenAI(`gpt-4o-mini`)或其他支持 OpenAI 兼容格式的 vision 模型
- 2. API Key 是什么?没申请的话引导去对应平台注册
- 3. (如果用非千问服务)API Base URL 是什么?
- ### 场景 A:用户要在普通 Claude Code 项目里用
- 1. 把这个仓库里的 `vision.js` 下载到项目根目录
- 2. 替换 `vision.js` 里的 `sk-xxx` → 用户的 Key,`xxx` → 模型名。如果用的不是千问,同步改 `BASE_URL`
- 3. 把 `CLAUDE.md` 的内容合并到项目的 `CLAUDE.md`(没有就新建)
- 4. 告诉用户:配置完成,以后直接发图片就行,AI 会自动识图
- ### 场景 B:用户要在 cyberboss 里用
- 1. 先执行场景 A 的所有步骤
- 2. 接着读这个仓库里的 `cyberboss-setup.md`,按它说的改 persona 和 `src/core/app.js`
- 3. 告诉用户:重启 cyberboss 后生效,微信里直接发图片就能识图
- ### 场景 C:用户只想了解这是什么
- 简要解释:
- - `vision.js` 是核心,读取图片 → base64 → 发给 vision 模型 API → 返回文字描述
- - 走 OpenAI 兼容格式,不绑定特定厂商
- - 推荐千问是因为有免费额度;有别的便宜 vision API 也能用
- - 配置好之后,用户直接发图片,AI 自动处理,无需手动打命令
- ---
- ## 如果你是人类,请读这里
- ### 这是什么
- 一个让 DeepSeek 等无 vision 能力的模型也能"看图"的脚本。配置好之后,直接发图片 AI 就会自动识别。
- ### 推荐识图服务
- | 服务 | 模型 | 备注 |
- |------|------|------|
- | **阿里云百炼(推荐)** | `qwen3.5-omni-plus` | 新用户 100 万 token 免费 |
- | 阿里云百炼 | `qwen-vl-max` | 同上 |
- | OpenAI | `gpt-4o-mini` | 需海外支付 |
- | 其他 | 任何 OpenAI 兼容格式 | 改 `BASE_URL` 和模型名即可 |
- ### 自动配置
- **方式一(推荐)**:先把仓库 clone 到本地,然后告诉 Claude Code 本地路径:
- ```
- git clone https://github.com/asuojun/claude-vision-skill.git
- ```
- 然后在 Claude Code 里说:
- > 读一下 claude-vision-skill/README.md,帮我配置识图
- **方式二**:直接发 GitHub 链接(DeepSeek 等第三方模型可能无法访问 GitHub):
- > 按 https://github.com/asuojun/claude-vision-skill 的 README 帮我配置识图
- AI 会问你用什么服务、Key 是什么,然后自动配好。
- ### 手动配置
- 1. 把 `vision.js` 拷到项目里
- 2. 打开 `vision.js`,填 API Key、模型名(如用非千问服务还需改 API 地址)
- 3. 把 `CLAUDE.md` 放到项目根目录
- ### 文件说明
- | 文件 | 用途 |
- |------|------|
- | `vision.js` | 核心脚本(Node),OpenAI 兼容格式,零依赖 |
- | `vision.py` | 核心脚本(Python),纯标准库零依赖,用法同 vision.js |
- | `CLAUDE.md` | 项目说明书,告诉 AI 何时用识图脚本 |
- | `cyberboss-setup.md` | cyberboss 自动配置指令 |
vision.js · Bundled script · 221 lines · 1 finding marked
- #!/usr/bin/env node
- /**
- * 独立识图脚本 — 调用千问 VL 模型,按量付费。
- *
- * 用法:
- * node vision.js <图片路径> [问题]
- * node vision.js --url <图片链接> [问题]
- * node vision.js --clipboard [问题]
- *
- * 依赖: 无(自带 .env 解析)
- * DASHSCOPE_API_KEY 环境变量 或 同目录 .env 文件
- */
- const fs = require("fs");
- const path = require("path");
- const https = require("https");
- const http = require("http");
- const os = require("os");
- const { execFileSync } = require("child_process");
- // 加载 .env(先找当前目录,再找脚本所在目录)——无外部依赖,拷到任何目录都能用
- // 若装了 dotenv 也用它读一遍当前目录的 .env(不覆盖已存在的环境变量)
- function loadDotenv(file) {
- try {
- for (const line of fs.readFileSync(file, "utf8").split("\n")) {
- const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
- if (m && !(m[1] in process.env)) process.env[m[1]] = m[2].replace(/^["']|["']$/g, "");
- Dismissed after review: Copies every environment variable, where API keys and tokens live, in a file that sends data
- Line 27 on GitHub
- }
- } catch (_) {}
- }
- try { require("dotenv").config(); } catch {}
- loadDotenv(path.resolve(__dirname, ".env"));
- const BASE_URL = process.env.DASHSCOPE_BASE_URL || "https://dashscope.aliyuncs.com/compatible-mode/v1";
- const API_KEY = process.env.DASHSCOPE_API_KEY || "";
- const MODEL = process.env.VISION_MODEL || "";
- function parseArgs() {
- const argv = process.argv.slice(2);
- let imageSource = "", prompt = "", isUrl = false, useClipboard = false, noFallback = false;
- for (let i = 0; i < argv.length; i++) {
- if (argv[i] === "--clipboard") {
- useClipboard = true;
- } else if (argv[i] === "--no-fallback") {
- noFallback = true;
- } else if (argv[i] === "--url" && argv[i + 1]) {
- isUrl = true;
- imageSource = argv[++i];
- } else if (useClipboard && !argv[i].startsWith("--")) {
- prompt = prompt ? prompt + " " + argv[i] : argv[i];
- } else if (!imageSource && !argv[i].startsWith("--")) {
- imageSource = argv[i];
- } else if (imageSource && !argv[i].startsWith("--")) {
- prompt = prompt ? prompt + " " + argv[i] : argv[i];
- }
- }
- if (/^https?:\/\//i.test(imageSource)) {
- isUrl = true;
- }
- if (!prompt) prompt = "请详细描述这张图片的内容。";
- return { imageSource, prompt, isUrl, useClipboard, noFallback };
- }
- function getClipboardReader() {
- if (process.platform === "darwin") {
- return (outPath) => {
- execFileSync("/usr/bin/swift", [path.join(__dirname, "clipboard.swift"), outPath], {
- stdio: "pipe",
- });
- return outPath;
- };
- }
- if (process.platform === "win32") {
- return (outPath) => {
- execFileSync(
- "powershell",
- [
- "-NoProfile",
- "-NonInteractive",
- "-Sta",
- "-ExecutionPolicy",
- "Bypass",
- "-File",
- path.join(__dirname, "clipboard.ps1"),
- "-OutFile",
- outPath,
- ],
- { stdio: "pipe", windowsHide: true },
- );
- return outPath;
- };
- }
- return null;
- }
- function readClipboardImage() {
- const reader = getClipboardReader();
- if (!reader) {
- throw new Error(
- `剪贴板读取暂不支持当前平台: ${process.platform}(目前支持 macOS / Windows)`,
- );
- }
- const outPath = path.join(os.tmpdir(), `vision-clipboard-${Date.now()}.png`);
- return reader(outPath);
- }
- function resolveImageUrl(source, isUrl) {
- if (isUrl) return source;
- const resolved = path.resolve(source);
- if (!fs.existsSync(resolved)) throw new Error(`文件不存在: ${resolved}`);
- const ext = path.extname(resolved).toLowerCase().replace(".", "");
- const mimeMap = { jpg: "jpeg", jpeg: "jpeg", png: "png", gif: "gif", webp: "webp", bmp: "bmp" };
- const data = fs.readFileSync(resolved);
- return `data:image/${mimeMap[ext] || "jpeg"};base64,${data.toString("base64")}`;
- }
- function request(payload) {
- const url = new URL(BASE_URL.replace(/\/?$/, "/") + "chat/completions");
- const body = JSON.stringify(payload);
- const transport = url.protocol === "https:" ? https : http;
- return new Promise((resolve, reject) => {
- const req = transport.request(url, {
- method: "POST",
- headers: {
- Authorization: `Bearer ${API_KEY}`,
- "Content-Type": "application/json",
- "Content-Length": Buffer.byteLength(body),
- },
- }, (res) => {
- let data = "";
- res.on("data", (c) => data += c);
- res.on("end", () => {
- if (res.statusCode >= 400) return reject(new Error(`API ${res.statusCode}: ${data.slice(0, 300)}`));
- try {
- resolve(JSON.parse(data)?.choices?.[0]?.message?.content || data);
- } catch { resolve(data); }
- });
- });
- req.on("error", reject);
- req.write(body);
- req.end();
- });
- }
- async function main() {
- const missing = [];
- if (!API_KEY) missing.push("DASHSCOPE_API_KEY");
- if (!MODEL) missing.push("VISION_MODEL");
- if (missing.length) {
- console.error(`请设置以下配置:${missing.join(", ")}(环境变量或 .env 文件)`);
- console.error("获取 Key: https://bailian.console.aliyun.com/");
- process.exit(1);
- }
- const { imageSource, prompt, isUrl, useClipboard, noFallback } = parseArgs();
- let source = imageSource;
- const tryClipboard = () => {
- try {
- source = readClipboardImage();
- console.error("(未提供可用图片路径,已自动回退读取系统剪贴板)");
- return true;
- } catch (err) {
- console.error("剪贴板读取失败:", err.message);
- return false;
- }
- };
- const showUsage = () => {
- console.error("用法: node vision.js <图片路径> [问题]");
- console.error(" node vision.js --url <图片链接> [问题]");
- console.error(" node vision.js --clipboard [问题]");
- };
- if (useClipboard) {
- if (imageSource || isUrl) {
- console.error("--clipboard 不能和图片路径或 --url 同时使用。");
- process.exit(1);
- }
- if (!tryClipboard()) process.exit(1);
- } else if (source && !isUrl) {
- const resolved = path.resolve(source);
- if (!fs.existsSync(resolved)) {
- if (noFallback) {
- console.error(`文件不存在: ${resolved}`);
- process.exit(1);
- }
- if (!tryClipboard()) process.exit(1);
- }
- } else if (!source) {
- if (noFallback) {
- showUsage();
- process.exit(1);
- }
- if (!tryClipboard()) process.exit(1);
- }
- if (!source) {
- showUsage();
- process.exit(1);
- }
- try {
- const imageUrl = resolveImageUrl(source, isUrl);
- const result = await request({
- model: MODEL,
- messages: [{ role: "user", content: [
- { type: "image_url", image_url: { url: imageUrl } },
- { type: "text", text: prompt },
- ]}],
- stream: false,
- max_tokens: 1024,
- });
- console.log(result);
- } catch (err) {
- console.error("识图失败:", err.message);
- process.exit(1);
- }
- }
- main();
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.