AI Agent Skill 整理与管理实践：以 PPT Skill 为例讲清安装、识别、路由、排错与安全规范

参考资料和来源说明

本文参考了以下公开资料，并结合 PPT Skill 管理场景做工程化整理。链接附在这里，方便读者追溯原始说明。

资料	用途
OpenAI Codex Agent Skills 文档	说明 Skill 的目录结构、`SKILL.md`、`name`、`description`、渐进式加载、显式/隐式触发和本地安装位置
OpenAI Codex Customization 文档	说明 Skill、AGENTS.md、MCP、插件之间的边界，以及全局 Skill 和仓库级 Skill 的适用场景
Agent Skills 标准概览	说明`SKILL.md`、`scripts/`、`references/`、`assets/` 这类通用 Skill 结构
ningzimu/codex-ppt-skill	作为图片式 PPT Skill 的公开案例来源，用于讲解整页图片式 PPT、阶段化确认、样张确认和本地组装
python-pptx 官方文档	说明 Python 生成和分析 PPTX 的能力边界，例如添加幻灯片、图片、文本框、表格和图表
Microsoft PresentationML 文档	说明 PPTX/Open XML 中 presentation、slide、theme、notes 等部件结构
Git sparse-checkout 官方文档	说明只拉取仓库中部分目录的方式，适合从大型社区仓库安装单个 Skill
GitHub Repository Contents API 文档	说明无法直接 Git clone 时，如何通过 API 获取仓库文件或目录内容
GitHub Secret Scanning 文档	说明为什么发布 Skill、教程和仓库前必须做密钥扫描

需要注意的是，公开资料只提供基础机制和案例。本文中的目录设计、路由规则、排错表和安全清单是面向工程实践的整理，不代表任何工具在所有环境中都自动具备这些行为。

背景与问题定义

Skill 可以理解为"给 Agent 看的可复用工作说明书"。它不是普通提示词，也不一定是完整插件。一个好的 Skill 会把某类任务的流程、边界、质量标准、依赖工具和验收方式固化下来，让 Agent 在新对话里也能复用同一套做法。

以 PPT 生成为例，很多人直接让 Agent "做一份 PPT"，得到的往往只是大纲、普通文本或布局不稳定的文件。真正可用的 PPT 工作流至少要回答这些问题：

输入是什么：主题、资料、目标受众、页数、语言、风格、是否有模板、是否要求可编辑。
输出是什么：可编辑 PPTX、图片式 PPTX、讲稿、每页图片、渲染检查结果或源文件。
中间处理流程是什么：理解资料、整理叙事、设计视觉系统、生成样张、批量生成、QA、组装、导出。
关键模块有哪些：主控 Skill、可编辑 PPT 工具、图片生成 Skill、组装脚本、验证脚本、脱敏检查。
什么时候不能直接继续：缺少关键资料、用户要求和技术路线冲突、密钥未配置、下载来源不可信、输出不可验证。

因此，Skill 管理不是"把几个文件复制进去"这么简单。它至少要解决四件事：

能不能被 Agent 发现。
什么时候应该触发，什么时候不应该触发。
依赖工具和运行环境是否可用。
输出是否能被验证，且不会泄露隐私和密钥。

本文把一次真实整理 Skill 的过程抽象成下面这张工程问题表。这里不记录任何私人路径和对话细节，只保留可复用的技术判断。

现场现象	抽象成的工程问题	文章中的处理方式
明明装过不少 Skill，界面却只显示少数插件	插件列表不等于 Skill 清单	区分 Skill、Plugin、系统 Skill、用户 Skill、社区 Skill
Skill 中英文混杂	元数据来源不同，`name` 和 `description` 语言策略不统一	保留稳定英文名，在 description 中补充中文触发词
新对话不一定知道新装的 PPT Skill	Skill 需要进入可扫描目录，且 description 能被触发	扫描`SKILL.md`、检查元数据、准备回归提示词
PPT 高颜值和可编辑性冲突	图片式 PPT 与可编辑 PPTX 是两条不同路线	设计主控 Skill，默认可编辑，图片式路线必须明确接受
下载社区 Skill 时可能失败	Git、代理、DNS、权限、仓库路径都可能出错	用`git ls-remote`、代理检查、API 下载作为排错路径
担心泄露 API key 和本地路径	Skill、教程、截图和仓库都可能泄露敏感信息	增加发布前脱敏扫描和人工安全清单
不想每次重新解释偏好	临时对话经验没有固化	把路由、质量标准和验证步骤写进`SKILL.md` 与 references

核心概念

1. `SKILL.md` 是 Skill 的入口

