企业官网建设流程全解析

这次我们来看一个 Agent Skill 项目：/show-me。它由开发者以 "Show HN: /show-me: agent skill for compact visual representations" 的形式发布，核心目标一句话就能说清：让 AI Agent 在需要表达结构、流程、层级、依赖关系时，直接生成紧凑、可读、token 友好的视觉表示，而不是输出一大段需要读者自己脑补的文字。

如果你接触过 Claude Code、Codex、OpenCode 这类 Agent 工具，应该对 skill 不陌生。skill 是当前 Agent 开发里最热的方向之一，本质上是一段经过验证的、可复用的能力描述，让 Agent 在特定场景下按需加载。而 /show-me 就属于 skill 这一层：它不是图像生成模型，不跑推理、不占显存，本质是一个“给 Agent 装上的可视化表达技能包”。从项目定位看，它的核心特点可以归纳为：

• 接入门槛低，不需要 GPU，普通开发机即可运行；
• 输出格式可约束，通过 SKILL.md 规则和示例控制生成质量；
• 支持批量触发，可以配合宿主 Agent 的 CLI 做批量结构化输出；
• 适合沉淀成团队标准，一次配置，多处复用。

这篇文章会带你先搞清楚四件事：第一，/show-me 到底解决什么问题；第二，skill 和 MCP 有什么区别；第三，一个 skill 项目的目录结构、安装方法和加载机制；第四，怎么按通用流程做功能验证、接口接入和批量任务。文章最后会给出常见问题的排查清单。

如果你正在做 Agent 开发、提示词工程，或者经常用 Agent 生成方案文档、代码结构说明、评审材料，这篇文章建议收藏。需要先说明的是，项目刚发布，具体参数、安装脚本、输出格式可能随版本变化，本文涉及命令的部分会以“通用模板 + 替换说明”的方式给出，实际使用时以项目 README 为准。

1. 核心能力速览

这张表里，硬件门槛是最清楚的一条：这类项目不跑模型推理，不涉及显存占用，真正影响体验的是宿主 Agent 的版本、模型能力，以及你对 skill 触发条件的配置。如果你此前没有接触过 skill 机制，建议先花几分钟确认你常用的 Agent 工具是否支持，再决定是否继续。

2. /show-me 是什么：Agent Skill、适用场景与使用边界

先说结论：/show-me 做的事情，可以理解为“给 Agent 一个可视化表达的出口”。它不是一个独立应用，也不是一个模型仓库，而是一套可以被 Agent 运行时加载的规则包。理解了这一层，你才能判断它到底适合用在什么地方，以及哪些问题它解决不了。

2.1 什么是 Agent Skill

Skill 是当前 Agent 开发里的热门概念，GitHub 上以 “skill” 命名的项目数量增长很快。它本质上把一段经过验证的“能力”打包成标准格式，让 Agent 在特定场景下按需调用。一个 skill 里通常包含：说明文档，告诉 Agent 这个技能做什么、什么时候用、怎么用；示例，给 Agent 几个输入输出样例，降低理解成本；可选脚本，如果技能需要计算、文件处理、网络请求，就配套一个小工具。

skill 与普通 prompt 的区别在于，它更结构化、可复用、可版本管理。你可以把一个 skill 当作“给 Agent 安装的一个功能插件”。相比把一大段指令写进 system prompt，skill 的核心优势是“按需加载”：Agent 检测到相关任务时才读取详细规则，不相关的场景不消耗上下文。对于上下文窗口敏感的 Agent 工作流来说，这一步能明显减少 token 浪费。

2.2 /show-me 解决什么问题

Agent 在处理复杂任务时，最容易被诟病的一点是“输出太长、结论不直观”。比如让 Agent 梳理一个模块的调用关系，它可能写出三五百字的文字描述，但读者仍然要自己脑补架构图。如果让 Agent 直接画图，常见路径是调用绘图 API 或生成流程图标记语言，但普通 Agent 并不总能输出格式正确、层级紧凑的图表。

/show-me 这类 skill 的思路是：提前把“如何画一张紧凑的视觉表示”这件事沉淀成规则。Agent 遇到需要展示结构、流程、依赖、层级的内容时，就按 skill 里的模板输出，而不是临场发挥。产出通常具备这些特征：紧凑，优先用短标签、缩写、分层缩进；结构明确，树、图、流程有清晰边界；便于粘贴，尽量用纯文本或轻量标记，不依赖重型渲染器；可验证，输出结果能快速检查，格式错误时能立即发现。

