Agent Skills：构建可复用 AI 编程知识库的最佳实践在 AI 辅助编程的时代，AGENTS.md 已成为开发

在 AI 辅助编程的时代，AGENTS.md 已成为开发者向 AI 工具传递项目上下文的重要文件。然而，随着项目增多，维护多个项目的 AGENTS.md 文件变得愈发困难——重复的知识、分散的更新、难以同步。新的Agent Skills开放标准针对这些问题有很好的解决方案

AGENTS.md 的痛点与 Agent Skills 的诞生

AGENTS.md 的困境

传统上，开发者会在每个项目中创建 AGENTS.md 文件，用于记录：

项目特定的编码规范
首选的 Swift/SwiftUI 方法
重构策略
Swift Concurrency 使用模式

在实践中存在三个核心问题：

第一，知识同步成本高。当在 A 项目中发现 AI 生成了错误代码并更新 AGENTS.md 后，相同的问题修复需要手动同步到 B、C、D 项目，维护成本线性增长。

第二，通用知识与项目知识混杂。AGENTS.md 本应聚焦项目特有逻辑，却不得不包含大量通用编程最佳实践（如 Swift Concurrency 使用规范），导致文件臃肿。

第三，缺乏标准化分享机制。即使想开源自己的 AGENTS.md 帮助他人，其格式也不适合直接分享——它天然为项目特定而设计，而非领域通用。

Agent Skills 的核心理念

Agent Skills 是一个开放格式（open format），旨在将 AI Agent 的能力模块化、可复用化。官方定义为：

Agent Skills 是一种为 AI Agent 提供新能力和专业知识的开放格式。单个 Skill 可包含指令、脚本和资源文件夹，使 Agent 能更准确地执行特定任务。

其核心优势在于领域专业知识的封装与复用。你可以将 Swift Concurrency、SwiftUI 架构、代码重构等领域的最佳实践打包成独立 Skill，在所有项目中共享。

一句话总结：AGENTS.md 是项目级知识库，而 Agent Skills 是跨项目、领域级的知识库。

Agent Skills 核心概念详解

什么是 Agent Skills？

Agent Skills 由三个核心要素构成：

指令系统（Instructions）：指导 Agent 何时、如何使用该 Skill
参考资源（References）：详细的领域知识文档
可执行脚本（Scripts）：自动化工具或工作流

这种结构使 Skill 具备：

领域专业性：深度覆盖特定技术栈
可复用性：一次创建，多项目使用
工具兼容性：已被 Codex、Gemini、Claude、Cursor 等主流工具支持

技术生态现状

Agent Skills 已被广泛采纳：

Codex CLI：通过 /skills 命令管理
Cursor AI：集成 openskills CLI
Gemini/Claude：原生支持 Skill 格式

这意味着开发者可以立即投入使用，无需等待生态成熟。

实战案例：Swift Concurrency Skill 深度剖析

Skill 结构设计

swift-concurrency/
├── SKILL.md                    # 主技能文件：决策树入口
└── references/
    ├── async-await-basics.md   # async/await 基础语法
    ├── tasks.md                # Task 生命周期、取消机制、优先级
    ├── sendable.md             # 隔离域与 Sendable 协议
    ├── actors.md               # Actor 隔离、全局 Actor、可重入性
    ├── async-sequences.md      # AsyncSequence 与 AsyncStream 模式
    ├── threading.md            # 线程与 Task 对比、挂起点
    ├── memory-management.md    # 循环引用、weak self、隔离析构
    ├── core-data.md            # Core Data 集成模式
    ├── performance.md          # 使用 Xcode Instruments 优化
    ├── testing.md              # 并发代码测试策略
    ├── migration.md            # Swift 6 迁移分步指南
    ├── glossary.md             # 术语与概念词汇表
    └── linting.md              # 严格并发 Lint 规则

结构解析：

SKILL.md 是智能路由层，类似 API Gateway，根据问题类型分发到对应的参考文档
references/ 是知识库层，每篇文档聚焦单一主题，深度讲解
这种分层设计使 Agent 能精准定位所需知识，避免上下文过载

代码示例：决策树实现

SKILL.md 中的决策树是 Skill 的核心智能。以下是一个简化的实现示例：

# Swift Concurrency Skill - 主决策树

## 何时使用该 Skill
当开发者提及以下关键词时激活：
- "Swift Concurrency", "async/await", "actors", "tasks"
- "迁移到 Swift 6"
- "数据竞争" 或 "线程安全"
- "@MainActor", "Sendable"
- "并发代码架构" 或 "性能优化"