在常见 Agent Skill 结构中，一个 Skill 至少是一个包含 SKILL.md 的目录。SKILL.md 的开头通常包含 YAML front matter，用来声明 name 和 description。

yaml 复制代码

---
name: example-ppt-skill
description: Create, refine, route, QA, and export presentation decks. Use when the user asks for PPT, PowerPoint, slide decks, report decks, defense decks, course decks, or 高颜值PPT.
---

name 用于标识 Skill，应该稳定、简短、避免和其他 Skill 重名。description 决定隐式触发是否稳定，应该把核心任务、关键词、适用范围和排除范围写清楚。

一个常见误区是只写：

yaml 复制代码

description: Make PPT.

这种描述太窄，无法覆盖"答辩 PPT""汇报稿""路演 deck""美化现有 PPT""导出 .pptx"等常见说法。更稳的做法是把中英文触发词和边界都写进去，但不要写成无边界的万能 Skill。

2. Skill 和插件不是一回事

在 Codex 类工具里，Skill 更像"工作流作者格式"，插件更像"可安装分发单位"。一个插件可以包含一个或多个 Skill，也可以包含 app 映射、MCP 配置或其他资源。反过来，本地用户目录里也可以直接存在 Skill，但它们不一定以插件形式出现在插件列表里。

这解释了一个常见现象：界面里的插件只有几个，但本地实际可用的 Skill 可能更多。插件列表不等于 Skill 全量清单。真正盘点 Skill，应该扫描 SKILL.md，而不是只看插件 UI。

3. 渐进式加载

很多 Agent 不会一开始就把所有 Skill 全文塞进上下文，而是先读取 Skill 的 name、description 和路径。只有当任务匹配某个 Skill 时，才读取完整 SKILL.md，再按需要读取 references/、scripts/ 或其他文件。

这带来两个工程要求：

description 必须高质量，因为它是被发现和触发的第一入口。
支撑文档可以拆到 references/ 或 docs/，但 SKILL.md 必须写清何时读取这些文件。

如果安装了大量 Skill，初始 Skill 列表可能被压缩，描述过长的 Skill 更容易丢失关键信息。因此 description 要把最重要的触发词放在前面。

4. 可编辑 PPT 与图片式 PPT

PPT Skill 最容易混乱的地方是"可编辑"和"高颜值"经常互相拉扯。

可编辑 PPTX 指页面中的标题、正文、图形、表格、图表尽量使用 PowerPoint 原生对象。优点是后续可以逐字修改，适合答辩、课程汇报、工程评审、数据报告。缺点是视觉上限受模板、布局代码和渲染能力影响。

图片式 PPTX 指先为每页生成一张完整 16:9 图片，再把图片铺满幻灯片。优点是视觉统一、风格强，适合演讲、展示、路演和海报感页面。缺点是页面里的文字和图表不是逐元素可编辑，后续修改通常要重新生成图片。

类型	适合场景	优点	局限
可编辑 PPTX	答辩、课程汇报、工程评审、数据报告	文字、形状、表格、图表可继续改	复杂视觉效果需要模板和布局能力支撑
图片式 PPTX	视觉展示、主题演讲、路演、海报感汇报	风格统一、视觉冲击强、页面完整度高	文本和图表通常不可局部编辑
混合 PPTX	封面/章节页强调视觉，正文页强调可编辑	兼顾展示和维护	必须标注哪些页可编辑、哪些页是图片

一个高质量 PPT Skill 必须先判断交付路线，而不是盲目生成。

工程架构

一个通用 Skill 目录可以这样组织：

text 复制代码

~/.agent/skills/
├── system/
│   └── skill-installer/
│       └── SKILL.md
├── user/
│   └── ppt-master/
│       ├── SKILL.md
│       └── references/
│           ├── ppt-quality-checklist.md
│           └── image-first-caveats.md
└── community/
    └── codex-ppt/
        ├── SKILL.md
        ├── requirements.txt
        ├── docs/
        │   ├── workflow-gates-and-progress.md
        │   ├── backend-selection.md
        │   ├── outline-style-and-sample.md
        │   ├── slide-generation-and-subagents.md
        │   └── project-assembly-and-reporting.md
        ├── prompts/
        ├── scripts/
        └── references/

这个结构分成三层：

system/：系统预置 Skill，例如安装器、文档处理、PDF、表格、PPT 等通用能力。
user/：用户自己维护的主控 Skill，适合放个人常用工作流、质量标准和路由规则。
community/：来自社区的第三方 Skill，安装前必须检查来源、许可证、依赖和脚本行为。

以 PPT 为例，推荐使用"主控 Skill + 辅助 Skill"的结构：

