PrivateGPT Skills 入门指南：用 SKILL.md 快速打造可版本管理的 AI 专属人设

PrivateGPT Skills 入门指南：用 SKILL.md 快速打造可版本管理的 AI 专属人设

【免费下载链接】privateGPTComplete API layer for private AI applications on local models: RAG, skills, tools, MCP, text-to-sql, and more. Works with any OpenAI-compatible inference server.项目地址: https://gitcode.com/GitHub_Trending/pr/privateGPT

PrivateGPT 是一个面向本地模型的完整 API 层，支持 RAG、工具、MCP 与 text-to-sql 等能力。其中Skills（技能）功能让你用一个SKILL.md文件就能打包出可复用、可版本管理的 AI 专属人设——无需反复复制系统提示词，改一次人设，所有挂载它的对话同步生效。本文带你从零理解 Skills 机制，到 5 分钟创建并升级你的第一个 AI 人设。

什么是 Skills？一句话讲透

把 Skill 想象成一份"岗位说明书"：你写好一份SKILL.md，告诉 AI 它是谁、该怎么做事，然后把它挂在任意一次模型请求上。它有三个核心特点：

• 可复用：一份人设定义，挂到无数个对话或集成中，不用重复写系统提示词
• 有版本：Skill 创建后不可修改，更新只能新增版本，旧版本依然可用，不会破坏已上线的集成
• 有边界：每个 Skill 属于一个collection（团队/工作区标识），天然做多租户隔离

💡 适合场景：法务审查员、销售运营助手、代码评审专家……任何需要"固定人设 + 固定话术"的 AI 助手。

SKILL.md 长什么样？3 分钟读懂标准格式

一个 Skill 的核心就是一个 Markdown 文件，由YAML 前置元数据（frontmatter）+正文指令两部分组成：

--- name: legal-reviewer description: 用于法律文档审查，总是标记缺失条款和模糊表述 allowed-tools: web_search file_read --- 你是法律文档审查员。请始终检查： 1. 是否缺少关键条款 2. 是否存在模糊或歧义语言

前置元数据中的关键字段：

解析规则由 parser.py 严格校验：frontmatter 缺失或 YAML 不合法会直接报错，name含连续连字符也会被拒绝——格式规范保证了版本管理的可靠性。

创建你的第一个 Skill：一条 API 搞定

启动 PrivateGPT 服务后（默认端口 8080），用一条curl就能创建：

curl -X POST http://localhost:8080/v1/skills \ -F 'display_title=Legal Reviewer' \ -F 'collection=my-org' \ -F 'skill_md=# Legal Reviewer\n\nYou are a legal document reviewer.'

四个关键字段值得记住：

• display_title：给人看的名字
• collection：作用域，通常是团队或工作区标识
• skill_md：内联的SKILL.md内容
• loading：lazy（默认）或eager，决定指令何时注入对话

对应的 API 路由定义在 skill_router.py，支持 multipart 表单上传，也可以附带技能目录里的其他文件。

版本管理：更新人设，不破坏集成

这是 Skills 相比"写死系统提示词"最大的优势。Skill创建后不可变（immutable）——想改人设？新增一个版本即可：

curl -X POST http://localhost:8080/v1/skills/skill_01abc.../versions \ -H "Content-Type: application/json" \ -d '{"skill_md": "# Legal Reviewer v2\n\n更新后的指令..."}'

• 固定引用旧版本的集成继续用旧版，互不干扰
• 引用"最新版本"的集成自动升级
• 每个版本独立存储（版本实体定义见 skill_entities.py），天然可回溯

📌 来源为anthropic或zylon的只读技能不可删除，保护了官方预置人设的完整性。

加载模式：lazy 与 eager 怎么选？

Skill 挂载到对话时有两种加载策略：

• lazy（延迟加载，默认）：指令按需注入，省 token，适合工具型、场景型技能
• eager（即时加载）：对话一开始就注入完整人设，适合"整个会话都要保持人设"的场景，比如客服角色

系统还支持maximum_loaded_skills参数，限制单个对话同时加载的技能数量，超出时自动淘汰最早加载的技能，防止上下文被多个技能"挤爆"（见 input_models.py）。

幕后机制：技能如何安全进入模型环境

你可能好奇：模型是怎么"看到"技能文件的？

SkillLoader 会把每个技能以只读文件夹的形式挂载到沙箱路径/mnt/skills/{name}/，内容从对象存储按需拉取；一旦升级版本，就是全新路径 + 全新内容，旧版本物理隔离（实现见 skill_loader.py）。这保证了：

1. 技能文件对模型只读，防止"人设自我修改"
2. 多版本并存不互相污染
3. 本地存储可切换为 S3，支持分布式部署

常见问题 FAQ

Q：Skill 和工具（Tools）有什么区别？Skill 是"人设 + 工作流指令"，回答 AI"你是谁、怎么做"；Tool 是 AI 可调用的能力函数。Skill 还可以用allowed-tools限定自己能用的工具。

Q：能挂多少个技能到一个对话？没硬性上限，但受上下文窗口和maximum_loaded_skills限制，建议 1–3 个为宜。

Q：在哪里看完整 API 文档？官方 Skills API 指南：skills.mdx；API 参考：api-reference.mdx

快速上手清单

• 准备一份带 YAML frontmatter 的SKILL.md（name全小写）
• POST /v1/skills创建技能，指定collection
• 在对话请求中挂载技能 ID
• 人设不满意？POST /v1/skills/{id}/versions新增版本，永远别"原地改"

从一份SKILL.md开始，你就可以为本地私有 AI 打造专属、可控、可版本管理的 AI 人设了。更多 Skills 进阶用法，可参考 技能服务实现 与 技能路由。

【免费下载链接】privateGPTComplete API layer for private AI applications on local models: RAG, skills, tools, MCP, text-to-sql, and more. Works with any OpenAI-compatible inference server.项目地址: https://gitcode.com/GitHub_Trending/pr/privateGPT