Agent skill

Arkcli Understand

by volcengine in volcengine/ark-cli

arkcli +understand:基于 Responses API 的 12 个多模态专项理解配方,支持临时 API Key/Base URL/Endpoint 执行与无副作用 dry-run。用户只给 Endpoint 时先用 resources resolve;转写、抽取、字幕、定位等明确产出走本 skill,开放式对话走 +chat,生成走 +gen。

Apache-2.0Auto-check passedMedia & Creative

Install Arkcli Understand

skills CLI
$ npx skills add volcengine/ark-cli --skill arkcli-understand -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install volcengine/ark-cli arkcli-understand --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/volcengine/ark-cli.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/arkcli-understand .claude/skills/arkcli-understand && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
arkcli-understand
GitHub stars
140
Token cost
~1.7k tokens
SKILL.md length
531 words
Files
4 (incl. references)
Skills in repo
25
Repo updated
First seen
Licence
Apache-2.0

At a glance

arkcli +understand:基于 Responses API 的 12 个多模态专项理解配方,支持临时 API Key/Base URL/Endpoint 执行与无副作用 dry-run。用户只给 Endpoint 时先用 resources resolve;转写、抽取、字幕、定位等明确产出走本 skill,开放式对话走 +chat,生成走 +gen。

  • Works in 8 steps: 判断用户的理解任务命中哪个 sub-skill(见下表)。命中就显式带上… → 用户只给 ep-... → arkcli resources resolve… → 用户给了临时 Key/Base URL/Endpoint → 按共享… → …
  • Media & Creative work in your project
  • SKILL.md covers 核心概念, 快速决策(understand vs chat vs gen), Agent 快速执行顺序 and sub-skill 速查表(12 个 / 4 模态), plus 3 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Arkcli Understand is an agent skill from volcengine/ark-cli. arkcli +understand:基于 Responses API 的 12 个多模态专项理解配方,支持临时 API Key/Base URL/Endpoint 执行与无副作用 dry-run。用户只给 Endpoint 时先用 resources resolve;转写、抽取、字幕、定位等明确产出走本 skill,开放式对话走 +chat,生成走 +gen。

Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 4 other files, including reference files (for example `references/arkcli-understand.md`, `references/evals.md` and `references/sub-skills.md`).

It sits in Media & Creative. The repository describes itself as: The fastest way to put Volcengine Ark in your terminal and your AI agent — go from prompt to generated media, multimodal answer, or deployed endpoint in a single command, no API… The licence is Apache-2.0.

When your agent uses it

  • Media & Creative work in your project

Example prompts

  • “/arkcli-understand”

Workflow steps

8 steps, taken from the first numbered list in SKILL.md.

  1. 判断用户的理解任务命中哪个 sub-skill(见下表)。命中就显式带上 sub-skill 名,不要让它走自动路由去猜。
  2. 用户只给 ep-... → arkcli resources resolve --format json;只有用户任务属于明确理解产出,且 supported_workflows 包含 understand,才走本 skill。
  3. 用户给了临时 Key/Base URL/Endpoint → 按共享 execution-context 组合规则决定参数,不先切 profile。
  4. 没有完整 stateless 上下文时过认证闸门:不确定登录态先 arkcli auth status;鉴权失败按 ../arkcli-auth/references/auth-modes.md 的「API Key 模式的错误恢复」处理,不要原地重试。
  5. 备好输入:--input @(可多次)。本地文件用 @ 前缀;远程用 https:// / tos:// URL。
  6. 默认不传 --model:Platform Profile 会使用 Resources.Text.Default 中已部署的 ep-xxx,与 +chat 保持一致;Plan 类 Profile 才使用 sub-skill 的 recipe fallback…
  7. 需要逐段输出加 --stream;想微调任务指令用 --system-prompt-append "...",或 --system-prompt-override "..."。
  8. 跑完回到用户原始目标,不要停在中间产物上。

What it can do on your machine

Read from SKILL.md and the folder at commit fb5b7be. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Arkcli Understand loads about 1.7k tokens when it runs, and up to ~8.8k if it reads all its reference files. Until then it costs about 50 tokens; SKILL.md has 531 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~50
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~8.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from volcengine/ark-cli at commit fb5b7be, republished under its Apache-2.0 licence (© volcengine). 531 words, ~1,695 tokens.

