dark4scope/tech-ppt-marp skill 教程

给 dark4scope/tech-ppt-marp 做本地安装时，不要照抄 README 里的 main/SKILL.md raw 地址：截至核对时，这个仓库默认分支是 master，main 路径返回 404。最稳的做法是用 master raw 地址，或者直接 clone 仓库后复制根目录的 SKILL.md。

这个 skill 的价值在于把“暗色科技风 PPT”收束到一套固定 Marp 方案：锁定 Credit Intelligence Dark Luxe v1 设计 token，先渲染 PNG 查溢出，再导出 PPTX、PDF 和 HTML。它的限制也很明确：它不是通用 PowerPoint 自动排版器，核心产物是 Marp Markdown 驱动的 16:9 技术方案、赛事路演或产品发布 deck。

本地安装先用 master 地址

仓库根目录只有几类关键文件：README.md、SKILL.md、examples-finance-ie.md 和许可证。安装时把 SKILL.md 放进 Claude Code 的 skills 目录即可：

mkdir -p ~/.claude/skills/tech-ppt-marp
curl -fsSL https://raw.githubusercontent.com/dark4scope/tech-ppt-marp/master/SKILL.md 
  -o ~/.claude/skills/tech-ppt-marp/SKILL.md

如果想保留示例文件，直接 clone 更方便：

git clone https://github.com/dark4scope/tech-ppt-marp.git
mkdir -p ~/.claude/skills/tech-ppt-marp
cp tech-ppt-marp/SKILL.md ~/.claude/skills/tech-ppt-marp/SKILL.md

安装后重启 Claude Code。触发语通常是“做一个 PPT”“做技术方案 PPT”“比赛 PPT”“路演 PPT”或英文的 make a tech presentation。如果只想写长网页讲解，仓库说明里建议走作者的 algo-page-viz 方向，而不是这个 PPT skill。

依赖重点是 Marp CLI 和浏览器渲染

tech-ppt-marp 走的是 Marp 工具链，不依赖 PowerPoint API。先装 Marp CLI，并确认版本至少接近 README 中要求的 v4.4+：

npm install -g @marp-team/marp-cli
which marp
marp --version

Marp 会用 headless Chromium 把页面渲染成图片，再生成 PDF 或 PPTX。macOS 上如果没有可用 Chrome，可先安装：

brew install --cask google-chrome

本地图片、字体或资源参与渲染时，导出命令需要带 --allow-local-files。不带这个参数，Marp 可能拒绝读取本地资源，页面看起来就会少图、少字体或样式不完整。

先理解它固定了什么

这个 skill 最核心的不是“帮你写几页 PPT 文案”，而是固定了一套暗色科技感的视觉系统。SKILL.md 里写明了背景、卡片、文字、品牌色、语义色、边框和渐变等 22 个设计 token，并且反复强调不要把粉色、霓虹青、多重 accent 再加回来。

页面结构也偏固定：标准场景是 11 张幻灯片，围绕业务价值、技术创新、工程实现、可扩展性等评分维度展开。对比赛路演或技术方案汇报来说，这种固定结构能减少来回调色和重排版；但如果目标是轻松培训课、品牌故事长稿或复杂交互演示，就要先判断是否适合 11 页密度。

examples-finance-ie.md 是实际示例，里面包含 Marp frontmatter、深色背景、渐变标题、玻璃感表格和紧凑的组件尺寸。写新 deck 时，可以先从这个示例理解作者希望的页面密度，而不是只复制颜色变量。

第一次试跑用临时目录

建议先在临时目录写一个简单主题，确认 Marp 能渲染。完整 deck 通常会由 Claude Code 生成一个 /tmp/<topic>.md，里面包含 marp: true、size: 16:9、深色背景和完整 CSS。

cd /tmp
TOPIC=demo-tech-ppt
marp ${TOPIC}.md --images png --image-scale 1 --allow-local-files -o ppt_slides/slide.png

这一步不是可选装饰，而是这个仓库反复强调的自检环节。Marp 会输出类似 ppt_slides/slide.001.png 的 1280×720 图片。先检查这些 PNG，再决定是否改字号、删内容、调 .ann 框或表格行数。

为什么 PNG 自检不能省

Marp 编辑器里看着正常，不等于 PDF 或 PPTX 最终不会溢出。这个 skill 把“先导出给人看”视为反模式，要求先用 marp --images png 渲染每页，再逐页检查底部、右栏、表格和注释框。

常见问题包括右栏注释框被截、四个 metric 两行堆叠过高、h2 字号撑开行高、顶部 eyebrow 太贴边。SKILL.md 给出的修法也很具体：删 bullet 数、把 .ann 字号从 13 调到 12、把 2×2 metric 改成 1×4、把 h2 控在 34px 左右。

如果 Read 视图看起来被缩小挤压，还要用文件信息确认 PNG 是否真的是 1280×720，而不是把缩略视图误判成版面问题。这里的目标不是追求更炫，而是保证每页交付时没有被截断的内容。

通过后再导出 PPTX 和 PDF

PNG 全部通过后，再分别导出 PPTX 与 PDF。Marp 不支持 --pptx 和 --pdf 同时跑，两个命令需要分开执行：

cd /tmp
marp ${TOPIC}.md --pptx --allow-local-files
marp ${TOPIC}.md --pdf --allow-local-files

如果还要生成在线翻页 HTML，可再导出 index.html，或按自己的站点结构部署。仓库默认部署说明指向 https://darkscope.cn/algorithms/<topic>-ppt/，本地使用时不必照搬这个服务器路径，只需要确认 .md、.pptx、.pdf 能在自己的交付目录里对应上。

输出检查看这几项

第一，看 PNG 是否覆盖所有页，尺寸是否为 1280×720。第二，看 PDF 是否能打开，并抽查表格、卡片、底部页码和大标题。第三，看 PPTX 能否在 PowerPoint 或 Keynote 中打开，尤其注意它本质上是 Chromium 渲染后的高保真页面，复杂 CSS 会换来更大的文件体积。

README 提到，复杂玻璃拟态、backdrop-filter、mix-blend-mode 会让 PDF 从 1 到 2MB 增长到 10 到 15MB。这个不是错误，而是把视觉质感 raster 进导出文件的代价。若提交系统限制体积，就需要提前压缩或降低复杂度。

适合谁，不适合谁

dark4scope/tech-ppt-marp 适合做技术方案、算法项目、科技、比赛路演、产品发布这类需要严肃暗色视觉和评分结构的 deck。它尤其适合已经知道主题和论点，只缺一套稳定视觉系统与导出验证流程的人。

它不适合拿来临时美化任何 PPT，也不适合需要大量手工拖拽编辑的传统 PowerPoint 工作流。真正应该保留下来的使用习惯是：先固定设计 token，再控制每页内容预算，PNG 自检通过后才导出正式文件。这样跑出来的 PPTX 和 PDF，才不会只是“看起来科技”，而是在交付边界上也可靠。