这种能力在代码评审、接口设计、方案文档和项目复盘里非常实用。Agent 给你的不再是一团文字，而是一张信息密度高、一眼能看懂的结构图。对于做 agent 开发的人来说，这也是一个很好的 skill 参考实现，可以拿来改造成自己的团队规范。

2.3 和 MCP 有什么区别

最近 Agent 社区经常讨论“skill 和 MCP 有什么区别”，这里给一个不太严谨但实用的区分。MCP 解决的是“Agent 如何连接外部工具和数据”，偏重协议和通信，比如让 Agent 访问数据库、调用 API、读写文件；Skill 解决的是“Agent 如何完成一类任务”，偏重规则和产出质量，比如“生成 Git 提交说明”“输出简洁架构图”“按指定格式整理周报”。

两者可以互补：一个 Agent 项目里，MCP 负责打通能力边界，skill 负责沉淀做事方法。/show-me 属于 skill 这一层，它的价值不是让 Agent “能画图”，而是让 Agent “画出来的图符合你的预期”，输出稳定、紧凑、可自定义。

2.4 适合谁、解决什么、不适合什么

适合的人群主要有四类：Agent 开发者，正在做 Claude Code、Codex、OpenCode 等 agent 的 skill 开发，需要一个可参考的视觉表示类 skill 范例；技术文档写作者，希望 Agent 输出的方案、架构说明、代码结构能直接转成可视化内容；项目负责人，让 Agent 批量生成模块结构图、依赖关系图，减少人工整理时间；提示词工程师，研究如何把输出格式约束从 system prompt 下沉到 skill 文件，减少上下文开销。

它能解决的问题包括：结构化表达，把多段文字转成树形图、流程图；代码理解，让 Agent 梳理目录结构、函数调用链、系统模块关系；方案对比，把多个方案的关键差异用表格或图表呈现；沟通效率，在 PR、评审、周报里直接粘贴紧凑图表，减少返工。不适合的场景也很明确：需要高质量、美观、可交互图表的场景，这不是 skill 的强项；需要严格遵循公司绘图规范、带版权模板的重型文档项目；对输出格式有高度定制需求、但又不想维护 skill 规则的业务线。另外，涉及敏感数据的大规模批量导出，必须在数据合规和脱敏前提下进行。

2.5 使用边界与合规提醒

任何 Agent skill 都会继承宿主 Agent 的数据流。用 /show-me 处理内部架构、业务数据时，要确认 Agent 调用的是允许的模型 API，数据不能进入不允许的外部服务。涉及客户信息、密钥、内网拓扑时，建议先在脱敏环境里测试。输出的图表如果用于商业文档或培训材料，要确认内容授权和版权归属，尤其是引用第三方库和模板时。这里不是做免责声明，而是实际部署时最容易忽略的一环：skill 本身是文本，但它处理的内容往往比普通提示词更结构化、更有业务价值，泄露面不小。

3. 环境准备与前置条件

由于项目本身不跑模型，这里按通用 agent skill 开发流程给出一份检查清单。实际版本和路径以项目 README 为准，不要照抄。

3.1 环境检查清单

环境准备的重点不是装依赖，而是确认三件事：宿主 Agent 版本、skill 目录路径、模型对指令的遵循能力。前两件决定能不能加载，第三件决定输出质量。

3.2 确认宿主 Agent 是否支持 skill

不同 Agent 对 skill 的支持方式不一样，普遍的做法是：在项目或用户目录下创建.agents/skills/或.claude/skills/这类固定目录；每个 skill 独占一个子目录；技能说明文件通常是SKILL.md，带有 YAML frontmatter。安装 /show-me 前，先用宿主 Agent 的命令行查看版本，再按官方文档确认 skill 目录的准确路径。不要凭经验猜目录，不同版本差异很大，目录放错是新手最容易踩的坑之一。

4. 安装部署与 skill 加载配置

严格说，skill 不是“启动”出来的，而是“加载”出来的。它会随 Agent 会话被读取，在合适的任务上按需触发。下面的配置流程是一个通用模板，你需要对照宿主 Agent 的文档调整路径和命令。

