企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 框架
• 多智能体
• 工具调用
• Agent 沙箱
• 交互助手
• MCP Clients

Pydantic Deep Agents（简称 pydantic-deep）是一个开源、可自托管的 Claude Code 替代品——一个运行在终端的 AI 编程助手，同时也是一个可二次开发的 Python 框架，底层构建于 Pydantic AI 之上，支持任意模型。它的**技能系统（Skills）**是亮点之一：通过一份份SKILL.md文件把领域知识"打包"，AI 按需加载、渐进式披露，从而在不膨胀系统提示词的前提下，让 Agent 变得"懂行"。

技能系统是什么：用 SKILL.md 给 AI 装"插件" 💡

很多时候你想教 Agent 一些"怎么做"的东西：团队的 Git 规范、审查代码的清单、写测试的习惯……如果把全部内容塞进系统提示词，Token 成本和上下文负担都会爆炸。

技能（Skill）的解法是渐进式披露（progressive disclosure）：

• 每个技能就是一个文件夹，核心是一份 SKILL.md；
• Agent 平时只看到每个技能的一行摘要（YAML frontmatter 里的description）；
• 当任务真正匹配时，才调用工具加载完整指令，并进一步读取技能附带的资源文件。

一句话：技能多放不心疼，用哪个才付哪个的 Token 成本。

SKILL.md 格式：一个文件定义一个技能

一个标准技能目录长这样：

my-skill/ ├── SKILL.md # 必需：frontmatter + 指令正文 ├── template.md # 可选：资源文件（模板、清单等） └── example.py # 可选：示例/可执行脚本

SKILL.md由两部分组成：开头的 YAML frontmatter（元数据）和 Markdown 正文（给 Agent 看的指令）。frontmatter 字段如下：

一个最小可用的技能示例：

--- name: api-design description: Design RESTful APIs following best practices version: 1.0.0 tags: - api - rest --- # API Design Skill 你是一名 API 设计专家。设计 API 时遵循以下原则： ## REST 约定 - 资源用名词：/users、/orders - 正确使用 HTTP 方法：GET、POST、PUT、DELETE - API 版本化：/v1/users ## 输出格式 始终返回结构一致的 JSON……

⚠️ 校验规则（见 pydantic_deep/features/skills/directory.py）：name缺失会跳过该技能；正文建议不超过 500 行，超出的内容拆成资源文件，正是渐进式披露的本意。

技能目录下还可以放两类"附加物"：

• 资源文件（Resources）：.md、.json、.yaml、.csv、.xml、.txt等文本文件，按需读取；
• 脚本（Scripts）：技能根目录或scripts/子目录下的.py文件，Agent 可执行它完成计算或处理数据。

四步按需加载：Agent 如何使用技能 🔧

技能工具集 SkillsToolset 会给 Agent 注册 4 个工具，构成一条清晰的调用链：

Agent 的典型工作流：收到任务 →list_skills发现候选 →load_skill读取完整指令 → 按指令执行 → 需要模板时再read_skill_resource。

在 CLI 交互界面中，输入/skills命令即可打开技能面板，查看全部已加载技能及描述（实现见 apps/cli/modals/skills_view.py），确认哪些技能已生效非常直观。

技能放哪里：三级加载优先级

CLI 启动时会按固定顺序自动扫描技能目录（逻辑见 apps/cli/agent.py）：

1. 内置技能：随 CLI 一起发布的 apps/cli/skills/；
2. 用户级技能：~/.pydantic-deep/skills/（跨项目通用）；
3. 项目级技能：项目根目录下.pydantic-deep/skills/（仅当前项目）；
4. 显式覆盖：--skills-dir参数指定的目录，优先级最高。

同名技能后者覆盖前者；若只是内容完全相同的重复，则静默跳过。

内置10个实战技能逐个解析 📦

CLI 自带的 10 个技能覆盖了日常开发的高频场景（源码见 apps/cli/skills/，框架内置副本在 pydantic_deep/bundled_skills/）：

以 code-review 技能 为例，它的正文是一份审查清单：正确性（逻辑错误、边界条件）、安全（注入、硬编码密钥）、性能（N+1 查询、内存占用）、风格（命名、函数长度）、测试覆盖，并规定输出格式为**File:line** — 类别 — 描述 — 建议修复。这正是"把专家经验写成可执行指令"的典型示范。

动手创建你的第一个技能 ✍️

第 1 步：建目录

mkdir -p ~/.pydantic-deep/skills/deploy-checklist

第 2 步：编写SKILL.md（frontmatter + 分步骤指令 + 输出格式示例）

第 3 步（可选）：把模板、清单等拆成独立资源文件放在同目录

第 4 步：在 CLI 里输入/skills确认已加载，直接说"按部署清单检查这个项目"即可。

写作建议（官方文档 docs/concepts/skills.md 总结）：

• ✅ 名称清晰：deploy-checklist，而非deploy2；
• ✅ 一个技能只做好一件事；
• ✅ 指令要具体可执行："发现安全问题时，注明文件行号、描述漏洞、给出修复示例"；
• ✅ 附上期望输出格式的示例；
• ✅ 用version跟踪变更（1.1.0加清单项，2.0.0破坏性变更）。

进阶：在框架中集成技能与 Workspace 技能 🔌

如果你在写自己的 Agent 应用，用create_deep_agent传入技能目录即可（完整示例见 examples/skills_usage.py 和 docs/examples/skills.md）：

from pydantic_deep import create_deep_agent agent = create_deep_agent( skill_directories=[ {"path": "~/.pydantic-deep/skills", "recursive": True}, ], )

更进阶的是Workspace 技能：技能不必放在宿主机，可以跟着 Agent 的"工作区"走——Docker 容器、沙箱会话或内存文档里的skills/文件夹，用 WorkspaceSkillsDirectory 声明即可，脚本会在同一工作区内执行，与 Agent 看到相同的文件和环境：

from pydantic_deep import DockerWorkspace, WorkspaceSkillsDirectory, create_deep_agent agent = create_deep_agent( workspace=DockerWorkspace(runtime="python-minimal"), skill_directories=[WorkspaceSkillsDirectory(path="skills")], )

两种来源还可以混用：本机技能目录 + 工作区技能一起挂载，本地技能作为基础、项目专属技能在沙箱内覆盖。

常见问题 FAQ ❓

Q：技能会一直占用上下文吗？不会。默认提示词中只注入技能名和一行描述，完整指令由load_skill按需拉取，且首次加载后在 Agent 实例生命周期内缓存。

Q：资源文件可以读技能目录之外的文件吗？不可以。路径解析后会校验是否仍在技能目录内，符号链接逃逸会被拦截并跳过（见 pydantic_deep/features/skills/directory.py 中的安全校验）。

Q：技能放多了会拖慢启动吗？目录扫描发生在 Agent 创建时，深度默认 3 层（max_depth可调）。建议只指向确有技能的目录，或直接用SkillsToolset(skills=[...])预加载对象，跳过磁盘扫描。

总结

Pydantic Deep Agents 的技能系统用一份SKILL.md就把"领域知识注入 Agent"这件事变得极其简单：frontmatter 定义元数据，正文定义指令，资源文件承载模板，脚本承载执行。渐进式披露让技能"多放免费、用时付费"，而code-review、systematic-debugging、verification-strategy等 10 个内置技能则展示了如何把工程经验沉淀成可复用的资产。把团队规范写成技能，你的终端 AI 助手从此"人随项目走"。🚀

• 人工智能
• AI Agent
• Agent 框架
• 多智能体
• 工具调用
• Agent 沙箱
• 交互助手
• MCP Clients