## 决策路径

### 1. 刚开始编写异步代码？
```bash
# Agent 执行动作：读取基础文档
openskills read swift-concurrency/references/async-await-basics.md

需要并行操作？→ 读取 tasks.md (async let, TaskGroup)

需要保护共享可变状态？

# 评估项目类型
if 项目使用类（class）管理状态:
    openskills read swift-concurrency/references/actors.md
else:
    openskills read swift-concurrency/references/sendable.md

管理异步操作生命周期？

# 区分结构化并发与流式数据
if 需求是结构化任务管理:
    openskills read swift-concurrency/references/tasks.md
elif 需求是流式数据处理:
    openskills read swift-concurrency/references/async-sequences.md

性能分析与调试？

# 引导使用 Instruments
openskills read swift-concurrency/references/performance.md

项目配置检查清单在应用建议前，Agent 必须检查：

Swift 版本（6.0+？）
是否启用 StrictConcurrency=complete
是否设置 nonisolatednonsendingbydefault
默认 Actor 隔离策略


**注释说明**：
- 决策树本质是**条件路由表**，将自然语言问题映射到具体文档
- `openskills read` 是 Agent 与 Skill 的**标准交互接口**
- 项目配置检查确保建议**因地制宜**，避免生搬硬套

## Agent 如何使用 Skills：技术实现原理

### 安装与同步机制

Agent Skills 通过 `openskills` CLI 工具管理，其工作流程分为三步：

**步骤 1：安装 Skill**
```bash
# 从 GitHub 安装公开 Skill
openskills install avdlee/Swift-Concurrency-Agent-Skill

技术原理：该命令会：

克隆 GitHub 仓库到本地 Skill 存储目录（~/.skills 或项目 .skills）
解析 SKILL.md 提取元数据（名称、描述、触发关键词）
注册 Skill 到全局索引

步骤 2：同步到 AGENTS.md

# 将已安装 Skills 注入项目 AGENTS.md
openskills sync

该命令会自动化修改 AGENTS.md，插入 Skill 引用区块。生成的内容如下：

<skills_system priority="1">

## 可用 Skills

<!-- SKILLS_TABLE_START -->
<usage>
当用户请求任务时，检查以下可用 Skills 是否能更有效完成工作。Skills 提供专业能力和领域知识。

使用方法：
- 调用：Bash("openskills read <skill-name>")
- Skill 内容将加载，包含完成任务的具体指令
- 输出中提供基础目录，用于解析捆绑资源（references/, scripts/, assets/）

使用注意：
- 仅使用 <available_skills> 下列出的 Skills
- 不要调用已加载到上下文的 Skill
- 每次 Skill 调用是无状态的
</usage>

<available_skills>

<skill>
<name>swift-concurrency</name>
<description>'Swift Concurrency 最佳实践、模式和实现的专家指导。使用场景：(1) 提及 Swift Concurrency、async/await、actors 或 tasks，(2) "使用 Swift Concurrency" 或 "现代并发模式"，(3) 迁移到 Swift 6，(4) 数据竞争或线程安全问题，(5) 将闭包重构为 async/await，(6) @MainActor、Sendable 或 Actor 隔离，(7) 并发代码架构或性能优化，(8) 并发相关 Lint 警告（SwiftLint 等）'</description>
<location>project</location>
</skill>

</available_skills>
<!-- SKILLS_TABLE_END -->

</skills_system>

技术解析：

使用 XML 格式是为了兼容不同 Agent 的解析器
priority="1" 确保 Skill 系统被优先评估
<description> 是触发器（Trigger），Agent 通过自然语言匹配决定是否调用
Bash("openskills read ...") 是标准调用接口，解耦 Agent 与 Skill 实现

Agent 的决策流程

当用户提问时，Agent 的内部工作流程如下：