ppt-master：主控 Skill，负责理解需求、判断路线、控制质量、选择可编辑或图片式工作流。
codex-ppt：图片式 PPT 辅助 Skill，负责高视觉统一性页面、样张确认、整页图片生成和 PPTX 组装。
Presentations 或其他 PPT 工具：负责可编辑 PPTX 的创建、修改、渲染和导出。

这种分层的好处是边界清楚。主控 Skill 负责"该不该用"，辅助 Skill 负责"怎么生成"，验证脚本负责"结果能不能交付"。

环境准备

不同 Agent 客户端的 Skill 目录和加载机制可能不同，下面只给通用检查项。版本、目录和命令都需要根据实际环境确认。

1. 操作系统与 Shell

Linux/macOS 常用 Bash 或 Zsh：

bash 复制代码

uname -a
echo "$SHELL"

Windows PowerShell 可检查：

powershell 复制代码

$PSVersionTable

写教程时不要把个人机器上的真实绝对路径写进正文。需要路径时，使用 ~/.agent/skills、./skills/example-skill、~/project 这类通用示例。

2. Git、Python 与 PPT 依赖

社区 Skill 常用 Git 下载，本地脚本可能依赖 Python。版本号以实际环境为准。

bash 复制代码

git --version
python --version

如果要用 Python 组装 PPTX，可以检查 python-pptx：

bash 复制代码

python -c "import pptx; print('python-pptx ok')"

如果导入失败，需要按项目文档安装依赖：

bash 复制代码

python -m pip install -r requirements.txt

3. 网络、代理和仓库访问

安装社区 Skill 前，先确认仓库能访问：

bash 复制代码

git ls-remote <COMMUNITY_SKILL_REPO_URL> HEAD

如果失败，不要立即判断仓库不存在。常见原因包括代理不可用、DNS 异常、证书问题、仓库地址错误、私有仓库无权限。

检查 Git 代理：

bash 复制代码

git config --global --get-regexp 'http.*proxy|https.*proxy'

是否应该取消代理，需要根据实际网络环境确认。不要在不了解网络环境的情况下强行修改全局配置。

4. API key 和环境变量

部分图片生成 Skill 需要模型 API。教程和 Skill 文档只能写变量名和占位符，不能写真实密钥。

bash 复制代码

export OPENAI_API_KEY="<API_KEY>"
export OPENAI_BASE_URL="https://api.example.com/v1"

Windows PowerShell 示例：

powershell 复制代码

$env:OPENAI_API_KEY = "<API_KEY>"
$env:OPENAI_BASE_URL = "https://api.example.com/v1"

这些变量名是否适用，需要看具体 Skill 文档。不要把真实密钥写进 SKILL.md、文章、截图、仓库、提交记录或聊天记录。

实战案例：整理一个 PPT Skill 体系

这一节用一个公开化案例讲完整流程。目标是让 Agent 在新对话里遇到 PPT 任务时能稳定判断：

用户要可编辑 PPTX，就走可编辑流程。
用户明确接受整页图片，就走图片式 PPT 流程。
用户只是想要高颜值但还要后续修改，就先解释取舍，再默认可编辑。
用户想先看效果，就先生成样张，不直接批量生成完整 deck。

第一步：盘点当前有哪些 Skill

先扫描所有 SKILL.md。Linux/macOS 可用：

bash 复制代码

find ~/.agent/skills -name SKILL.md

PowerShell 可用：

powershell 复制代码

Get-ChildItem -Path "$HOME/.agent/skills" -Recurse -Filter "SKILL.md" |
  Select-Object FullName

如果需要输出 Skill 名称和描述，可以写一个只读脚本：

python 复制代码

from pathlib import Path
import re

root = Path("~/.agent/skills").expanduser()

for skill_file in sorted(root.rglob("SKILL.md")):
    text = skill_file.read_text(encoding="utf-8", errors="replace")
    name = re.search(r"^name:\s*(.+)$", text, re.M)
    desc = re.search(r"^description:\s*(.+)$", text, re.M)
    print("FILE:", skill_file)
    print("NAME:", name.group(1).strip() if name else "<missing>")
    print("DESC:", desc.group(1).strip() if desc else "<missing>")
    print()

运行：

bash 复制代码

python ./scripts/list_skills.py

盘点时重点看：

有没有同名 Skill。
有没有缺少 name 或 description 的 Skill。
有没有旧版本和新版本同时存在。
有没有只下载了一半的目录。
有没有脚本、模板或文档引用了不存在的文件。

第二步：判断插件列表为什么不等于 Skill 列表

如果界面里插件数量很少，不代表本地 Skill 很少。原因通常有三类：