4.1 典型目录结构

一个标准的 skill 项目目录类似这样：

show-me/ ├── SKILL.md ├── examples/ │ ├── tree-01.txt │ ├── flow-01.txt │ └── architecture-01.txt ├── scripts/ │ └── render.sh └── README.md

如果你的 Agent 使用统一 skill 目录，安装时把show-me/整个复制进去即可。目录命名要简短，避免特殊符号，否则部分 Agent 可能识别不到。

4.2 SKILL.md 的配置模板

SKILL.md 是 skill 的灵魂，它包含 frontmatter 和正文两部分。frontmatter 写名称、描述、适用场景；正文写触发条件、输出规则和示例路径。下面是一个基础模板：

--- name: show-me description: Generate compact visual representations for structures, flows and relations. when_to_use: When the user asks for diagrams, trees, flowcharts, architecture overviews or any structured visual representation. ---

正文部分可以要求 Agent 按以下步骤处理：先判断目标适合哪种表示，层级关系用树，时序用流程，模块关系用图；优先使用短标签，避免长句；输出前做自检，缩进是否对齐、箭头是否闭合、层级是否完整；如果格式校验失败，用回退方案重新输出。这些规则最终要替换成项目自己的写法，没有一个万能 SKILL.md，需要根据你的模型能力和业务习惯反复调整。

4.3 安装命令示例

下面给出一套通用安装流程，路径按实际项目替换：

# 假设你的 agent skill 目录位于 ~/.agents/skills mkdir -p ~/.agents/skills cp -r ./show-me ~/.agents/skills/show-me # 验证目录结构 ls -R ~/.agents/skills/show-me # 检查 SKILL.md 的 frontmatter 是否合法 head -5 ~/.agents/skills/show-me/SKILL.md

如果你的 Agent 使用.claude/skills或项目级.agents/skills，把第一条命令的目标路径替换掉即可。安装后必须重启 Agent 会话，技能才会被重新扫描。装完先做一个最小验证：打开 Agent 会话，输入“请用 /show-me 展示当前项目的目录结构”。如果输出的是紧凑树形图，说明加载成功；如果只是普通文字列表，就回到目录路径和 frontmatter 格式上排查。

5. 功能测试与效果验证

按“小参数优先”的原则，第一次先用最简单的输入验证 skill 是否生效，再逐步增加复杂度。下面四组测试覆盖了最常见的可视化场景。

5.1 测试一：树形结构输出

输入示例：

请用 /show-me 展示当前项目的目录结构。

预期结果是 Agent 输出树形图而不是列表文字，节点自带层级缩进，符号统一，输出中没有残缺箭头或未闭合的括号。判断标准是结构能一眼看懂、缩进和对齐一致、与项目真实目录一致。失败时优先排查：如果 Agent 输出了 Markdown 列表而不是树，说明 skill 没触发，检查 frontmatter 的when_to_use写得太窄；如果输出混乱、层级错位，说明模型没理解规则，需要在 SKILL.md 中补充一个标准树形示例。

5.2 测试二：流程表示

输入示例：

用 /show-me 描述一次用户注册的完整流程。

预期结果是输出带箭头的流程，步骤之间有明确先后关系，分支用条件标记清楚。判断标准是流程顺序正确、分支条件无歧义、输出长度可控，没有大段解释文字。失败时排查：输出过长、夹杂大量解释文字，很可能是 skill 规则里没有限制“只输出图，不加解释”；分支表达不清，就增加一个带条件分支的示例，让模型照着模板走。

5.3 测试三：架构关系图

输入示例：

用 /show-me 画一个微服务的模块依赖关系图。

预期结果是输出服务之间的依赖关系，方向清楚，不依赖额外渲染器。判断标准是服务名清晰、依赖箭头方向与描述一致、不出现无关的渲染标记。这个测试最能体现 skill 的价值，因为架构关系图如果用文字描述，读者通常要花很多时间才能还原出依赖关系。如果输出中出现了系统不知道的标记语法，建议在 SKILL.md 里明确写出“只使用标准文本图符号，不使用渲染器专属语法”。

5.4 测试四：复杂内容与长上下文

