Agent Skills › ChatCut-Inc/agent-plugin › known-errors

known-errors

GitHub

诊断ChatCut插件工具故障，指导处理突变拒绝、导入媒体、生成及导出错误。依据当前MCP schema解决冲突、重试和认证问题，避免无效操作。

claude/skills/known-errors/SKILL.md ChatCut-Inc/agent-plugin

Trigger Scenarios

插件工具调用失败突变被拒绝或验证错误媒体导入或转换异常内容生成或渲染报错

Install

npx skills add ChatCut-Inc/agent-plugin --skill known-errors -g -y

More Options

Non-standard path

npx skills add https://github.com/ChatCut-Inc/agent-plugin/tree/main/claude/skills/known-errors -g -y

Use without installing

npx skills use ChatCut-Inc/agent-plugin@known-errors

指定 Agent (Claude Code)

npx skills add ChatCut-Inc/agent-plugin --skill known-errors -a claude-code -g -y

安装 repo 全部 skill

npx skills add ChatCut-Inc/agent-plugin --all -g -y

预览 repo 内 skill

npx skills add ChatCut-Inc/agent-plugin --list

SKILL.md

Frontmatter

{
    "name": "known-errors",
    "description": "Diagnose ChatCut plugin tool failures, rejected mutations, unexpected response shapes, and blocked import, generation, or render operations."
}

Known Errors

Treat the active MCP tool schema and returned structured error as authoritative. Do not retry with remembered legacy payloads when the current manifest differs.

Mutation Rejections

On same-track overlap, do not force the write or silently delete the conflicting item. Decide whether content is sequential or layered, choose an available track when appropriate, or ask which item should win.
On locked-track or stale-id failures, refresh the affected timeline scope and retry only with current ids and state.
On validation errors, change only the rejected field or transaction shape; preserve unrelated project state.

Import And Media

Hosted plugin surfaces use the asset-import adapter and import_media; do not substitute backend-only push_asset or download_media calls when they are absent.
If media conversion fails, use the helper's structured retry when provided. Otherwise explain the unsupported source and ask for a compatible replacement; do not repeat the same failing editor import path.
Wait for upload only before byte-dependent operations. A known asset id can be used for metadata and timeline placement while bytes continue uploading.

Generation And Motion Graphics

Use only generation tools visible on the current host. Codex direct-authors Motion Graphics with create_motion_graphic_from_code; Claude Code may expose submit_motion_graphic.
Preserve the original provider or content-policy failure. Do not spend credits on repeated identical retries or silently switch models.

Verification And Export

A successful mutation is not visual proof; load verification when the result must be seen.
Use track_export for render jobs. If cloud render cannot read an asset, resolve remote readiness through asset-import only with user permission, or report the limitation.

On auth or project-access errors, verify the exact project id and that the editor and plugin use the same ChatCut account before attempting code or infrastructure debugging.

Version History

e1867a8 Current 2026-08-02 23:36
重构错误处理指南，从固定payload示例转为基于当前MCP schema的动态诊断，新增对运动图形生成、异步上传及云渲染就绪状态的详细处理逻辑。
f39cdae 2026-07-30 21:53
新增浏览器视频转换失败的处理策略，明确需修复源文件或重新编码而非重试UI；更新Local dev Zero caveat说明端口隔离配置；补充Timeline screenshot renderer caveat片段。
5e9afe0 2026-07-22 10:57