插件是分发单位，Skill 是工作流单位。一个插件可能带多个 Skill，本地用户目录也可能有不属于插件的 Skill。
UI 可能只显示可管理的插件，不显示所有直接放在 Skill 目录下的用户 Skill。
Skill 列表为了节省上下文，可能只加载 name、description 和路径，不把所有文档都展开显示。

因此，排查"为什么看不到我装的 Skill"时，应该按下面顺序：

bash 复制代码

find ~/.agent/skills -name SKILL.md

然后检查每个 SKILL.md 的 front matter，再重启或刷新 Agent 客户端。是否支持热加载，需要根据具体客户端确认。

第三步：安装社区 PPT Skill

如果使用公开社区 Skill，可以先用 Git 克隆。这里用占位仓库地址表示通用流程：

bash 复制代码

mkdir -p ~/.agent/skills/community
git clone <COMMUNITY_SKILL_REPO_URL> ~/.agent/skills/community/codex-ppt

如果仓库很大，只需要其中一个目录，可以用 sparse checkout。具体命令是否可用取决于 Git 版本。

bash 复制代码

git clone --filter=blob:none --sparse <COMMUNITY_SKILL_REPO_URL> ./skill-repo
cd ./skill-repo
git sparse-checkout set skills/codex-ppt
cp -r skills/codex-ppt ~/.agent/skills/community/codex-ppt

如果 Git 访问失败，可以考虑使用 GitHub Repository Contents API 读取公开目录。下面是通用示例，不要把真实 token 写进命令历史或文章。

bash 复制代码

curl -L \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/<OWNER>/<REPO>/contents/<PATH_TO_SKILL>"

如果访问私有仓库，需要鉴权。鉴权方式、token 权限和安全策略必须根据实际环境确认。

第四步：检查社区 Skill 是否可信

安装第三方 Skill 前，不要只看 stars 或截图，至少检查四项：

是否有 SKILL.md。
是否有许可证，是否允许使用、修改和再发布。
是否包含脚本，脚本会不会读取敏感文件、上传本地文件、执行危险命令。
是否要求 API key，密钥读取方式是否只通过环境变量或安全配置。

可以先列出目录结构：

bash 复制代码

find ~/.agent/skills/community/codex-ppt -maxdepth 3 -type f

检查是否有潜在危险命令：

bash 复制代码

grep -RInE "(rm -rf|curl .*\\|.*sh|Invoke-WebRequest|Start-Process|subprocess|os\\.system)" ~/.agent/skills/community/codex-ppt

这个命令只用于初筛。是否危险不能只靠正则判断，还需要人工阅读上下文。

第五步：写一个主控 PPT Skill

主控 Skill 的作用不是替代所有工具，而是做判断、调度和验收。下面是一份可公开复用的 ppt-master 示例骨架。

markdown 复制代码

---
name: ppt-master
description: Create, rewrite, beautify, polish, repair, route, QA, and export PPT, PowerPoint, slide decks, presentations, defense decks, report decks, course decks, roadshow decks, 高颜值PPT, 答辩PPT, 汇报PPT, or .pptx files.
---

# PPT Master

## Core Principle

Act as a presentation director, not a slide filler. A good deck needs a clear argument, controlled information density, a deliberate visual system, editable PowerPoint objects when required, and rendered QA before delivery.

## Tool Choice

- Default to editable PPTX when the user needs later revision, defense use, course/project reporting, engineering review, tables, charts, or line-by-line editing.
- Use image-based PPTX only when the user explicitly accepts full-slide image pages or asks for an image-first, poster-like, keynote-style, highly visual deck.
- If an image-based PPT Skill is available, treat it as a visual-generation companion. Keep this main skill responsible for brief, narrative, route choice, QA, and final delivery judgment.
- Do not use full-slide screenshots or image-only pages when the user requires every textbox, chart, table, and label to remain editable.

## Required Workflow

1. Define the brief: audience, goal, occasion, tone, slide count, language, output format, source files, and constraints.
2. Build the narrative chain before designing slides.
3. Lock a visual system: size, palette, typefaces, grid, chart style, icon/photo style, and citation style.
4. Write a slide-by-slide storyboard with role, main message, evidence, layout intent, visual plan, and editable-object plan.
5. Choose editable PPTX, image-based PPTX, or hybrid PPTX.
6. Generate one sample or first draft when the route is risky.
7. Render every slide and inspect overflow, contrast, alignment, spacing, crops, hierarchy, and missing sources.
8. Deliver only after the output exists, is non-empty, has the expected slide count, and limitations are documented.

## Route Tests

- "做答辩 PPT，后续我要自己改" -> editable PPTX.
- "做一份视觉冲击强的演讲稿，整页图片也可以" -> image-based PPTX.
- "美化已有 PPT，但保留可编辑" -> editable PPTX, images only as assets.
- "先给我看一页效果" -> sample slide first, wait for confirmation before full deck.

这份骨架的关键不是"写得长"，而是把边界写清楚。尤其要写明什么时候不能用图片式流程，否则高颜值 Skill 很容易误伤需要可编辑的场景。

第六步：整理图片式 PPT Skill 的工作流

以公开的图片式 PPT Skill 思路为例，一个比较稳的流程是：

读取资料，明确主题、受众、页数和约束。
先产出 outline.md，让用户确认每页内容。
确认视觉方向，例如科研风、手绘解释风、咨询风、仪表盘风。
确认图片生成后端，例如内置图片工具或 API fallback。
生成一页代表性样张，等待确认。
样张通过后，再生成每页图片。
记录每页状态，例如 pending、generated、accepted、blocked。
写讲稿或 speaker notes。
使用脚本把图片组装成 PPTX。
检查每页是否有截断、错字、风格漂移、素材缺失和比例问题。

对应目录可以这样设计：

text 复制代码

./ppt-project/
├── outline.md
├── deck_spec.json
├── speech.md
├── slide_jobs.json
├── slide_run_state.json
├── origin_image/
│   ├── slide_01.png
│   ├── slide_02.png
│   └── slide_03.png
└── output/
    └── deck.pptx

这些文件的职责：

outline.md：用户确认过的页面大纲。
deck_spec.json：主题、页数、风格、生成后端、样张方式等结构化配置。
slide_jobs.json：每一页的生成任务。
slide_run_state.json：每一页当前状态，避免只靠聊天记录判断进度。
origin_image/：最终进入 PPT 的逐页图片。
speech.md：讲稿或备注。
output/deck.pptx：最终交付文件。

这套状态文件并不是所有项目都必须照抄，但"任务状态要落盘、最终结果要可验证"这个原则很重要。

第七步：处理中英文混杂问题

Skill 名称、描述和文档语言可能来自不同来源：系统内置 Skill 常用英文，社区 Skill 可能用英文或中文，用户自定义 Skill 可能混合中英文触发词。界面中出现中英文混杂通常不是编码错误，而是 Skill 元数据本身就是混合语言。

整理方式有三种：

方案	做法	适用场景	注意点
保留英文`name`，扩展中文 `description`	`name` 用稳定英文，description 写中英文触发词	推荐做法，兼顾稳定和中文触发	不要把 description 写成无边界长文
新增中文说明段	在正文中写"中文使用说明"	面向中文用户的本地 Skill	不影响机器识别时，主要提升可读性
改成中文`name`	Skill 名称直接中文化	少量本地私用 Skill	可能带来兼容和输入不便问题，需要按客户端确认

推荐保留英文短名，例如 ppt-master、codex-ppt，同时在 description 中加入 做PPT、生成PPT、美化PPT、答辩PPT、汇报PPT 等中文触发词。

关键代码与命令解析

1. Skill 元数据检查脚本

下面脚本检查 SKILL.md 是否包含 name 和 description，并检测重名 Skill。

python 复制代码

from collections import defaultdict
from pathlib import Path
import re

root = Path("~/.agent/skills").expanduser()
seen = defaultdict(list)

for skill_file in sorted(root.rglob("SKILL.md")):
    text = skill_file.read_text(encoding="utf-8", errors="replace")
    name = re.search(r"^name:\s*(.+)$", text, re.M)
    desc = re.search(r"^description:\s*(.+)$", text, re.M)

    skill_name = name.group(1).strip() if name else ""
    status = []
    if not skill_name:
        status.append("missing name")
    if not desc:
        status.append("missing description")
    if skill_name:
        seen[skill_name].append(skill_file)

    print(f"{skill_file}: {', '.join(status) if status else 'ok'}")

print("\nDuplicate names:")
for skill_name, paths in seen.items():
    if len(paths) > 1:
        print(skill_name)
        for path in paths:
            print(f"  - {path}")

运行：

bash 复制代码

python ./scripts/check_skill_metadata.py

如果出现同名 Skill，不一定要马上删除。应先判断它们来自系统、用户目录还是项目目录，再决定禁用、重命名或保留。某些客户端允许同名 Skill 同时出现，但这会降低人工选择和隐式触发的确定性。

2. 图片式 PPT 最小组装脚本

下面示例用 python-pptx 把 origin_image/slide_XX.png 组装成 16:9 PPTX。它是教学用最小版本，真实项目建议增加图片尺寸检查、备注写入、异常处理和渲染验证。

python 复制代码

from pathlib import Path
from pptx import Presentation
from pptx.util import Inches