# 伪代码：Agent 决策逻辑
def handle_user_prompt(prompt: str, skills: List[Skill]):
    # 1. 解析用户意图（Embedding + 关键词匹配）
    intent = extract_intent(prompt)
    
    # 2. 遍历可用 Skills，计算相关性得分
    for skill in skills:
        # 匹配 Skill 描述中的关键词
        if skill.description.contains_any(intent.keywords):
            score = calculate_relevance(skill.description, intent)
            if score > THRESHOLD:
                # 3. 动态加载 Skill 上下文
                skill_content = execute_bash(f"openskills read {skill.name}")
                
                # 4. 决策树路由
                decision_path = parse_decision_tree(skill_content.SKILL.md)
                target_doc = decision_path.evaluate(intent)
                
                # 5. 读取具体知识文档
                reference_doc = execute_bash(
                    f"openskills read {skill.name}/references/{target_doc}"
                )
                
                # 6. 生成带引用的回答
                return generate_answer(
                    prompt, 
                    context=reference_doc,
                    citations=[target_doc]  # 引用来源
                )
    
    # 无匹配 Skill，使用通用知识
    return generate_answer(prompt, context=general_knowledge)

关键设计亮点：

延迟加载（Lazy Loading）：Skill 内容在需要时才加载，避免上下文窗口浪费
无状态调用：每次调用都是独立的，Skill 内部无复杂状态管理，降低耦合
可溯源性：Agent 必须明确引用参考文档，实现知识审计

领域专业知识的重要性：Skill 质量的基石

为什么需要领域专家？

Agent Skills 的质量取决于创建者的领域深度。其 Swift Concurrency Skill 的优势源于：

对 Swift 6 新特性的深度理解（如 Default Actor Isolation）
实际项目中的踩坑经验（如不必要的 @MainActor）

反模式：浅层知识与过度设计

一些开源 Skill 的问题：

问题 1：缺乏深度

# 反例：浅层 Skill
## 使用 async/await
- 用 async 标记异步函数
- 用 await 调用异步函数

这种 Skill 只是语法复述，无法解决实际问题（如线程安全、性能优化）。

问题 2：过度武断

// 反例：强制架构风格
// Skill 建议：所有 ViewModel 必须遵循 MVVM
class MyViewModel: ObservableObject { /* ... */ } 
// 但如果用户项目使用 TCA 或 Elm，此建议就是错误的

最佳实践原则：

Skill 应聚焦 "最佳实践" 而非 "个人偏好"
应解决 "How to do it right" 而非 "How I do it"
提供 "配置感知" 能力，根据项目实际设置调整建议

配置感知的实现

Swift Concurrency Skill 会先评估项目配置：

// Skill 决策逻辑示例：评估项目 Swift 版本
func evaluateProjectSettings() -> ConcurrencyStrategy {
    let swiftVersion = readSwiftVersion() // 读取 // swift-tools-version: 6.0
    let concurrencyChecks = buildSettings["SWIFT_STRICT_CONCURRENCY"] // 严格并发设置
    let actorIsolation = buildSettings["SWIFT_DEFAULT_ACTOR_ISOLATION"] // 默认 Actor 隔离
    
    if swiftVersion >= .v6_0 && concurrencyChecks == "complete" {
        // Swift 6 + 完整严格并发检查
        return .swift6Strict
    } else if actorIsolation == "mainActor" {
        // 默认主 Actor 隔离，可省略多余 @MainActor
        return .mainActorDefault
    } else {
        return .legacy
    }
}

// 根据评估结果，Skill 会生成差异化建议
switch evaluateProjectSettings() {
case .swift6Strict:
    // 建议：利用编译时检查，减少运行时保护
    suggest("优先使用 Sendable 和 Actor 隔离，减少 DispatchQueue")
case .mainActorDefault:
    // 建议：移除冗余注解
    suggest("全局已默认 @MainActor，可移除显式标记")
case .legacy:
    // 建议：保守的向后兼容方案
    suggest("逐步迁移，先启用 StrictConcurrency=minimal")
}

这种上下文感知能力使 Skill 建议精准而非教条。

如何使用 Agent Skills：多工具实践

使用 openskills CLI（Cursor AI）

安装 Skill：

# 安装 Swift Concurrency Skill
openskills install avdlee/Swift-Concurrency-Agent-Skill

# 查看已安装 Skills
openskills list

同步到项目：

# 自动更新 AGENTS.md
openskills sync

# 可指定输出文件
openskills sync --output .cursor/agents.md

在对话中使用：

用户：帮我分析当前项目的 Swift Concurrency 使用是否合理  

Agent 内部：
1. 匹配到关键词 "Swift Concurrency" → 触发 swift-concurrency Skill
2. 执行 `openskills read swift-concurrency`
3. 读取 SKILL.md，决策树指向 "analyze-project"
4. 执行分析脚本（如有）
5. 生成带引用的报告

实用 Prompt 示例

以下是可直接使用的 Skill 调用示例：

# 示例 1：检查冗余 @MainActor
"使用 swift-concurrency Skill，找出项目中不必要的 @MainActor 使用"

# 示例 2：后台任务优化
"分析当前项目，识别可移动到后台线程的同步代码，使用 Swift Concurrency 重构"

# 示例 3：迁移辅助
"帮我将文件 NetworkManager.swift 从 GCD 迁移到 Swift Concurrency，使用 Skill 指导"

# 示例 4：性能分析
"使用 Skill 的性能模块，分析 async let 和 TaskGroup 的使用效率"

# 示例 5：Lint 规则
"根据 Skill 的 linting.md，检查项目是否符合严格并发 Lint 规则"

深入原理性分析

Agent Skills 的架构设计哲学

Agent Skills 的设计遵循三大原则：

原则一：关注点分离（Separation of Concerns）

AGENTS.md = 项目特定上下文（如业务逻辑、架构决策）
Skill = 领域通用知识（如语言特性、框架最佳实践）

原则二：知识的层次化封装

用户提问
    ↓
意图识别（Agent 通用能力）
    ↓
Skill 路由（SKILL.md 决策树）
    ↓
知识检索（References 文档）
    ↓
答案生成（带引用）

这种分层使知识从扁平文本升级为结构化知识图谱。

原则三：工具无关性（Tool Agnostic）

通过标准化 openskills read 接口，Skill 创建者无需关心 Agent 实现细节。这是类 Unix 哲学：做一件事，做好，并能与其他工具组合。

与 RAG（检索增强生成）的对比

Agent Skills 本质上是一种手动优化的 RAG 系统：

特性	传统 RAG	Agent Skills
知识组织	自动分块，可能不连贯	人工结构化，逻辑清晰
检索方式	向量相似度搜索	规则/决策树路由
上下文控制	自动注入，可能冗余	按需加载，精确控制
可解释性	黑盒，难以追溯	显式引用，可审计
维护成本	低（自动化）	中等（需人工维护）
回答质量	一般，可能 hallucinate	高，专家级深度

适用场景：

RAG：通用知识、快速原型
Agent Skills：专业领域、生产环境、团队协作

个人见解与总结

核心观点

Agent Skills 不仅是技术工具，更是编程知识管理的范式升级。它解决了 AI 辅助开发中的三个根本矛盾：

通用性与特异性的矛盾
- AGENTS.md 试图两者兼顾，结果两头不讨好
- Skill 将通用知识提取、封装、复用，让项目文件回归本质
深度与广度的矛盾
- 大模型虽有广度，但缺乏领域深度
- Skill 引入人类专家知识，弥补模型能力边界
个人与团队的矛盾
- 个人 AGENTS.md 难以团队协作
- Skill 可版本化、共享、共建，形成团队知识资产

最佳实践建议

总结如下实践指南：

对于 Skill 使用者：

优先使用官方/专家 Skill：如苹果工程师维护的 Swift Skill，比社区版更可靠
定期更新 Skills：openskills update avdlee/Swift-Concurrency-Agent-Skill
小步验证：先让 Skill 分析单个文件，再扩展到整个项目
审查引用：检查 Skill 建议的引用文档，理解其逻辑，而非盲信

对于 Skill 创建者：

聚焦单一领域：一个 Skill 只解决一个问题（如只做并发，不做架构）
编写决策树：SKILL.md 必须是决策指南，而非平铺文档
提供可运行示例：在 scripts/ 目录提供验证脚本，如：

  # scripts/validate-actor-isolation.sh
  # 自动扫描 @MainActor 冗余情况

版本兼容：明确 Skill 支持的 Swift/Xcode 版本范围

对于团队负责人：

建立内部 Skill 市场：将团队编码规范封装为 Skill
CI 集成：在 PR 检查中运行 Skill 分析，如：

  # .github/workflows/ai-review.yml
  - name: Run Swift Concurrency Skill Audit
    run: |
      openskills install team/swift-concurrency-skill
      openskills run audit --skill swift-concurrency --path Sources/

与传统文档的对比

Agent Skills 不是取代文档，而是增强：

- 传统文档：人读 → 理解 → 应用（慢、易错）
+ Agent Skills：Agent 读 → 直接应用 + 人读 → 学习（快、准确）

Skill 的双重价值：

运行时：Agent 实时指导编码
学习时：开发者阅读参考文档，提升技能

扩展场景与创新应用

多 Skill 协同工作

真实项目中常需多个 Skills 协同：

# 复杂场景：重构遗留代码
用户："将这个 VIPER 模块重构为 SwiftUI + Concurrency"

Agent 工作流：
1. 加载 swift-architecture-skill (理解 VIPER)
2. 加载 swiftui-skill (理解 SwiftUI 最佳实践)
3. 加载 swift-concurrency-skill (理解并发迁移)
4. 加载 testing-skill (确保重构后覆盖测试)

协同决策：
- Architecture Skill: "VIPER → TCA 或 MVVM"
- SwiftUI Skill: "使用 @StateObject 和 @EnvironmentObject"
- Concurrency Skill: "将 Interactor 的回调改为 async/await"
- Testing Skill: "为新的 ViewModel 编写异步测试"

最终输出：集成各 Skill 建议的综合重构方案

技术挑战：多 Skill 可能冲突。解决方案：

Skill 优先级：<skills_system priority="1"> 控制加载顺序
冲突仲裁：Agent 需识别矛盾建议，请求人工澄清

企业级应用场景

场景一：金融 App 合规检查

# 创建内部 Skill：financial-compliance-skill
/references
  ├── data-encryption.md      # 数据加密规范
  ├── audit-logging.md        # 审计日志要求
  └── api-security.md         # API 安全标准

# 在 CI 中强制检查
openskills run compliance-check --skill financial-compliance
# 不通过则阻断 PR 合并

场景二：跨平台知识库

# multi-platform-skill.yaml
name: multi-platform-ui
references:
  - shared-state-management.md  # 通用状态管理
  - ios/
      - swiftui-patterns.md
  - android/
      - composable-patterns.md
  - web/
      - react-patterns.md

# Agent 根据项目类型自动路由

场景三：动态 Skill 生成

# 从内部文档自动生成 Skill
def generate_skill_from_docs(doc_path: str):
    # 1. 解析 Markdown 文档
    # 2. 提取决策树（基于标题层次）
    # 3. 生成 SKILL.md
    # 4. 打包为 GitHub 仓库
    pass

# 例如：将团队 Notion 知识库转为 Skill
generate_skill_from_docs("https://notion.so/team-guide")

AI 原生开发工作流

展望未来，Skill 可能成为可交易的编程知识资产：

{
  "skill_marketplace": {
    "swift-concurrency-expert": {
      "author": "Apple Engineer",
      "price": "$9.99/month",
      "metrics": {
        "accuracy": 98.5,
        "adoption": 12000+,
        "reviews": 4.9/5
      },
      "updates": "与 Swift 版本同步发布"
    },
    "rxswift-migration-kit": {
      "author": "ReactiveX Team",
      "price": "Free",
      "purpose": "从 RxSwift 迁移到 Combine/Swift Concurrency"
    }
  }
}

这种模式将人类专家知识与AI 效率结合，创造新的知识经济形态。

参考资料与进一步学习

官方资源

Agent Skills 官网：agentskills.io/home
- 官方规范、示例和工具链
openskills CLI：github.com/numman-ali/…
- Skill 管理命令行工具
Swift Concurrency Skill：
- GitHub：github.com/AvdLee/Swif…

社区资源

Cursor AI 文档：cursor.com/cn
Codex CLI 指南：github.com/openai/code…
AI Development Blog：www.avanderlee.com/ai-developm…

最终总结

Agent Skills 标志着 AI 辅助编程从手工提示工程迈向系统化知识工程。它不仅是文件格式的革新，更是开发范式的进化：

对开发者：从重复教 AI 基础知识，到专注项目逻辑
对团队：从口头规范，到可执行、可验证的知识资产
对社区：从散落博客，到标准化、可组合的专家系统

行动清单

立即开始尝试 Agent Skills：

# 1. 安装 openskills
pip install openskills

# 2. 安装第一个 Skill
openskills install avdlee/Swift-Concurrency-Agent-Skill

# 3. 同步到你的项目
cd your-project
openskills sync

# 4. 在 Cursor/Codex 中提问
"使用 Skill 优化我的并发代码"

# 5. 观察效果，逐步构建自己的 Skills

未来已来，Agent Skills 让 AI 真正理解你的领域，而非仅仅是模式匹配。

学习资料

www.avanderlee.com/ai-developm…

Agent Skills：构建可复用 AI 编程知识库的最佳实践