xinetzone/SpecWeave / .agents/skills/byted-mediakit-shared
byted-mediakit-shared
Verified1. mediakit-cli: supports a variety of operations such as audio/video processing, editing, and images, with some capabilities covering both cloud and local modes;2. mediakit-cli shared: environment checks, initialization config, command structure, authentication config, async task responses, and error handling. Use when the task needs media processing or mediakit-cli environment and authentication setup.
MediaKit Shared Rules
This skill guides you on how to operate media resources via mediakit-cli, along with the common rules and considerations during invocation.
Preflight Checks
Dependency Installation
Before first use, confirm the CLI is installed:
# Install
npm install -g @volcengine/mediakit-cli
# Verify
mediakit-cli --version
SKILL Installation
# One command installs the Skills into every supported agent on your machine
npx skills add volcengine/mediakit-cli -g -y
Authentication Info Check
Priority: environment variables > config file (file path ~/.mediakit/config.json)
Field Descriptions
- Environment variables / config file:
MEDIAKIT_API_KEY,MEDIAKIT_ENDPOINT,MEDIAKIT_SURFACE,MEDIAKIT_RUNTIME
| Variable | Required | Description |
|---|---|---|
MEDIAKIT_API_KEY | Required in cloud mode | API authentication token |
MEDIAKIT_ENDPOINT | No | API endpoint |
MEDIAKIT_SURFACE | No | Request source header x-surface; default cli, Skill recommends skill, Plugin recommends plugin, finally reported as cli/skill or cli/plugin |
MEDIAKIT_RUNTIME | No | Request source header x-runtime; set per host to claude, arkclaw, etc.; falls back to environment detection or unknown when not configured |
When any required field is missing, terminate execution and output a list of all missing items along with remediation suggestions.
Cloud invocations automatically carry x-surface / x-runtime. Header priority is: environment variables > ~/.mediakit/config.json > default value / environment detection. When this Skill/Plugin invokes cloud capabilities via mediakit-cli, the runtime environment should inject MEDIAKIT_SURFACE=skill|plugin and MEDIAKIT_RUNTIME=<host>; the CLI preserves the original artifact prefix and reports x-surface=cli/skill|cli/plugin. If not explicitly configured, the CLI defaults to x-surface=cli, and x-runtime falls back in order to IDENTITY_NAME / OPENCLAW_SERVICE_MARKER environment detection, and finally unknown.
Source Reporting Constraints
- When a Skill invokes
mediakit-cli, it must explicitly setMEDIAKIT_SURFACE=skill, and must not rely on the user's existing environment variables. - When a Plugin invokes
mediakit-cli, it must explicitly setMEDIAKIT_SURFACE=plugin, and must not reuse the Skill's value. - It is recommended to also explicitly set the host environment identifier
MEDIAKIT_RUNTIME=<host>; if not set, the CLI falls back to the environment detection value orunknown.
MEDIAKIT_SURFACE=skill MEDIAKIT_RUNTIME=<runtime> mediakit-cli editing add-image-to-video
MEDIAKIT_SURFACE=plugin MEDIAKIT_RUNTIME=<runtime> mediakit-cli editing add-image-to-video
CLI Usage
Initialization Config
For first-time use, it is recommended to run the initialization wizard first:
mediakit-cli init
For non-interactive Agent initialization, the request source and runtime config can be written explicitly:
mediakit-cli init --mode cloud-first --api-key <key> --runtime <runtime> --surface cli --yes
mediakit-cli init --mode local-first --api-key <key> --endpoint <url> --output-path ~/mediakit-output --runtime <runtime> --surface cli --credential-store config --yes
Common commands after initialization are as follows:
# View current config
mediakit-cli config show
# Switch the default mode to local-first
mediakit-cli config set mode local-first
# Switch the default mode to cloud-first
mediakit-cli config set mode cloud-first
# Refresh environment checks and view dependency status
mediakit-cli doctor
Command Structure
MediaKit CLI uniformly uses the domain + tool invocation pattern:
mediakit-cli {domain} {tool} [flags]
Common help commands:
# View all domains
mediakit-cli --domains
# View the tool list under a specific group
mediakit-cli {domain} --help
# View the parameters of a specific tool
mediakit-cli {domain} {tool} --help
# Dynamically discover tool capabilities and return structures
mediakit-cli {domain} {tool} --schema
mediakit-cli --local {domain} {tool} --schema
The domains currently covered by the artifacts include: editing, video.
Schema Discovery
Every capability command supports --schema, which lets the Agent dynamically read tool capabilities without requiring the mandatory business parameters to be passed.
The return structure includes:
name: tool name, in snake_case, e.g.add_image_to_videodescription: tool description, automatically includingModeandAsyncinformationinput_schema: input parameter JSON Schemaoutput_schema: the return structure under the current execution mode
Output differentiation rules:
- By default, parse the return surface according to the global
modeconfiguration --local ... --schemaoutputs the local-mode return surface; local mode directly returns the final result fields- Cloud async tools output
task_id/request_id, and describe thequery-taskcompleted-state result infinal_result query-taskis cloud only; the schema describes the task status and completed-state result
Examples:
mediakit-cli editing trim-video --schema
mediakit-cli --local editing trim-video --schema
Single-Invocation Mode Override
In addition to setting the default mode via config set mode, a temporary override that only applies to the current command is also supported:
mediakit-cli --local editing add-image-to-video
mediakit-cli --cloud editing add-image-to-video
Additional rules:
--local/--cloudonly affect the current command and do not modify the globalconfig.mode--localand--cloudare mutually exclusive and cannot be passed at the same time
Async Tasks
After successfully submitting an async media processing task, a task_id field is returned. Query the result via the shared query-task command.
mediakit-cli shared query-task --task-id <task_id>
local / cloud Constraints
query-taskis a cloud only tool- query-task is not supported in local mode
- The capabilities of this round are mainly executed in the cloud; if explicit declaration is needed, prefer using
--cloud
Cloud Mode Media Input Supplement
- When a command executes with the
--cloudorcloud-firststrategy, media input parameters (such asvideo_url,audio_url,image_url,subtitle_url,sub_image_url, and their corresponding array/object subfields) can be passed as anhttp:///https://URL, amediakit://...file_id, or a local file path http:///https://URLs andmediakit://...file_ids are submitted as-is; local file paths are first uploaded by the CLI as amediakit://...file_id and then submitted to the cloud tool- The parameter descriptions in each tool's reference come from the original APIHub/OpenAPI field descriptions; if a public URL or HTTP/HTTPS URL is written there, it indicates the resource form ultimately received by the cloud API, and does not restrict the CLI cloud mode's local-path preprocessing capability
Local Mode Supplement
- Local output directory priority:
--output-path>MEDIAKIT_OUTPUT_PATH> configoutput_path>~/.mediakit/temp - When
--output-pathpoints to a specific media file name, it is used directly as the final output file; otherwise,{original_filename}_{tool_name}.{ext}is generated based on the input file name, with a 6-digit random number appended on collision - When a file name cannot be extracted from the input URL or path, it falls back to
{tool_name}-{UnixNano}.{ext} - Local mode depends on
ffmpeg/ffprobe; when missing, the error provides aninstall_guide - Local mode media processing output must conform to the interface response schema, and outputting internal execution metadata is prohibited
Error Responses
- CLI cloud mode passes through the original error object returned by the API as-is, without extracting
message - CLI local mode returns a structured error:
{"error":{"type":"...","code":"...","message":"..."}} - MCP error_response passes through the original error content as-is, with the dict used directly as the value of the
errorfield
Idempotency Parameter Maintenance
| Parameter | Purpose | Maintenance Suggestion |
|---|---|---|
client_token | Actively control idempotency | Reuse the same value on request retry; pass a new unique value to force re-execution |
callback_args | Pass through callback parameters | Recommended to maintain together with client_token for callback reconciliation and retry tracking |
Additional rules:
client_tokenlength must not exceed 64 characterscallback_argscan be used for callback pass-through and reconciliation tracking
Polling Strategy
| Parameter | Description | Default |
|---|---|---|
poll-interval-seconds | Polling interval | 10s |
max-poll-attempts | Number of polls; 0 means no query | 0 |
poll-complete | Block until terminal state | - |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |