Agent Skills 完全指南：从零开始构建你的 AI 代理技能体系

闹纳尼

757人浏览 · 2026-03-18 13:50:00

闹纳尼 · 2026-03-18 13:50:00 发布

一篇写给开发者的深度博客，涵盖 SKILL.md 架构原理、实战构建方法、生态工具全景，以及从 LangChain 到 Agentica 的框架选型思考

前言：我为什么要写这篇文章

如果你用过 Claude Code，或者任何现代 AI 编码代理，你一定遇到过这样的场景——

你打开一个新对话，开始跟 AI 说："我们的数据库用的是老式 WHERE 连接，不用 ANSI JOIN，字段名是斯洛文尼亚语，业务术语你不认识……"然后花了十分钟解释背景，AI 才勉强进入状态。第二天，重新开一个对话，再来一遍。

这不是 AI 不够聪明，而是它没有"记住你的工作环境"的机制。

Agent Skills（代理技能）就是为了解决这个问题而生的。它让你把这些背景知识、工作流程、代码模板打包成一个模块化的 SKILL.md 文件，AI 在需要的时候自动加载，不需要你每次重复解释。

这篇文章会从原理讲到实战，从 Anthropic 官方的 Claude Skills 讲到 LangChain、OpenSkills、Agentica 等整个生态，帮你建立一套完整的认知框架，并且真正能用起来。

第一章：Agent Skills 到底是什么？

1.1 一个直觉性的比喻

在软件开发里，我们有"库"（Library）这个概念——你不需要每次都从零写排序算法，直接 import 一个现成的就好。

Agent Skills 做的事情类似，只不过它打包的不是代码逻辑，而是AI 的行为模式和专业知识。

你可以把一个 Skill 理解成：

一份给 AI 看的"操作手册"
一套特定场景下的"行为规范"
一个可以随时插拔的"专业模块"

当你告诉 AI “帮我处理这个 PDF 文件”，它会自动去找有没有一个叫 pdf-tools 的技能，加载里面的指令和代码示例，然后按照你预先定义好的方式来处理，而不是每次都即兴发挥。

1.2 技术定义：SKILL.md 是什么

从技术角度看，一个 Agent Skill 的核心是一个 SKILL.md 文件——一个带有 YAML 前置元数据的 Markdown 文件。

它的最简形式长这样：

---
name: pdf-tools
description: Extract text from PDFs using pdfplumber. Use when working with PDF files.
---

# PDF Tools

import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
    print(text)

就这些。这已经是一个完整可用的技能了。

YAML 头部的 name 和 description 是必填字段，其余都是可选的。Markdown 正文可以放任何你想让 AI 知道的内容：代码示例、操作步骤、注意事项、业务术语表……

1.3 渐进式披露：技能架构的核心设计思想

理解 Agent Skills 的关键，是理解"渐进式披露"（Progressive Disclosure）这个概念。

AI 的上下文窗口是有限的。如果你把所有知识都塞进一个对话，很快就会超出限制，而且大量无关内容会干扰 AI 的判断。

渐进式披露的思路是：按需加载，而不是全量加载。

具体来说，技能的加载分三个层次：

第一层：元数据（始终加载）
只有 name 和 description，几十个字符。AI 在每次对话开始时都会读取所有技能的元数据，用来判断"这个任务需要用哪个技能"。

第二层：SKILL.md 正文（按需加载）
当 AI 判断某个技能与当前任务相关时，才会加载完整的 SKILL.md 内容。这里包含主要的指令、代码示例和操作流程。

第三层：引用文件（按需加载）
如果 SKILL.md 里引用了其他文件（比如 AUTH.md、REFERENCE.md），AI 只有在真正需要那部分内容时才会去读取。

这个设计非常优雅。它让你可以构建非常丰富的技能包，而不用担心撑爆上下文窗口。

用一个更形象的比喻：SKILL.md 就像一本书的目录，你不需要把整本书背下来，只需要知道"第三章讲认证，第五章讲错误处理"，需要的时候翻到对应章节就好。

1.4 技能 vs. MCP：别搞混了

很多人会把 Agent Skills 和 MCP（Model Context Protocol）混淆，这里简单区分一下。

MCP 是一个通信协议，解决的是"AI 如何调用外部工具和服务"的问题。它更像是一个 API 接口规范，让 AI 能够实时调用数据库、文件系统、外部 API 等。

Agent Skills 是一个知识打包格式，解决的是"AI 如何携带专业知识和行为规范"的问题。它更像是一个配置文件或操作手册，告诉 AI 在特定场景下应该怎么做。

两者并不互斥，实际上可以很好地配合使用：MCP 提供工具调用能力，Skills 提供使用这些工具的最佳实践和业务知识。

第二章：从零开始构建你的第一个技能

2.1 最简单的起点

不要被"技能"这个词吓到。你的第一个技能可以非常简单。

先创建一个目录结构：

~/.claude/skills/my-first-skill/
└── SKILL.md

然后写一个最基础的 SKILL.md：

---
name: my-coding-style
description: Personal coding style guide. Use when writing Python code for this project.
---

# My Coding Style

- 使用 4 空格缩进
- 函数名用 snake_case
- 类名用 PascalCase
- 所有函数必须有 docstring
- 优先使用 f-string 而不是 .format()

就这样，你已经有了一个技能。当你让 AI 帮你写 Python 代码时，它会自动遵循这些规范，不需要你每次重复说明。

2.2 写好 description 是最重要的事

很多人在构建技能时把大量精力放在正文内容上，却忽视了 description 字段——而这恰恰是最关键的部分。

AI 是通过 description 来决定"这个技能是否与当前任务相关"的。如果描述写得太模糊，AI 就不知道什么时候该用它；如果描述太宽泛，AI 可能在不该用的时候也加载它，浪费上下文。

一个好的 description 应该包含三个要素：

它能做什么（功能描述）
什么时候用它（触发条件）
关键词（帮助 AI 匹配用户意图）

来看几个对比：

❌ 太模糊，没用：

description: Helps with files
description: Does database stuff
description: Utility functions

✅ 清晰有效：

description: Extract text from PDFs using pdfplumber. Use when working with PDF files, forms, or document extraction.

description: Connect to Oracle database, extract PL/SQL packages with old-style SQL syntax. Use for Oracle database operations or PL/SQL code extraction.

description: Analyze Excel spreadsheets, create pivot tables. Use when working with .xlsx files or tabular data.

注意最后一点：用第三人称写作。写"Extract text from PDFs"而不是"I can extract text"或"You can use this to extract text"。Claude 的系统提示用的是第三人称，混用人称会造成混淆。

2.3 正文内容的写作原则

SKILL.md 的正文是给 AI 看的，不是给人看的。这意味着你要用 AI 最容易理解的方式来组织内容。

核心原则：简洁优先

AI 已经知道 PDF 是什么，知道 Python 的基本语法，知道什么是 REST API。你不需要解释这些基础知识，直接给代码、给步骤、给规范就好。

❌ 浪费上下文的写法：

## Extract PDF text

PDF stands for Portable Document Format. It's a file format developed by Adobe in 1992 
for presenting documents. PDFs can contain text, images, forms, and more. To extract 
text from a PDF, you'll need to use a specialized library. There are many options 
available in Python, such as PyPDF2, pdfplumber, and PyMuPDF. We recommend pdfplumber 
because it's actively maintained...

✅ 高效的写法：

## Extract PDF text

import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

Claude 已经知道 PDF 是什么了。把代码贴出来，继续下一步。

目标：主 SKILL.md 文件保持在 500 行以内。 如果内容更多，用引用文件来扩展（后面会讲）。

2.4 用渐进式披露扩展技能

当你的技能内容越来越多，单个 SKILL.md 文件会变得臃肿。这时候就需要用到渐进式披露的文件引用机制。

目录结构变成这样：

~/.claude/skills/api-client/
├── SKILL.md          # 主文件，包含快速入门和文件引用
├── AUTH.md           # 认证相关详细文档
├── LIMITS.md         # 速率限制说明
├── ERRORS.md         # 错误处理指南
└── EXAMPLES.md       # 完整示例集合

SKILL.md 的写法：

# API Client

## Quick Start
[基础代码示例]

## Advanced Topics

需要认证？见 [AUTH.md](AUTH.md)
遇到速率限制？见 [LIMITS.md](LIMITS.md)
错误处理？见 [ERRORS.md](ERRORS.md)

这样，Claude 只有在用户问到认证相关问题时才会去读 AUTH.md，其他时候不会加载，节省了大量上下文。

有一个重要的注意事项：保持引用层级只有一层深。

❌ 不要这样：

SKILL.md → advanced.md → details.md → actual_info.md

✅ 应该这样：

SKILL.md → auth.md, limits.md, errors.md, examples.md

嵌套太深的话，Claude 有时候只会部分读取文件，导致信息丢失。保持扁平结构，从 SKILL.md 直接引用所有子文件。

如果某个引用文件超过 100 行，在文件顶部加一个目录：

# API Reference

## Contents
- [Authentication](#authentication)
- [Endpoints](#endpoints)
- [Error Codes](#error-codes)

---

## Authentication
[...]

这帮助 Claude 在只读取部分文件时也能快速定位需要的内容。

2.5 添加可执行脚本

对于更复杂的技能，你可以在技能目录里放实际可执行的代码文件。

~/.claude/skills/db-toolkit/
├── SKILL.md
├── reference.md
├── usage-examples.md
├── sql-syntax-guide.md
├── troubleshooting.md
└── scripts/
    └── oracle_toolkit_standalone.py

在 SKILL.md 里引用这个脚本：

## Setup

The toolkit script is at `scripts/oracle_toolkit_standalone.py`.

from pathlib import Path
import sys

skill_dir = Path.home() / '.claude' / 'skills' / 'db-toolkit'
sys.path.insert(0, str(skill_dir / 'scripts'))

from oracle_toolkit_standalone import OracleToolkit

关键点是：把所有依赖都内嵌在技能包里，不要依赖外部路径。这样技能可以在任何环境下工作，不会因为路径问题失效。

2.6 打包你的技能

技能完成后，需要按照正确的目录结构打包成 ZIP 文件才能上传。

✅ 正确结构：

我的技能.zip
└── 我的技能/
    ├── SKILL.md
    └── 资源/

❌ 错误结构：

我的技能.zip
└──（文件直接位于 ZIP 根目录）

注意：ZIP 文件里必须有一个顶层目录，不能把文件直接放在 ZIP 根目录下。

2.7 测试你的技能

上传前的自检清单：

SKILL.md 的 description 是否清晰准确？
描述是否准确反映了 Claude 应该在什么时候使用这个技能？
所有引用的文件是否都存在于正确的位置？
用几个示例提示测试一下，确保 Claude 能正确识别并调用它

上传后的验证步骤：

尝试几种不同的提示，应该能触发这个技能
查看 Claude 的思路，确认它正在加载技能
如果 Claude 在预期情况下没有使用技能，迭代更新 description

第三章：实战案例——解决一个真实的遗留数据库问题

这个案例来自一位真实开发者的经历，他处理的是一个极其复杂的 Oracle 数据库：1048 个 PL/SQL 包，20913 个存储过程，所有业务术语用斯洛文尼亚语，SQL 语法是 1995 年风格（只用 WHERE 连接，不用 ANSI JOIN）。

每天他都要跟 Claude 重复解释这些背景，直到他构建了两个技能解决了这个问题。

3.1 为什么是两个技能而不是一个

最初的想法是把所有内容放进一个大技能。但他最终选择了分成两个：

db-toolkit：技术层面——如何连接数据库、提取代码、执行查询
business-domain：业务层面——表名的含义、业务流程、斯洛文尼亚语术语表

分开的理由很实际：这两类知识的变化频率不同。数据库操作方式几乎不变，但业务知识会随着业务发展持续更新。分开维护更方便，而且有时候只需要加载其中一个，节省上下文。

这个思路值得记住：按变化频率和使用场景来拆分技能，而不是按内容量来拆分。

3.2 db-toolkit 的完整结构

~/.claude/skills/db-toolkit/
├── SKILL.md              # 687行（超过推荐的500行，但有充分理由）
├── reference.md          # 所有方法的API文档
├── usage-examples.md     # 10+个真实场景示例
├── sql-syntax-guide.md   # 老式SQL语法示例
├── troubleshooting.md    # 常见错误处理
└── scripts/
    └── oracle_toolkit_standalone.py

SKILL.md 超过了推荐的 500 行，但作者认为值得——因为里面包含了用户可以直接复制使用的工作流程检查清单，这些内容不能拆分到其他文件里。

3.3 让技能真正好用的四个关键设计

设计一：复制粘贴检查清单

对于复杂的多步骤工作流，在技能里提供一个检查清单，让 Claude 在执行过程中逐项勾选：

Copy this checklist:

Task Progress:
- [ ] Connect to database
- [ ] Extract package body
- [ ] Validate extraction (check line count)
- [ ] Copy to working directory
- [ ] Make changes
- [ ] Run tests

这个设计非常实用。用户可以清楚地看到进度，Claude 也有了明确的执行框架，不容易遗漏步骤。

设计二：立即验证每个操作

每个操作完成后立刻验证结果，并提供具体的修复建议：

pkg = await toolkit.extract_source('MY_SCHEMA', 'PKG_EXAMPLE', 'PACKAGE BODY')

if not pkg['success']:
    print("❌ Failed:", pkg['message'])
    print("🔄 Try these fixes:")
    print("  • Check package name spelling")
    print("  • Use 'PACKAGE BODY' not 'PACKAGE'")
    print("  • Verify schema owner is correct")
    return

# 验证提取质量
if pkg['line_count'] < 10:
    print("⚠️  Suspiciously small extraction - double check")

不要等到最后才发现问题。每一步都验证，出错了立刻给出可操作的修复建议。

设计三：技能之间相互引用

db-toolkit 在需要业务上下文时提到 business-domain，business-domain 在需要数据库操作时提到 db-toolkit。Claude 会自动判断什么时候需要同时加载两个技能。

设计四：嵌入所有依赖

所有依赖的 Python 脚本都放在技能目录的 scripts/ 子目录里，通过相对路径引用：

from pathlib import Path
skill_dir = Path.home() / '.claude' / 'skills' / 'db-toolkit'
sys.path.insert(0, str(skill_dir / 'scripts'))
from oracle_toolkit_standalone import OracleToolkit

这样技能在任何机器上都能工作，不依赖外部环境配置。

3.4 最终结果

经过几周的迭代优化：

✅ 100% 符合 Anthropic 最佳实践
✅ 14 个测试中通过 12 个（85.7% 通过率）
✅ 每周节省大约 10 小时的重复解释时间
✅ 跨会话稳定工作

这个案例最有价值的地方不是技术细节，而是思路：把你的工作流程、业务知识、操作规范系统化地打包成技能，让 AI 真正融入你的工作环境，而不是每次都从零开始。

第四章：常用设计模式

在构建了足够多的技能之后，一些通用的设计模式会浮现出来。这里整理了几个最实用的。

4.1 模板模式（Template Pattern）

当你需要 AI 输出固定格式时，直接在技能里定义模板：

## Report Format

ALWAYS use this structure:
# [Title]
## Summary
[One paragraph]

## Findings
- Finding 1
- Finding 2

## Recommendations
[Actionable next steps]

这个模式适用于：周报、代码审查报告、技术文档、API 文档等任何需要统一格式的输出。

4.2 词汇表模式（Glossary Pattern）

当你的项目有大量专业术语或领域特定词汇时：

## Domain Glossary

- skondi_spis: claim file (保险理赔文件)
- zavarovanec: insured person (被保险人)
- premija: premium (保费)
- škoda: damage/loss (损失/赔付)

## Naming Conventions
- All table names use Slovenian terms
- Column names follow pattern: [entity]_[attribute]
- Procedure names use verb_noun format

这让 AI 在处理你的代码时能正确理解业务含义，而不是把斯洛文尼亚语当成乱码。

4.3 约束模式（Constraints Pattern）

当你的环境有特殊限制时，明确列出禁止事项：

## Hard Rules

- NEVER use ANSI JOIN syntax (INNER JOIN, LEFT JOIN, etc.)
- ALWAYS use WHERE clause joins: WHERE a.id = b.id
- NEVER use modern SQL features (CTEs, window functions)
- ALWAYS validate extraction line count > 100
- NEVER modify production tables directly

这比"请用老式 SQL 语法"这种模糊指令有效得多。

4.4 工作流模式（Workflow Pattern）

对于多步骤的复杂任务，提供明确的执行流程：

## Standard Extraction Workflow

1. Connect to database using toolkit
2. Verify connection: check schema access
3. Extract package: use PACKAGE BODY type
4. Validate: line_count > 100, no error messages
5. Save to working directory
6. Create backup copy
7. Make requested changes
8. Run syntax validation
9. Test in dev environment
10. Report results with line count comparison

配合检查清单使用效果更好，让 AI 和用户都清楚当前进行到哪一步。

4.5 条件分支模式（Conditional Pattern）

当不同情况需要不同处理方式时：

## File Type Handling

If .xlsx file:
  → Use openpyxl for reading
  → Preserve formatting when writing
  
If .csv file:
  → Use pandas with encoding='utf-8-sig'
  → Handle BOM characters
  
If .json file:
  → Validate structure first
  → Use indent=2 for output

第五章：Agent Skills 生态全景

Agent Skills 不只是 Claude 的专属功能，它已经发展成一个跨平台的生态标准。让我们看看整个生态的全貌。

5.1 支持技能的平台

根据目前的生态现状，以下平台都已经支持 Agent Skills：

Anthropic 官方

Claude Code（claude.ai/code）：Anthropic 的编码工具，技能支持的发源地，文档最完整

OpenAI 阵营

OpenAI Codex：OpenAI 的 CLI 代理，已支持技能格式

Google 阵营

Gemini CLI：终端中的 Gemini，带有技能支持

编辑器和 IDE

Cursor：集成原生技能的 AI 编辑器
VS Code：通过 GitHub Copilot 支持 Agent Skills
GitHub Copilot：具有 Agent Skills 支持的代码助手
Roo Code：VS Code 扩展，集成了技能

其他平台

Mistral Vibe：Mistral 的 CLI 编码代理
Manus：自主 AI 代理，支持代理技能
OpenCode：AI 开发工具，内置技能支持
Amp：AI 编码助手，支持 Agent Skills

这个列表说明了一件重要的事：SKILL.md 正在成为 AI 代理能力扩展的事实标准格式，就像 Dockerfile 之于容器化一样。

5.2 即用型技能库

你不需要从零构建所有技能，已经有大量现成的技能库可以直接使用：

官方技能库

Anthropic 官方技能：最权威的参考，包含各类通用技能
OpenAI 技能：OpenAI 官方维护
微软技能：专注于 Azure SDK 和 Microsoft AI Foundry
Google Workspace 技能：Google 生产力工具集成
Vercel 技能：Web 开发最佳实践
Supabase 技能：Supabase 数据库操作
Hugging Face 技能：ML/AI 相关技能

社区技能集合

Agent-Skills-for-Context-Engineering：上下文工程专项
AI-research-SKILLs：AI/ML 研究技能
pm-skills：项目管理技能

技能市场

agentskill.sh：44k+ 技能目录，双层安全扫描
SkillsMP：发现和分享技能的市场
Skillstore：精选技能市场
skills.sh：技能目录和排行榜

5.3 开发者工具

围绕技能开发，已经出现了一批专门的工具：

SkillCheck（安全扫描器）

npm install @agentigy/skillcheck
npx skillcheck .claude/skills/my-skill.md

SkillCheck 会扫描你的 SKILL.md 文件，检测以下安全问题：

硬编码密钥：API keys、tokens、passwords（CRITICAL 级别）
命令注入：不安全的 shell 命令执行（CRITICAL 级别）
权限提升：sudo、chmod 777 等危险操作（CRITICAL 级别）
路径遍历：../ 序列、未验证的用户路径（HIGH 级别）
信息泄露：SSH 密钥、数据库连接字符串等（HIGH 级别）

它还支持 SARIF 格式输出，可以集成到 GitHub Code Scanning：

npx skillcheck --format sarif . > results.sarif

OpenSkills（通用技能加载器）

OpenSkills 解决了一个很实际的问题：如果你同时使用 Claude Code 和其他 AI 代理，每个平台都有自己的技能加载方式，维护起来很麻烦。

OpenSkills 提供了一个统一的安装和加载接口：

# 安装 Anthropic 官方技能库
npx openskills install anthropics/skills

# 同步技能
npx openskills sync

# 从任意 GitHub 仓库安装
npx openskills install your-org/your-skills

# 从本地路径安装
npx openskills install ./local-skills/my-skill

它生成的 <available_skills> XML 格式与 Claude Code 完全兼容，任何能读取 AGENTS.md 的代理都可以使用。

对于多代理环境，可以使用 --universal 模式，把技能安装到 .agent/skills/ 而不是 .claude/skills/，避免与 Claude 的插件市场冲突：

npx openskills install anthropics/skills --universal

第六章：框架视角——LangChain 如何实现技能模式

如果你在构建自己的 AI 代理框架，而不只是使用现成的工具，LangChain 提供了一个很好的参考实现。

6.1 LangChain 中的技能模式

在 LangChain 的架构里，技能被实现为一种特殊的工具（Tool），代理可以按需调用来加载专业化的提示和上下文。

from langchain.tools import tool
from langchain.agents import create_agent

@tool
def load_skill(skill_name: str) -> str:
    """Load a specialized skill prompt.

    Available skills:
    - write_sql: SQL query writing expert
    - review_legal_doc: Legal document reviewer

    Returns the skill's prompt and context.
    """
    # 从文件或数据库加载技能内容
    skill_content = load_from_storage(skill_name)
    return skill_content

agent = create_agent(
    model="gpt-4.1",
    tools=[load_skill],
    system_prompt=(
        "You are a helpful assistant. "
        "You have access to specialized skills. "
        "Load the appropriate skill when needed."
    ),
)

6.2 技能模式的关键特征

LangChain 文档总结了技能模式的五个核心特征，这对理解整个设计思想很有帮助：

提示驱动的专业化：技能主要通过专业化的提示来定义，而不是通过代码逻辑。这让非技术人员也能创建和维护技能。

渐进式披露：技能根据上下文或用户需求按需激活，而不是全部预加载。

团队分布式开发：不同团队可以独立开发和维护各自的技能，不需要修改核心代理代码。

轻量级组合：技能比完整的子代理更简单，组合起来的开销更小。

引用感知：技能可以引用脚本、模板和其他资源，实现更复杂的功能。

6.3 什么时候用技能模式，什么时候用子代理

LangChain 的文档给出了一个很清晰的判断标准：

用技能模式，当你：

需要一个代理有多种可能的专业化方向
不需要在技能之间强制执行特定约束
不同团队需要独立开发能力

用子代理模式，当你：

需要真正的并行执行
不同任务需要完全隔离的上下文
需要严格的权限控制

常见的技能模式应用场景：编码助手（不同语言或任务的技能）、知识库（不同领域的技能）、创意助手（不同格式的技能）。

6.4 Deep Agents：技能模式的完整实现

LangChain 的 Deep Agents 框架是一个"开箱即用"的代理框架，内置了完整的技能支持：

from deepagents import create_deep_agent

agent = create_deep_agent()
result = agent.invoke({
    "messages": [{"role": "user", "content": "Research LangGraph and write a summary"}]
})

Deep Agents 内置了：

规划工具（write_todos）：任务分解和进度跟踪
文件系统工具（read_file, write_file, edit_file, ls, glob, grep）
Shell 访问（execute）：执行命令（带沙箱）
子代理（task）：委托工作，隔离上下文窗口
上下文管理：对话过长时自动摘要，大输出保存到文件

你也可以自定义：

from langchain.chat_models import init_chat_model

agent = create_deep_agent(
    model=init_chat_model("openai:gpt-4o"),
    tools=[my_custom_tool],
    system_prompt="You are a research assistant.",
)

第七章：更广阔的视角——从 Agentica 看技能的本质

7.1 Agentica：把函数调用推向极致

Agentica 是一个 TypeScript 的 AI 函数调用框架，它的设计理念和 Agent Skills 有一个有趣的对比。

Agentica 的核心主张是：任何能写函数的人都能构建 AI 代理。

import { Agentica, assertHttpController } from "@agentica/core";
import OpenAI from "openai";
import typia from "typia";

import { MobileFileSystem } from "./services/MobileFileSystem";

const agent = new Agentica({
  vendor: {
    api: new OpenAI({ apiKey: "********" }),
    model: "gpt-4o-mini",
  },
  controllers: [
    // 来自 TypeScript 类的函数
    typia.llm.controller<MobileFileSystem>(
      "filesystem",
      new MobileFileSystem(),
    ),
    // 来自 Swagger/OpenAPI 的函数
    assertHttpController({
      name: "shopping",
      model: "chatgpt",
      document: await fetch(
        "https://shopping-be.wrtn.ai/editor/swagger.json",
      ).then(r => r.json()),
      connection: {
        host: "https://shopping-be.wrtn.ai",
        headers: { Authorization: "Bearer ********" },
      },
    }),
  ],
});

await agent.conversate("I wanna buy MacBook Pro");

Agentica 支持三种函数来源：TypeScript 类、Swagger/OpenAPI 文档、MCP 服务器。你把函数准备好，它就变成了 AI 代理。

7.2 Skills vs. Functions：两种不同的抽象层次

对比 Agent Skills 和 Agentica 的设计，可以看到两种不同的抽象思路：

Agent Skills（提示驱动）：

核心是 Markdown 文档
面向知识和行为规范的打包
非技术人员也能创建
适合打包"怎么做"的知识

Agentica（函数驱动）：

核心是 TypeScript 函数
面向具体能力的封装
需要编程能力
适合封装"能做什么"的功能

两者并不对立，而是互补的。在一个完整的 AI 代理系统里，你可能既需要 Skills 来提供业务知识和操作规范，也需要 Functions 来提供实际的执行能力。

7.3 IntentKit：云原生的代理团队

IntentKit 代表了另一个方向：不是增强单个代理，而是构建一个协作的代理团队。

IntentKit 的核心特性：
- 云原生：在云端运行，不需要本地资源
- 多代理协作：多个代理可以互相调用
- 自托管：完全控制你的代理基础设施

在 IntentKit 的架构里，技能的概念被扩展了——不只是单个代理的能力模块，而是整个代理团队的专业分工。

这个思路很有启发性：当任务足够复杂，单个代理加载多个技能可能不够，需要多个专业代理协同工作。

第八章：安全性——不能忽视的维度

8.1 技能文件的安全风险

技能文件本质上是给 AI 执行的指令，这带来了一些独特的安全风险。

提示注入：如果技能内容来自不可信来源，攻击者可能通过精心构造的技能内容来操控 AI 的行为。

硬编码凭证：开发者可能不小心把 API 密钥、数据库密码等敏感信息写进技能文件。

危险命令：技能可能包含 sudo、rm -rf、chmod 777 等危险操作，在某些情况下可能造成系统损害。

路径遍历：如果技能里有文件操作，不安全的路径处理可能导致访问到不该访问的文件。

8.2 SkillCheck 的安全扫描规则

SkillCheck 工具提供了系统化的安全扫描，覆盖以下规则：

CRITICAL 级别

SECRET_EXPOSURE_001（硬编码密钥）

检测：AWS keys、API keys、JWT tokens、私钥、GitHub tokens
排除：占位符，如 your_api_key_here、${API_KEY}、XXXX
对应 CWE-798

CMD_INJECTION_001（命令注入）

检测：不安全的 bash、eval()、exec()、os.system() 与用户输入结合
上下文感知：当附近有验证代码时跳过
对应 CWE-78

PRIV_ESCALATION_001（权限提升）

检测：sudo、setuid/setgid、chmod 777、su、pkexec、内核模块加载、Docker socket 访问
上下文感知：当附近有授权检查时跳过
对应 CWE-250

HIGH 级别

PATH_TRAVERSAL_001（路径遍历）

检测：../ 序列、带未验证用户路径的文件操作
上下文感知：当存在 path.resolve() 或验证时跳过
对应 CWE-22

INFO_DISCLOSURE_001（信息泄露）

检测：SSH 密钥、AWS 凭证、.env 文件、/etc/passwd、数据库连接字符串
上下文感知：当有脱敏/过滤代码时跳过
对应 CWE-200

8.3 安全最佳实践

构建技能时的安全建议：

凭证管理：永远不要把真实的 API 密钥或密码写进技能文件。使用环境变量或密钥管理服务，在技能里只写占位符和读取方式：

## Authentication

Load credentials from environment:
api_key = os.environ.get('MY_API_KEY')
# Never hardcode: api_key = "sk-abc123..."

命令执行：如果技能需要执行 shell 命令，明确限制可以执行的命令范围，并验证所有用户输入：

## Allowed Commands

Only execute these pre-approved commands:
- git status, git log, git diff
- python -m pytest
- npm test

Never execute commands with user-provided arguments directly.

文件操作：限制文件访问范围，使用 path.resolve() 防止路径遍历：

import os
from pathlib import Path

def safe_read(user_path: str, base_dir: str) -> str:
    # 解析并验证路径
    full_path = Path(base_dir).resolve() / user_path
    if not str(full_path).startswith(str(Path(base_dir).resolve())):
        raise ValueError("Path traversal detected")
    return full_path.read_text()

定期扫描：把 SkillCheck 集成到 CI/CD 流程里，每次提交都自动扫描：

# .github/workflows/skill-security.yml
- name: Scan Skills
  run: npx skillcheck --fail-on HIGH ./skills

第九章：最佳实践总结

经过前面的深入探讨，这里把最重要的最佳实践整理成一个可以直接参考的清单。

9.1 技能设计原则

保持专注：一个技能解决一类问题。多个专注的小技能，比一个什么都包含的大技能效果更好。

判断标准：如果你的技能 description 里出现了"and"连接两个不同的功能，考虑拆分成两个技能。

描述要精准：description 是技能的"门面"，AI 靠它决定是否加载技能。要具体说明功能、触发条件和关键词，用第三人称写作。

先简单后复杂：先用纯 Markdown 写基础指令，验证有效后再添加脚本和复杂逻辑。不要一开始就过度设计。

按变化频率拆分：技术实现和业务知识分开，快速变化的内容和稳定的内容分开。这样维护成本更低。

9.2 内容写作原则

简洁优先：AI 已经有大量基础知识，不需要你解释 PDF 是什么、Python 是什么。直接给代码、给步骤、给规范。

主文件控制在 500 行以内：超出的内容用引用文件扩展，保持主文件简洁。

引用层级保持一层：SKILL.md 直接引用所有子文件，不要嵌套引用。

长文件加目录：超过 100 行的引用文件，在顶部加目录，帮助 AI 快速定位。

9.3 技能结构原则

嵌入所有依赖：把脚本、配置文件等依赖放在技能目录里，通过相对路径引用，不依赖外部环境。

提供检查清单：对于复杂的多步骤工作流，提供可复制的检查清单，让执行过程可见可追踪。

立即验证：每个操作后立刻验证结果，出错时提供具体的修复建议，而不是等到最后才发现问题。

技能间相互引用：当两个技能经常配合使用时，在各自的文件里互相提及，让 AI 知道什么时候需要同时加载。

9.4 安全原则

不硬编码凭证：API 密钥、密码等敏感信息永远不写进技能文件，使用环境变量。

限制命令范围：如果技能需要执行命令，明确列出允许的命令，验证所有输入。

定期安全扫描：把 SkillCheck 集成到开发流程，自动检测安全问题。

来源可信：只使用来自可信来源的技能，从市场安装时注意查看安全评分。

第十章：未来展望——技能生态的演化方向

10.1 标准化的趋势

从目前的生态发展来看，SKILL.md 正在朝着成为行业标准的方向演化。

Claude Code、OpenAI Codex、Gemini CLI、Cursor、VS Code、GitHub Copilot……越来越多的平台开始支持相同的技能格式。这种趋势一旦形成，会产生强大的网络效应：你为 Claude 构建的技能，可以直接在 Cursor 里用；Anthropic 发布的官方技能，可以通过 OpenSkills 安装到任何支持的平台。

这类似于 Docker 镜像的演化路径——从一个公司的内部格式，到整个行业的标准。