image_dir = Path("./origin_image")
output = Path("./output/deck.pptx")
output.parent.mkdir(parents=True, exist_ok=True)

images = sorted(image_dir.glob("slide_*.png"))
if not images:
    raise SystemExit("No slide images found.")

prs = Presentation()
prs.slide_width = Inches(13.333)
prs.slide_height = Inches(7.5)

blank_layout = prs.slide_layouts[6]

for image_path in images:
    slide = prs.slides.add_slide(blank_layout)
    slide.shapes.add_picture(
        str(image_path),
        0,
        0,
        width=prs.slide_width,
        height=prs.slide_height,
    )

prs.save(output)
print(f"saved: {output}")

关键参数：

slide_width、slide_height：控制页面比例。示例使用 16:9 宽屏。
slide_*.png：依赖文件名排序，建议使用 slide_01.png、slide_02.png。
add_picture：把图片铺满页面，因此页面内容不是逐元素可编辑对象。

如果图片比例不是 16:9，强行铺满会导致拉伸。更稳的做法是生成图片前约束尺寸，或在组装前做裁切、留白和尺寸检查。

3. 路由规则配置示例

可以把 PPT 路由写成结构化规则，方便后续维护。

yaml 复制代码

routing:
  editable_pptx:
    priority: default
    use_when:
      - user needs to revise text later
      - deck contains tables, charts, formulas, or detailed labels
      - academic defense, course report, engineering review, data report
      - user asks to beautify an existing deck while preserving editability
    avoid_when:
      - user explicitly accepts full-slide image pages

  image_based_pptx:
    priority: explicit_only
    use_when:
      - user asks for highly visual, poster-like, keynote-style slides
      - user accepts full-slide image pages
      - deck is mainly for display rather than later editing
    avoid_when:
      - every textbox, chart, shape, or table must remain editable
      - source data must be editable inside PowerPoint

  hybrid_pptx:
    priority: ask_before_use
    use_when:
      - cover and section pages need strong visuals
      - content pages need editable text, charts, and tables
    avoid_when:
      - user requires a single consistent editing model

这段配置的重点是 priority：

default：没有额外说明时优先走。
explicit_only：必须用户明确接受才走。
ask_before_use：可以建议，但要先确认。

4. 新对话识别验证

安装或修改 Skill 后，需要验证新对话是否还能识别。可以准备一组回归提示词：

text 复制代码

请做一份答辩 PPT，后续我要自己逐页修改。

预期：选择可编辑 PPTX，不走整页图片流程。

text 复制代码

请做一份高颜值主题演讲 PPT，允许每页都是完整图片。

预期：可以选择图片式 PPT Skill，并说明页面内容不可逐元素编辑。

text 复制代码

请美化已有 PPT，但所有文字和图表必须保留可编辑。

预期：不能使用整页截图或整页图片覆盖。

text 复制代码

先给我生成一页样张，不要直接生成完整 PPT。

预期：只生成样张或样张方案，等待用户确认。

如果这些提示词的路由不稳定，优先修改 description 和主控 Skill 的 Tool Choice，而不是在每次对话中临时纠正。

运行与验证

Skill 安装后至少验证五层。

1. 文件存在

bash 复制代码

test -f ~/.agent/skills/community/codex-ppt/SKILL.md && echo "SKILL.md exists"

PowerShell：

powershell 复制代码

Test-Path "$HOME/.agent/skills/community/codex-ppt/SKILL.md"

2. 元数据可读

bash 复制代码

grep -E "^(name|description):" ~/.agent/skills/community/codex-ppt/SKILL.md

PowerShell：

powershell 复制代码

Select-String -Path "$HOME/.agent/skills/community/codex-ppt/SKILL.md" -Pattern "^(name|description):"

3. 依赖可用

bash 复制代码

python --version
python -c "import pptx; print('python-pptx ok')"

如果 Skill 使用图片生成 API，还要验证环境变量是否存在，但不要打印真实密钥。

bash 复制代码

python - <<'PY'
import os
print("OPENAI_API_KEY configured:", bool(os.environ.get("OPENAI_API_KEY")))
print("OPENAI_BASE_URL configured:", bool(os.environ.get("OPENAI_BASE_URL")))
PY

4. 路由符合预期

用前面的回归提示词分别测试，观察 Agent 是否选对 Skill。验证时不要只看"有没有回答"，要看它是否说明了关键取舍：

可编辑性。
视觉统一性。
后续修改成本。
是否需要样张确认。
是否需要用户提供素材、模板或数据。

5. 输出可验证

对 PPT 输出至少检查：

