Vulkan 渲染专家技能

English | 中文

这是一个 Vulkan 渲染工程专家技能包。它不是 Vulkan 入门教程，而是为真实渲染工程任务准备的运行时知识库：用于在处理 Vulkan 设计、实现、调试、优化和验证问题时，按工程链路组织判断、引用规则、API 细节、调试路径和回归验证。

适用场景

• 设计 Vulkan 渲染管线、Render Pass、Dynamic Rendering、Render Graph 或 RHI 抽象。
• 实现或修改 Descriptor、Pipeline、Command Buffer、Buffer/Image、Swapchain、同步和资源生命周期代码。
• 排查黑屏、闪烁、崩溃、GPU hang、device lost、Validation Error、image layout、descriptor binding 等问题。
• 分析移动端 Vulkan 性能瓶颈，包括 bandwidth、fullscreen pass、barrier、descriptor 更新和 pipeline 创建卡顿。
• 处理 Android Vulkan 的 ANativeWindow、Surface 生命周期、pause/resume、横竖屏和 swapchain recreate。
• 在不确定 API 细节时，区分规范来源、经验判断和需要回查的内容。
• 分析真实 Vulkan / 图形引擎仓库，建立 [CODE] 源码证据、Architecture Map、源码级影响面和 coding-agent 实施计划。

技能结构

.
├── SKILL.md                 # 技能入口，定义触发、加载顺序和输出规则
├── agents/                  # 可选的工具或平台集成配置
├── assets/                  # README 和发布页使用的图片资产
└── references/              # Vulkan 专家知识库，按任务渐进加载

references/ 按职责拆分为 8 个模块：

核心能力

这个技能要求输出始终给出可执行的 Vulkan 路径，而不是停留在概念解释：

1. 先给结论和最高优先级判断。
2. 给出 Vulkan 对象链路、关键 API、资源状态、layout 或同步关系。
3. 标出 descriptor、pipeline、command buffer、image layout、lifetime、Android lifecycle 等高风险点。
4. 给出最小验证方式，例如 Validation Layer、RenderDoc、AGI、logcat、trace、counter 或 targeted assert。
5. 对不确定 API 细节明确要求回查 Vulkan Spec、Registry、官方示例或平台文档。

v1.0.9：轻量入口（2026-10-17）

启动只加载全部 19 条硬规则、唯一路由入口段落及命中类型，再按需读取模板、准确性规则与检索协议。保留全部 8 模块、触发词、宿主配置、Evidence Map / Architecture Map，以及结论前必做的 G1-G6 验证。

稳定锚点与全文读取回退见检索协议，旧规则去向见规则迁移映射。实际模型 token 降低 30% 是待测目标；静态体积变化不能证明 live 行为或质量不回退，未取得对应证据前不宣称达标。

安装与调用

本技能遵循 Agent Skills 规范：仓库根目录即技能目录，SKILL.md 是入口，references/ 按需加载。

Claude Code

git clone https://github.com/oahc09/vulkan-rendering-expert-skill ~/.claude/skills/vulkan-rendering-expert-skill

放入技能目录后，描述 Vulkan 问题即可自动触发；也可显式说"使用 vulkan-rendering-expert-skill"。

TraeCode / Trae

在技能管理中添加本仓库目录作为本地技能，或从技能市场搜索安装。

其他支持 Agent Skills 的宿主（Cursor、VS Code 插件等）

凡能读取 SKILL.md frontmatter 并按其指令加载 references/ 文件的宿主均可使用。宿主不支持技能机制时，可把 SKILL.md 全文粘贴为系统提示词，技能以降级模式工作；仍需按入口要求提供硬规则与命中参考段落（自动加载失效，不能仅凭入口全文声称完整执行）。

提问示例库

以下提问可直接复制使用，括号内为会触发的模块：

1. Android Vulkan 前后台切换后黑屏，给出对象链路、最可能原因和验证步骤。（debug playbook + Android case）
2. vkCreateGraphicsPipelines 报 VUID 错误，帮我解码这条 Validation 消息：（validation 解码 playbook）
3. 小米 13 上 GPU 帧耗时 22ms，全屏后处理占大头，怎么优化？（性能 playbook + 优化 workflow）
4. 从零搭建一个最小 Vulkan renderer，要求 Validation clean、能 resize。（renderer workflow + 架构决策）
5. 材质数量上千，descriptor set 创建很慢，要不要上 bindless？给我决策分析。（架构决策框架 + bindless 案例）
6. 现有 8 个 pass 的手写 barrier 维护不动了，评估是否引入 RenderGraph。（架构决策 + RenderGraph 案例）
7. vkCmdPipelineBarrier2 的 srcStageMask 怎么选？（API 卡片）
8. 有没有 swapchain recreate 导致崩溃的真实案例？（case 索引）
9. 先诊断现有仓库的 Vulkan 架构，再评估升级 Vulkan 1.3 的源码影响面，不要给通用建议。（project diagnosis + regression reasoning）

提问时附带关键信息可获得最准回答，各类任务的信息清单见 references/00_expert_entry/progressive_retrieval.md R2 节的分任务类型提问模板。

上手路径

• 直接提问（推荐）：无需先读任何文件，技能按症状/意图自动路由到对应 playbook、workflow 或案例。
• 看知识地图：读 references/README.md 和 references/MODULE_SUMMARY.md，了解 8 个模块的分工与规模。
• 深入学习：按模块编号 00 → 07 顺序阅读；调试优先读 04_debug_playbooks/，实现优先读 05_workflows/，架构优先读 02_core_mental_model/engine_architecture.md；真实仓库分析优先读 05_workflows/01_renderer_setup/project_diagnosis.md。