Download SKILL.mdSave it as .claude/skills/arkcli-understand/SKILL.md (or your agent's skills folder). This skill also uses 3 other files; get the full folder from GitHub.
name
arkcli-understand
description
arkcli +understand:基于 Responses API 的 12 个多模态专项理解配方,支持临时 API Key/Base URL/Endpoint 执行与无副作用 dry-run。用户只给 Endpoint 时先用 resources resolve;转写、抽取、字幕、定位等明确产出走本 skill,开放式对话走 +chat,生成走 +gen。
version
1.1.0
metadata.cliHelp
arkcli +understand --help

arkcli +understand

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../arkcli-shared/SKILL.md,其中包含认证闸门、API Key 错误恢复、配置排查与命令选择顺序。 CRITICAL — 执行 +understand 之前,MUST 先用 Read 工具读取 references/arkcli-understand.md(命令/flag/返回值/错误)与 references/sub-skills.md(12 个 sub-skill 的用途与期望输出形态)。禁止凭印象拼命令。

核心概念

  • +understand 不是 12 套实现,而是 1 个引擎 + 一层语义:底层引擎就是 +chat 用的数据面 Responses API;每个 sub-skill 只是一条配方 {模态, fallback 模型, 内置 system prompt}。Platform Profile 省略 --model 时必须使用当前 Profile 的 Resources.Text.Default Endpoint;只有 Plan 类 Profile 才使用 recipe fallback 模型。
  • 命令形态:arkcli +understand <sub-skill> --input @file [prompt]。
    • args[0] 命中注册表(12 个之一)→ 当作显式 sub-skill,其余位置参数当 prompt 叠加在内置 prompt 之上。
    • args[0] 不命中 → 整段位置参数都当 prompt,服务端按首个 --input 的文件模态自动路由到该模态的默认 sub-skill。
  • 必须有 --input:sub-skill 是「对某个文件做理解」,没有 --input 会直接 missing_input 报错。纯 prompt 无法推导配方。
  • 返回值与 +chat 完全一致:arkcli 扁平 schema {id, model, content, reasoning_content, usage},不是 Responses 原生 output[].content[].text 嵌套。详见 references/arkcli-understand.md 的「返回值」段。
  • 多模态上传:image/video/doc 由 SDK file:// preprocessor 自动走 Files API;audio 是特例——内联为 base64 data URL,上限 25MB。详见 reference。
  • 用户临时提供 --api-key / --base-url / Endpoint 时,MUST 读取 ../arkcli-shared/references/execution-context.md。不要根据 Key 文本或 Endpoint 名称猜数据面/工作流。
  • --dry-run 只在本地解析配方、当前 Profile 已持久化的默认 Endpoint、显式模型和输入引用,输出统一 preview.v1;不读取在线 Endpoint/模型元数据、不上传文件、不调用 Responses API、不产生模型用量、不创建 response id 或持久化响应。在线才能补齐的值必须标为 unresolved,不能把预览当服务端 validation。

快速决策(understand vs chat vs gen)

用户意图走哪个
有明确产出形态的多模态理解任务(转写 / 翻译 / 字幕 / 框选定位 / GUI 操作 / 字段抽取 / 分章节总结 / 多说话人 / 会议纪要)+understand(命中某个 sub-skill)
开放式带图/视频对话、追问、推理、需要多轮接续(--store/--previous-response-id)、需要 tools(web_search/function)或 --text-format json_schema 严格 JSON../arkcli-chat/SKILL.md
生成图片 / 视频(不是理解已有素材)../arkcli-gen/SKILL.md

一句话判据:任务能映射到下面某个 sub-skill 名 → 用 +understand;否则开放对话用 +chat,生成用 +gen。

Agent 快速执行顺序

  1. 判断用户的理解任务命中哪个 sub-skill(见下表)。命中就显式带上 sub-skill 名,不要让它走自动路由去猜。
  2. 用户只给 ep-... → arkcli resources resolve <ep-id> --format json;只有用户任务属于明确理解产出,且 supported_workflows 包含 understand,才走本 skill。
  3. 用户给了临时 Key/Base URL/Endpoint → 按共享 execution-context 组合规则决定参数,不先切 profile。
  4. 没有完整 stateless 上下文时过认证闸门:不确定登录态先 arkcli auth status;鉴权失败按 ../arkcli-auth/references/auth-modes.md 的「API Key 模式的错误恢复」处理,不要原地重试。
  5. 备好输入:--input @<file>(可多次)。本地文件用 @ 前缀;远程用 https:// / tos:// URL。
  6. 默认不传 --model:Platform Profile 会使用 Resources.Text.Default 中已部署的 ep-xxx,与 +chat 保持一致;Plan 类 Profile 才使用 sub-skill 的 recipe fallback 模型。只有用户明确指定其他资源时才传完整版本化 ID 或 ep-xxx。
  7. 需要逐段输出加 --stream;想微调任务指令用 --system-prompt-append "...",或 --system-prompt-override "..."。
  8. 跑完回到用户原始目标,不要停在中间产物上。

sub-skill 速查表(12 个 / 4 模态)

下表是 Plan 类 Profile 使用的 recipe fallback 模型。Platform Profile 不使用这些裸模型名,而是使用当前 Profile 的 Resources.Text.Default Endpoint。确需覆盖时见上文执行顺序。

sub-skill模态Plan recipe fallback 模型一句话用途
image-captionimagedoubao-seed-1-6单图/多图描述、OCR(保留原文,不意译)
image-groundingimagedoubao-seed-1-6视觉定位:输出目标 bbox (x1,y1,x2,y2) + confidence
image-guiimagedoubao-seed-1-6GUI 截图 → 可执行操作序列(12 类操作 JSON 数组)
doc-extractfiledoubao-seed-1-6PDF/文档按 schema 抽取结构化 JSON(缺失填 null,保留 page)
video-summaryvideodoubao-seed-1-6视频总结:overall / segment / chapter + 关键时间点
video-qavideodoubao-seed-1-6视频问答:结合画面+音频+时间轴精准回答
vauvideodoubao-seed-2-0-lite音视频联合理解:分析视频内声音元素,出音频分析报告
asraudiodoubao-seed-2-0-lite语音转写:仅输出纯文本,无任何前后缀/格式
asr-alignaudiodoubao-seed-2-0-lite字幕打轴:默认 SRT 格式(序号+起止时间+文本)
asr-speakersaudiodoubao-seed-2-0-lite多说话人转写:标 [spk0] / [spk1] ...
astaudiodoubao-seed-2-0-lite语音翻译:把音频里的话译成文本
meeting-minutesaudiodoubao-seed-2-0-lite会议纪要:结构化 markdown(主题/参会人/要点/决议/待跟进)

逐条的期望输出形态与示例命令见 references/sub-skills.md。

Show full SKILL.md (179 more words)Show less

省略 sub-skill 时的自动路由

args[0] 不命中注册表时,按首个 --input 的文件扩展名推断模态并兜底到该模态的默认 sub-skill:

推断模态兜底 sub-skill
image(.jpg/.png/.webp/...)image-caption
video(.mp4/.mov/...)video-qa
audio(.mp3/.wav/.m4a/...)asr
file(其他扩展名)doc-extract
  • 没有 --input 时无法自动路由(纯 prompt 推不出配方)→ 报 missing_sub_skill。
  • 目前只按文件模态兜底,不做 prompt 关键词级路由(例如说「框出」不会自动选 image-grounding)。Agent 想要非默认 sub-skill(如 grounding / gui / summary / 字幕 / 翻译)就显式写出 sub-skill 名,别依赖自动路由。

命令一览

命令说明
arkcli +understand image-caption --input @photo.jpg "描述这张图"图片描述
arkcli +understand image-caption --input @doc.png "OCR,原样保留文字"OCR
arkcli +understand image-grounding --input @scene.jpg "框出所有红色car"视觉定位 bbox
arkcli +understand doc-extract --input @invoice.pdf "抽取 发票号/金额/日期"文档字段抽取
arkcli +understand video-summary --input @clip.mp4 "按 chapter 总结"视频分章节总结
arkcli +understand video-qa --input @clip.mp4 "视频里出现了几辆车?"视频问答
arkcli +understand asr --input @speech.mp3语音转写(无需 prompt)
arkcli +understand asr-align --input @speech.mp3生成 SRT 字幕
arkcli +understand asr-speakers --input @meeting.wav多说话人转写
arkcli +understand ast --input @speech.m4a "译成英文"语音翻译
arkcli +understand meeting-minutes --input @meeting.m4a会议纪要
arkcli +understand "<prompt>" --input @photo.jpg省略 sub-skill → 按模态自动路由(此处 → image-caption)
arkcli +understand asr --input @speech.mp3 --stream流式逐段输出
arkcli +understand image-caption --input @x.jpg --system-prompt-append "用英文回答"在内置 prompt 后追加指令
arkcli +understand image-caption --input @x.jpg "描述图片" --dry-run --format json返回 recipe / 模型 / 请求摘要的 preview.v1;零网络、不上传、不推理

详细文档

© volcengine, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files (references) in skills/arkcli-understand of volcengine/ark-cli.

  • SKILL.md
  • references/arkcli-understand.md
  • references/evals.md
  • references/sub-skills.md

Open the folder on GitHubat commit fb5b7be

Compare with similar skills

Arkcli Understand next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Arkcli Understand compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Arkcli Understand this skillvolcengine/ark-cli140—~1.7kAutomated safety check: PassApache-2.0
Gh Stackremotion-dev/remotion62k6 repos~2.4kAutomated safety check: PassCustom licence
HyperFrames Media Useheygen-com/hyperframes58k2 repos~2.1kAutomated safety check: PassApache-2.0
Guizang Social Cardsop7418/guizang-social-card-skill7.4k1 repos~7.8kAutomated safety check: PassAGPL-3.0
Weekly Changelog Videoheygen-com/hyperframes58k—~3.3kAutomated safety check: PassApache-2.0
Anthropic Brand Stylinganthropics/skills180k29 repos~559Automated safety check: PassApache-2.0

Similar skills

  • Gh Stack

    remotion-dev/remotion

    Official

    Manages stacked PRs and splits multi-part work into reviewable branches with gh-stack.

    62k GitHub starsUsed in 6 repos~2.4k tokens
    Media & CreativeAuto-check passed
  • HyperFrames Media Use

    heygen-com/hyperframes

    Finds, generates and edits media for HyperFrames video projects: music, sound effects, images, icons, logos, voiceovers, captions and color grades.

    58k GitHub starsUsed in 2 repos~2.1k tokens
    Media & CreativeAuto-check passed
  • Guizang Social Cards

    op7418/guizang-social-card-skill

    Produces social card sets for Xiaohongshu and WeChat: carousels, Live Photo motion cards and puzzle layouts, and WeChat cover pairs, rendered from single-file HTML.

    7.4k GitHub starsUsed in 1 repo~7.8k tokens
    Media & CreativeAuto-check passed
  • Weekly Changelog Video

    heygen-com/hyperframes

    Turns a weekly changelog markdown file into a branded HyperFrames video with voiceover, animated mock-UI scenes and captions, using fonts, background and scripts bundled in the skill.

    58k GitHub stars~3.3k tokensUpdated today
    Media & CreativeAuto-check passed
  • Anthropic Brand Styling

    anthropics/skills

    Official

    Applies Anthropic's brand colors and fonts to artifacts such as PowerPoint slides, using fixed hex values for text and accents, Poppins headings and Lora body text.

    180k GitHub starsUsed in 29 repos~559 tokens
    Media & CreativeAuto-check passed
  • MoneyPrinterTurbo Video Generator

    harry0703/MoneyPrinterTurbo

    Installs and runs MoneyPrinterTurbo to turn a topic or script into a finished short video with voice-over, subtitles, stock footage and music.

    129k GitHub stars~2.1k tokensUpdated today
    Media & CreativeAuto-check: warnings

More from volcengine/ark-cli

All 25 skills in this repo
  • Arkcli API Explorer

    volcengine/ark-cli

    Inspect or invoke locally registered ArkCLI actions when product commands cannot cover a task.

    140 GitHub stars~1.3k tokensUpdated 8 days ago
    Auto-check passed
  • Arkcli Code Example

    volcengine/ark-cli

    arkcli +code-example:为指定基础模型生成多语言(Python / Go / Java / Node / curl)调用示例代码并写入本地文件。数据源是火山方舟 OpenTOP OpenGetSampleCode。当用户需要拿某个基础模型的 SDK / curl 调用示例、保存为本地接入模板时使用。反触发:TTS/ASR/语音模型没有 arkcli…

    140 GitHub stars~743 tokensUpdated 8 days ago
    Auto-check passed
  • Arkcli Config

    volcengine/ark-cli

    arkcli 本地配置管理。处理 profile 配置归因、update.mode 的 automatic/disabled 策略、config reset 与历史 yaml 排障;profile 类操作优先使用 arkcli profile <subcmd。

    140 GitHub stars~1.7k tokensUpdated 8 days ago
    Auto-check: notes
  • Arkcli Custommodel

    volcengine/ark-cli

    arkcli 自定义模型仓库管理:从 TOS 导入自定义模型、查询/筛选自定义模型、查看详情、改名、删除、查询可用量化模式、量化已就绪的模型。任何提到自定义模型 ID(cm-)的管理、部署准备,或要求用 cm- 直接对话/推理/试效果的边界判断,都必须使用本 skill。注意:查询火山公共基础模型(doubao 等 foundation models)走 arkcli-models;本…

    140 GitHub stars~2.6k tokensUpdated 8 days ago
    Auto-check passed
  • Arkcli Deploy

    volcengine/ark-cli

    arkcli +deploy:普通创建推理接入点(Endpoint)的统一首选入口。用户说『创建/新建/create 一个 endpoint/接入点』或『部署/上线/deploy 某模型』时优先走这里;但脚本化 / CI / 无护栏 / 原始 raw CRUD 创建是唯一例外,必须改走 arkcli-infer-endpoint,不能由本 skill…

    140 GitHub stars~2.6k tokensUpdated 8 days ago
    Auto-check passed
  • Arkcli Docs

    volcengine/ark-cli

    检索、读取与总结方舟官方文档。用户给出 ark.volcengine.com 文档 URL 或 /docs/ 路径、要求读链接、官方说明、API 契约或必填字段,询问 CC Switch 等第三方客户端的方舟图形配置流程,以及官方网页读取失败时使用。不用于业务调用、资源操作、CLI 帮助或通用知识。

    140 GitHub stars~3.3k tokensUpdated 8 days ago
    Auto-check passed

Questions about Arkcli Understand

What does Arkcli Understand do?

arkcli +understand:基于 Responses API 的 12 个多模态专项理解配方,支持临时 API Key/Base URL/Endpoint 执行与无副作用 dry-run。用户只给 Endpoint 时先用 resources resolve;转写、抽取、字幕、定位等明确产出走本 skill,开放式对话走 +chat,生成走 +gen。. Arkcli Understand is an agent skill from volcengine/ark-cli.

When should I use Arkcli Understand?

Arkcli Understand fits situations like: media & Creative work in your project.

How do I install Arkcli Understand in Claude Code?

Run `npx skills add volcengine/ark-cli --skill arkcli-understand -a claude-code`. Or copy the skill folder (skills/arkcli-understand in volcengine/ark-cli) into .claude/skills/arkcli-understand in your project. Claude Code loads it when a task matches its description.

How do I install Arkcli Understand in Codex?

Run `npx skills add volcengine/ark-cli --skill arkcli-understand -a codex`. Or copy the skill folder (skills/arkcli-understand in volcengine/ark-cli) into .agents/skills/arkcli-understand in your project. Codex loads it when a task matches its description.

Can I use Arkcli Understand in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add volcengine/ark-cli --skill arkcli-understand -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/arkcli-understand, .gemini/skills/arkcli-understand, .github/skills/arkcli-understand and .opencode/skills/arkcli-understand in your project.

What does Arkcli Understand need to run?

SKILL.md names no scripts, command-line tools or credentials: Arkcli Understand is instructions for the agent only.

Does Arkcli Understand access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Arkcli Understand safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Arkcli Understand use?

Arkcli Understand is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Arkcli Understand use?

About 1.7k tokens (SKILL.md is roughly 6.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 7.1k tokens, read only when the agent opens those files.

What are the alternatives to Arkcli Understand?

Skills that share tags, products or a category with Arkcli Understand: Gh Stack (remotion-dev/remotion, 62k stars), HyperFrames Media Use (heygen-com/hyperframes, 58k stars), Guizang Social Cards (op7418/guizang-social-card-skill, 7.4k stars) and Weekly Changelog Video (heygen-com/hyperframes, 58k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Arkcli Understand?

volcengine (a GitHub organization) maintains it in volcengine/ark-cli, which has 140 GitHub stars. The repository holds 25 skills in this directory. The repository was last updated on September 29, 2026.

Source: volcengine/ark-cli on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.