.pptx 文件存在且非空。
页数符合预期。
每页渲染后无明显遮挡、截断、重叠、错位。
图片式 PPT 的 origin_image/slide_XX.png 全部存在。
可编辑 PPT 的主要文本、图表、表格不是整页截图。
讲稿或备注与页码对应。
引用、图片来源和外部素材使用范围已标注。

常见问题排查

问题	可能原因	排查命令	解决方案
插件界面只有几个，但本地 Skill 很多	插件和 Skill 不是同一层概念	`find ~/.agent/skills -name SKILL.md`	用文件扫描盘点 Skill，不只看插件 UI
Skill 不触发	`description` 太窄、关键词不足或目录未被扫描	`grep -E "^(name	description):" <SKILL_MD_PATH>`
新对话不识别	Skill 放在临时目录、客户端未刷新、路径不在扫描范围	`find ~/.agent/skills -name SKILL.md`	放到用户级或仓库级 Skill 目录，必要时重启客户端
出现两个同名 Skill	用户目录、仓库目录或插件目录都有同名 Skill	运行元数据检查脚本	保留一个主版本，其他改名、禁用或归档
Skill 中英文混杂	元数据来自不同来源，英文 name 搭配中文触发词	查看`name` 和 `description`	保留稳定英文 name，在 description 中加入中文触发词和中文说明
Git 下载失败	网络、代理、DNS、证书、权限或仓库地址问题	`git ls-remote <REPO_URL> HEAD`	检查代理和地址；必要时使用 API 或手动下载
代理配置导致下载异常	Git 全局代理指向不可用服务	`git config --global --get-regexp 'http.*proxy	https.*proxy'`
安装后缺文件	仓库只下载一部分、稀疏检出路径错误	`find <SKILL_DIR> -maxdepth 3 -type f`	重新下载，确认`SKILL.md`、`docs/`、`scripts/` 是否完整
图片式 PPT 无法编辑文字	该路线本来就是整页图片	检查 PPT 中对象类型	改用可编辑 PPTX 路线，或混合使用图片页和可编辑页
可编辑 PPT 视觉弱	使用了保守模板或布局能力不足	渲染检查每页	先做视觉样张，再把风格迁移到可编辑对象
图片式 PPT 文字截断	图片生成时没有控制安全边距	查看每页渲染图	重新生成问题页，提示词中加入边距和字号约束
图片式 PPT 页面顺序错误	图片命名不可排序	`ls ./origin_image`	使用`slide_01.png`、`slide_02.png` 这类命名
API 调用失败	环境变量缺失、base URL 错误、模型名不支持	只检查变量是否存在，不打印真实值	按 Skill 文档配置占位变量，真实密钥放在安全位置
发布文章担心泄密	文中混入真实路径、账号、密钥或截图	执行脱敏扫描	删除敏感内容，改用占位符和通用路径

发布前安全检查

Skill 和教程一旦发布到公开平台，泄露的路径、账号和密钥很难彻底收回。建议发布前执行人工检查和命令检查。

1. 人工检查清单

不包含真实 API key、token、cookie、私钥。
不包含真实姓名、邮箱、手机号、账号、聊天记录。
不包含个人电脑真实绝对路径、公司内部路径或内网地址。
不包含截图里的密钥、用户名、浏览器账号、终端历史。
不包含未授权的私有仓库地址、内部接口、客户资料。
不把第三方开源项目的大段原文复制进文章。
公开引用第三方 Skill 时说明来源、许可证和适用边界。
所有危险操作都写清"需要根据实际环境确认"。

2. 脱敏扫描命令

下面命令只作为初筛，不能替代人工审查。

bash 复制代码

grep -RInE "(API_KEY|token|secret|password|cookie|private_key|BEGIN .* KEY)" ./skills ./docs

扫描疑似本地绝对路径：

bash 复制代码

grep -RInE "([A-Za-z]:\\\\|/Users/|/home/[^/]+/)" ./skills ./docs

扫描疑似邮箱和手机号：

bash 复制代码

grep -RInE "([A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}|[0-9]{11})" ./skills ./docs

如果发现真实密钥已经提交到仓库，只删除文件不够。应立即吊销或轮换密钥，再清理历史记录，并开启 secret scanning 或同类工具。

工程优化建议

1. Skill 命名要稳定

name 建议使用短英文或短横线命名，例如 ppt-master、codex-ppt、doc-polisher。不要用临时名称、个人名称、项目代号或带空格的复杂名称。

稳定命名的好处是：

新对话容易显式调用。
自动化脚本容易扫描。
同步到其他机器时不容易出错。
后续做禁用、升级、迁移时可控。

2. 主控 Skill 不要塞满所有细节

SKILL.md 需要写清主流程和边界，但不适合无限膨胀。可把详细检查项拆到 references/ 或 docs/。