输入一段长文或一份接口文档摘要，让 Agent 转成结构图。观察三点：长内容下输出是否仍然稳定、是否丢失关键节点、输出是否仍然紧凑。如果长内容下输出明显变差，建议在 SKILL.md 中增加“先列要点再画图”的中间步骤，让 Agent 先提炼再可视化。复杂场景下，宁可把一张大图拆成几张分层小图，也不要让 Agent 在一张图里塞下所有信息。

6. 接口 API 与批量任务集成

/show-me 本身是不是一个 HTTP 服务，需要看项目实际实现。但无论它是否自带接口，你都可以通过宿主 Agent 的 CLI 或脚本把它封装成可批量调用的能力。下面给出三种常见的接入方式。

6.1 会话内命令触发

在 Agent 会话里直接输入/show-me加任务描述，是最简单的方式。优点是零配置，缺点是每次都要手动输入，不适合批量场景。如果你只是个人使用，建议先用这个方式验证效果，再考虑自动化。

6.2 通过宿主 Agent 的 CLI 批量调用

如果你用 Claude Code、Codex、OpenCode 这类工具，可以通过 CLI 非交互模式批量处理任务。思路是写一个脚本，批量传入不同的输入文本，触发 Agent 调用 /show-me 并保存输出：

# 通用模板：批量让 agent 调用 skill 并保存结果 while read -r prompt; do echo "=== $prompt ===" >> outputs.txt your-agent-cli --prompt "用 /show-me 输出：$prompt" >> outputs.txt sleep 2 done < prompts.txt

以上是模板，具体命令名需要替换成宿主 Agent 的实际 CLI。批量任务的核心不是一次性跑完，而是让每一轮输出可追踪、可重试。

6.3 通过 HTTP 接口封装成服务

如果你的业务平台需要调用 /show-me 生成图表，可以封装一层 HTTP 服务。这里给一个通用 Python 示例，实际接口地址和参数需要按项目调整：

import requests url = "http://127.0.0.1:8000/api/show-me" payload = { "text": "描述用户注册流程", "format": "tree", } response = requests.post(url, json=payload, timeout=120) print(response.status_code) print(response.text)

如果项目本身没有开放 HTTP 接口，可以先用宿主 Agent 的 CLI 做批处理，再考虑外包一层服务。封装服务时要注意两点：一是控制并发，避免触发宿主 Agent 的速率限制；二是记录日志，每条请求都保存输入摘要、耗时和结果状态，方便定位问题。

6.4 批量任务设计建议

批量任务建议遵循五个原则：输入与输出分离，prompts 放一个文件，结果写另一个文件，方便失败重试；加日志，每条请求记录输入摘要、耗时、结果状态；失败重试，超时或返回非预期格式时延迟重试；任务限流，控制并发数；结果校验，批量生成完成后至少抽查 10% 的输出，确认格式和内容没有系统性偏差。对于视觉表示类 skill，常见问题是批量跑完后缩进不一致或方向错误，人工复核这一步不能省。

7. 资源占用与性能观察

/show-me 这类 skill 不进行模型推理，资源占用很小，但仍有两个维度值得观察：token 消耗和响应延迟。这两个指标直接决定它适合高频调用还是低频调用。

7.1 Token 消耗

视觉表示的“紧凑”价值主要体现在 token 上。一个 20 节点的树形图，如果按文字列表输出可能需要 300 到 500 token，按紧凑树图可能只要 100 到 200 token。测试时可以对比“让 Agent 自由发挥”和“使用 /show-me”两种方式的输出长度，直观感受 token 差异。观察方法有三种：在宿主 Agent 的会话记录里查看每次请求的 token 数；在批量脚本里记录每条任务的输入输出 token；比较同一问题在不同输出规则下的 token 总量。如果 token 减少不明显，说明 skill 的输出规则还不够紧凑，需要继续压缩标签和解释文字。

7.2 延迟与稳定性

skill 加载本身不会让响应显著变慢，真正影响速度的是模型上下文长度、输入文本长度、输出格式的复杂程度。结构化的图形格式通常比纯文本图耗时更长。如果批量任务里偶发超时，优先检查三条链路：输入文本是否过长；上下文是否已经堆积太多历史消息；是否触发了宿主 Agent 的速率限制。这里没有固定的显存或 CPU 指标可看，因为计算发生在模型 API