跳绳鸭
67.76M · 2026-02-04
在 AI 辅助编程的时代，AGENTS.md 已成为开发者向 AI 工具传递项目上下文的重要文件。
然而，随着项目增多，维护多个项目的 AGENTS.md 文件变得愈发困难——重复的知识、分散的更新、难以同步。新的Agent Skills开放标准针对这些问题有很好的解决方案
传统上，开发者会在每个项目中创建 AGENTS.md 文件，用于记录：
在实践中存在三个核心问题：
第一，知识同步成本高。当在 A 项目中发现 AI 生成了错误代码并更新 AGENTS.md 后，相同的问题修复需要手动同步到 B、C、D 项目，维护成本线性增长。
第二，通用知识与项目知识混杂。AGENTS.md 本应聚焦项目特有逻辑，却不得不包含大量通用编程最佳实践（如 Swift Concurrency 使用规范），导致文件臃肿。
第三，缺乏标准化分享机制。即使想开源自己的 AGENTS.md 帮助他人，其格式也不适合直接分享——它天然为项目特定而设计，而非领域通用。
Agent Skills 是一个开放格式（open format），旨在将 AI Agent 的能力模块化、可复用化。官方定义为：
其核心优势在于领域专业知识的封装与复用。你可以将 Swift Concurrency、SwiftUI 架构、代码重构等领域的最佳实践打包成独立 Skill，在所有项目中共享。
一句话总结：AGENTS.md 是项目级知识库，而 Agent Skills 是跨项目、领域级的知识库。
Agent Skills 由三个核心要素构成：
这种结构使 Skill 具备：
Agent Skills 已被广泛采纳：
/skills 命令管理这意味着开发者可以立即投入使用，无需等待生态成熟。
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/ 是知识库层，每篇文档聚焦单一主题，深度讲解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 必须检查：
StrictConcurrency=completenonisolatednonsendingbydefault
**注释说明**：
- 决策树本质是**条件路由表**，将自然语言问题映射到具体文档
- `openskills read` 是 Agent 与 Skill 的**标准交互接口**
- 项目配置检查确保建议**因地制宜**，避免生搬硬套
## Agent 如何使用 Skills：技术实现原理
### 安装与同步机制
Agent Skills 通过 `openskills` CLI 工具管理，其工作流程分为三步：
**步骤 1：安装 Skill**
```bash
# 从 GitHub 安装公开 Skill
openskills install avdlee/Swift-Concurrency-Agent-Skill
技术原理：该命令会：
~/.skills 或项目 .skills）SKILL.md 提取元数据（名称、描述、触发关键词）步骤 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>
技术解析：
priority="1" 确保 Skill 系统被优先评估<description> 是触发器（Trigger），Agent 通过自然语言匹配决定是否调用Bash("openskills read ...") 是标准调用接口，解耦 Agent 与 Skill 实现当用户提问时，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)
关键设计亮点：
Agent Skills 的质量取决于创建者的领域深度。其 Swift Concurrency Skill 的优势源于：
@MainActor）一些开源 Skill 的问题：
问题 1：缺乏深度
# 反例：浅层 Skill
## 使用 async/await
- 用 async 标记异步函数
- 用 await 调用异步函数
这种 Skill 只是语法复述，无法解决实际问题（如线程安全、性能优化）。
问题 2：过度武断
// 反例：强制架构风格
// Skill 建议：所有 ViewModel 必须遵循 MVVM
class MyViewModel: ObservableObject { /* ... */ }
// 但如果用户项目使用 TCA 或 Elm，此建议就是错误的
最佳实践原则：
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 建议精准而非教条。
安装 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. 生成带引用的报告
以下是可直接使用的 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 的设计遵循三大原则：
原则一：关注点分离（Separation of Concerns）
AGENTS.md = 项目特定上下文（如业务逻辑、架构决策）Skill = 领域通用知识（如语言特性、框架最佳实践）原则二：知识的层次化封装
用户提问
↓
意图识别（Agent 通用能力）
↓
Skill 路由（SKILL.md 决策树）
↓
知识检索（References 文档）
↓
答案生成（带引用）
这种分层使知识从扁平文本升级为结构化知识图谱。
原则三：工具无关性（Tool Agnostic）
通过标准化 openskills read 接口，Skill 创建者无需关心 Agent 实现细节。这是类 Unix 哲学：做一件事，做好，并能与其他工具组合。
Agent Skills 本质上是一种手动优化的 RAG 系统：
| 特性 | 传统 RAG | Agent Skills |
|---|---|---|
| 知识组织 | 自动分块，可能不连贯 | 人工结构化，逻辑清晰 |
| 检索方式 | 向量相似度搜索 | 规则/决策树路由 |
| 上下文控制 | 自动注入，可能冗余 | 按需加载，精确控制 |
| 可解释性 | 黑盒，难以追溯 | 显式引用，可审计 |
| 维护成本 | 低（自动化） | 中等（需人工维护） |
| 回答质量 | 一般，可能 hallucinate | 高，专家级深度 |
适用场景：
Agent Skills 不仅是技术工具，更是编程知识管理的范式升级。它解决了 AI 辅助开发中的三个根本矛盾：
通用性与特异性的矛盾
AGENTS.md 试图两者兼顾，结果两头不讨好深度与广度的矛盾
个人与团队的矛盾
AGENTS.md 难以团队协作总结如下实践指南：
对于 Skill 使用者：
openskills update avdlee/Swift-Concurrency-Agent-Skill对于 Skill 创建者：
scripts/ 目录提供验证脚本，如： # scripts/validate-actor-isolation.sh
# 自动扫描 @MainActor 冗余情况
对于团队负责人：
# .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 的双重价值：
真实项目中常需多个 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 可能冲突。解决方案：
<skills_system priority="1"> 控制加载顺序场景一：金融 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")
展望未来，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/…
Swift Concurrency Skill：
Swift Concurrency：
Default Actor Isolation in Swift 6：www.avanderlee.com/concurrency…
Agent Skills 标志着 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 真正理解你的领域，而非仅仅是模式匹配。