推荐拆分：

text 复制代码

ppt-master/
├── SKILL.md
└── references/
    ├── ppt-quality-checklist.md
    └── image-first-caveats.md

SKILL.md 中只写：

markdown 复制代码

## References

- Read `references/ppt-quality-checklist.md` before final QA.
- Read `references/image-first-caveats.md` before using image-first workflows.

这样既能保留高质量细节，又不会让主入口过长。

3. 把路由测试当成回归测试

每次修改 PPT Skill 后，都用固定提示词测试路由。不要只测试"能不能生成"，还要测试"有没有选对路线"。

text 复制代码

我要答辩 PPT，后续自己改。

text 复制代码

我要视觉冲击强，整页图片可以。

text 复制代码

我要美化已有 PPT，但保留可编辑。

text 复制代码

我只想先看一页样张。

这些提示词可以写进 references/route-tests.md，作为 Skill 维护时的验收清单。

4. 第三方 Skill 先审计再执行

社区 Skill 可能包含脚本。脚本越强，风险越高。建议安装后先只读审计：

bash 复制代码

find ~/.agent/skills/community/codex-ppt -maxdepth 3 -type f

bash 复制代码

grep -RInE "(subprocess|os\\.system|requests|fetch|curl|Invoke-WebRequest)" ~/.agent/skills/community/codex-ppt

如果脚本会上传文件、读取环境变量、执行外部命令或删除文件，必须理解后再使用。不要因为它是 Skill 就默认安全。

5. 可编辑和图片式路线都要写限制

很多 PPT 质量问题不是工具失败，而是交付标准没写清。建议在最终报告中写明：

本次 PPT 是可编辑 PPTX、图片式 PPTX 还是混合 PPTX。
哪些页面或元素不可编辑。
使用了哪些外部素材。
是否写入讲稿或备注。
是否完成渲染检查。
哪些地方需要用户后续确认或替换。

这样用户拿到文件后不会误以为所有内容都能在 PowerPoint 里逐元素修改。

扩展方向

1. 多 Skill 协同

PPT 只是一个例子。同一套管理方法可以扩展到文档润色、论文写作、代码审查、数据分析、网页生成、图片生成等 Skill。关键是让每个 Skill 只负责一个清晰任务，并通过主控 Skill 或路由规则协调。

2. 团队共享

团队可以把项目级 Skill 放在仓库内，例如 ./.agents/skills。这样同一个项目里的成员可以共享一致的发布流程、测试流程、文档规范和 QA 标准。

需要注意：

不要把个人密钥放进仓库。
不要把个人路径写进 Skill。
不要把只适合个人电脑的软件路径写死。
需要说明依赖安装方式和适用系统。

3. 自动化验证

可以为 Skill 增加自动化检查：

检查 SKILL.md 是否存在。
检查 name、description 是否存在。
检查重复名称。
检查引用文件是否存在。
检查是否包含疑似密钥和真实路径。
检查示例命令是否使用占位符。

这些检查不能保证 Skill 一定好用，但能减少低级错误。

4. PPT 质量进一步提升

对于 PPT Skill，可以继续扩展：

建立视觉模板库。
建立常见 deck 结构库，例如答辩、课程汇报、路演、培训。
建立页面 QA 规则，例如最小字号、对比度、留白、安全边距。
建立图片式 PPT 的样张确认机制。
建立可编辑 PPT 的渲染截图回归检查。

这些扩展方向需要根据实际工具链实现，不能在未验证前写成"已经完成"。

总结

Skill 管理的核心流程可以概括为：先盘点，再安装，再审计，再路由，再验证，最后做安全固化。

以 PPT Skill 为例，真正重要的不是"能不能生成 PPT"，而是能否稳定判断用户要的是可编辑 PPTX、图片式 PPTX，还是混合交付。可编辑 PPTX 适合答辩、报告和后续修改；图片式 PPTX 适合视觉展示和整页设计；混合路线适合封面、章节页强调视觉，正文页保留编辑能力。

一个成熟的 PPT Skill 体系应该包含：

清晰的 SKILL.md 元数据。
主控 Skill 和辅助 Skill 的边界。
明确的可编辑/图片式路由规则。
安装后的元数据、依赖和行为验证。
新对话可复现的回归提示词。
发布前脱敏和第三方脚本审计。

能让新对话稳定复现的规则，才算真正工程化。只存在于临时对话里的经验，迟早会丢失；写进 Skill、脚本、参考文档和验证清单里的经验，才会变成可维护的能力。

AI Agent Skill 整理与管理实践：以 PPT Skill 为例讲清安装、识别、路由、排错与安全规范