Agent Skills › langchain-ai/design-agent › design-agent-troubleshoot

design-agent-troubleshoot

GitHub

用于诊断和修复 Design Agent 故障,涵盖模型调用、部署及渲染异常。通过运行诊断工具、测试连接并对照症状表定位问题,结合日志与 LangSmith 追踪分析原因,指导用户采取相应修复措施。

.agents/skills/design-agent-troubleshoot/SKILL.md langchain-ai/design-agent

Trigger Scenarios

Design Agent 命令报错或无响应 需要排查模型连接、部署或渲染失败原因 查看系统日志或追踪以定位错误

Install

npx skills add langchain-ai/design-agent --skill design-agent-troubleshoot -g -y
More Options

Non-standard path

npx skills add https://github.com/langchain-ai/design-agent/tree/main/.agents/skills/design-agent-troubleshoot -g -y

Use without installing

npx skills use langchain-ai/design-agent@design-agent-troubleshoot

指定 Agent (Claude Code)

npx skills add langchain-ai/design-agent --skill design-agent-troubleshoot -a claude-code -g -y

安装 repo 全部 skill

npx skills add langchain-ai/design-agent --all -g -y

预览 repo 内 skill

npx skills add langchain-ai/design-agent --list

SKILL.md

Frontmatter
{
    "name": "design-agent-troubleshoot",
    "description": "Diagnose Design Agent when something fails. Setup, a render, a deploy, Slack or a model call. Run doctor and the connection tests, read logs and traces, match the symptom to its fix, and never print credentials. Use when a command errors, a reply never comes, or a file looks wrong."
}

Troubleshoot Design Agent

Report missing settings by name and never paste a key, token or .env line.

  1. uv run design-agent doctor (add --json to parse it) checks every model role, keys, the brand, the sandbox, MDA declarations, MCP and Paper. Fix what it names first.
  2. Real calls, a few cents each: uv run design-agent test model, test sandbox, test paper, test slack, test db.
  3. Match the symptom:
Symptom Fix
demo needs a sandbox start Docker, then uv run design-agent sandbox build
A render is missing a font uv run design-agent fonts verify; family in fonts.toml must be the name inside the file
Off-brand colours or a failed brand check uv run design-agent brand validate, then brand css
"The connection to the model stalled" or "stayed unavailable" check the provider's status, then reply continue in the thread
Background news arrives a minute or two late on MDA expected: MDA schedules land on the next minute
"A restart may have stopped…" a deploy or restart stopped helpers; ask the agent to resume them
Paper "not connected" Paper Desktop is closed or the bridge is down; boards still render in the sandbox
The sandbox bake runs out of disk on mda deploy uv run design-agent sandbox publish first
"Context Hub only accepts UTF-8 text files" move the skill's binary files to skill-binaries/<skill>/
"source archive … exceeds the 200 MB limit" clear old renders in workspace/out/
An MCP server is missing the startup log names the one that failed; the rest keep working
  1. Logs: uv run mda logs on MDA; docker compose -f deploy/self-host/compose.yaml logs api when self-hosted. Logs carry exception classes, never provider messages or keys.
  2. Traces: every run is traced in LangSmith (an MDA deployment's project is <deployment>-production). Follow a bad file back to the skills read, tools called and checks run, with the langsmith-trace skill. API runs attach delivered files to the trace. The deployed agent can read its own traces too (list_traces, read_trace): ask it in the thread what went wrong.
  3. A real bug: reproduce it with a failing test before changing code, then follow AGENTS.md.

More: Operations.

Version History

  • 8134d7c Current 2026-11-20 21:40

Same Skill Collection

.agents/skills/brand-onboarding/SKILL.md
.agents/skills/deep-agents-core/SKILL.md
.agents/skills/deep-agents-memory/SKILL.md
.agents/skills/deep-agents-orchestration/SKILL.md
.agents/skills/design-agent-customize/SKILL.md
.agents/skills/design-agent-deploy/SKILL.md
.agents/skills/design-agent-evals/SKILL.md
.agents/skills/design-agent-onboarding/SKILL.md
.agents/skills/design-agent-update/SKILL.md
.agents/skills/langsmith-evaluator/SKILL.md
.agents/skills/vendor-sync/SKILL.md
skills/brand-design/SKILL.md
skills/content-brief/SKILL.md
skills/data-viz/SKILL.md
skills/design-wiki/SKILL.md
skills/faceless-explainer/SKILL.md
skills/film-breakdown/SKILL.md
skills/general-video/SKILL.md
skills/gif-edit/SKILL.md
skills/hyperframes-core/SKILL.md
skills/hyperframes-creative/SKILL.md
skills/hyperframes-keyframes/SKILL.md
skills/image-generation/SKILL.md
skills/image-ops/SKILL.md
skills/launch-film/SKILL.md
skills/media-production/SKILL.md
skills/motion-direction/SKILL.md
skills/music-to-video/SKILL.md
skills/paper-design/SKILL.md
skills/pr-to-video/SKILL.md
skills/reference-study/SKILL.md
skills/remotion-to-hyperframes/SKILL.md
skills/slideshow/SKILL.md
skills/sound/SKILL.md
skills/stills/SKILL.md
skills/storyboard/SKILL.md
skills/thumbnails/SKILL.md
skills/visual-verify/SKILL.md
.agents/skills/managed-deep-agents/SKILL.md
skills/embedded-captions/SKILL.md
skills/hyperframes-animation/SKILL.md
skills/hyperframes-audio/SKILL.md
skills/hyperframes-cli/SKILL.md
skills/hyperframes-registry/SKILL.md
skills/hyperframes/SKILL.md
skills/media-use/SKILL.md
skills/motion-graphics/SKILL.md

Metadata

Files
0
Version
8134d7c
Hash
e3f1df8f
Indexed
2026-11-20 21:40

ホーム - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-21 02:35
浙ICP备14020137号-1