visual-companion-workflow-skill
tianyuegithub/visual-companion-workflow-skill
Visual companion workflow skill for Claude Code and Codex agents
Instalação
npx convez-ai tianyuegithub/visual-companion-workflow-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Visual Companion Workflow Skill
一个面向 Claude Code / Codex 类 agent 的“可视化伴随”工作流 skill。
它的核心不是生成一份漂亮 HTML,而是把本地浏览器变成实时协作白板:先打开 localhost,让用户看到等待页;再逐轮把用户输入、agent 理解、设计增量和下一步问题追加到同一个 URL 中。等讨论确认后,再产出正式需求、方案、计划或代码。
适用场景
- 需求澄清:把用户原话、理解偏差和设计增量放在同一画布里。
- 架构讨论:用流程图、边界图、对象关系图辅助决策。
- 产品设计:边聊边展示线框、布局、选项和决策清单。
- 本体/知识图谱:可视化对象类型、关系、实例校准和边界。
- 文档前置讨论:先用临时画布收敛,再生成正式文档。
不适合一分钟能说清楚的事实问答,也不适合绕过用户确认直接落正式产物。
安装到 Claude Code
推荐直接用 npx 从 GitHub 安装:
npx --yes github:tianyuegithub/visual-companion-workflow-skill install
默认会写入:
~/.claude/skills/visual-companion-workflow/SKILL.md
如果你已经安装过,CLI 会拒绝覆盖。确认要替换时再加 --force:
npx --yes github:tianyuegithub/visual-companion-workflow-skill install --force
如果你希望先看安装位置,不写文件:
npx --yes github:tianyuegithub/visual-companion-workflow-skill install --dry-run
安装到 Codex / 其他本地 agent
如果你的 agent 使用 Codex 或通用 ~/.agents/skills 目录:
npx --yes github:tianyuegithub/visual-companion-workflow-skill install --target codex
npx --yes github:tianyuegithub/visual-companion-workflow-skill install --target agents
如果想同时安装到 Claude Code、Codex 和 ~/.agents:
npx --yes github:tianyuegithub/visual-companion-workflow-skill install --target all
也可以指定任意 skills 根目录:
npx --yes github:tianyuegithub/visual-companion-workflow-skill install --skills-dir ~/.claude/skills
关键是让 agent 能在用户提到“可视化伴随”“visual companion”“先给我 localhost URL”等触发词时读取这份 SKILL.md。
npm registry 发布后
当前仓库已经包含 package.json 和 CLI,具备 npm 发布条件。发布到 npm registry 后,可以改用更短的命令:
npx --yes visual-companion-workflow-skill install
发布前需要本机先登录 npm:
npm adduser
npm publish
触发话术
可以直接对 agent 说:
进入可视化伴随模式,我们用本地页面讨论这个需求。
先给我一个 localhost URL,页面里等待推送。
用可视化伴随梳理这个架构,不要先落正式文档。
"进入可视化伴随模式"
"启动一个静态 HTML 页面,我们边看边改"
"先给我一个 localhost URL"
"打开我的本地浏览器,页面里等待推送"
"用可视化伴随讨论这个需求/架构/流程/本体"
"不要先落正式文档,先用页面讨论"
正确工作流
- 启动本地可视化伴随服务器。
- 立刻打开返回的本地 URL,此时页面可以只是等待态。
- 推送一个很小的首屏,先提出当前问题或展示草图。
- 后续保持同一个 URL,不断追加新的 screen。
- 每轮更新前读取浏览器事件,把点击反馈和聊天反馈合并。
- 页面从上到下保留决策轨迹:用户输入、agent 理解、设计增量、下一步问题。
- 用户确认后,再沉淀正式 Markdown、HTML、实现计划或代码改动。
仓库内容
SKILL.md:可直接安装的 skill 说明。bin/visual-companion-workflow-skill.mjs:npx 安装器。docs/visual-companion-skill-guide.html:HTML + SVG 分享文档,可直接用浏览器打开。examples/minimal-first-screen.html:最小首屏片段示例。LICENSE:Apache License 2.0。
设计原则
- 先开浏览器,再推内容。
- 使用同一个 URL 持续迭代。
- 优先追加,不覆盖已有讨论。
- 临时伴随页不是正式交付物。
- 可点击反馈要进入下一轮分析。
- 确认后的正式产物才进入项目仓库。
常见误区
| 误区 | 正确做法 |
|---|---|
| 先做完整 HTML,最后才让用户打开 | 先打开等待页,再推首屏 |
| 每轮换一个 URL | 始终使用同一个 URL |
| 覆盖旧内容 | 保留旧决策,向下追加 |
| 把伴随页直接当正式需求文档 | 用户确认后再生成持久文档 |
| 忽略浏览器点击 | 更新前读取事件并合并反馈 |
授权
本项目使用 Apache License 2.0 授权。