Agent Skills（智能体技能）
Agent 是智能体，Skills 是技能的意思，Agent Skills（智能体技能）是将专业知识、工作流规范固化为可复用资产的核心工具。
Agent Skills 本质上是一个模块化的 Markdown 文件，能教会 AI 工具（如 XCode、GitHub Copilot、Cursor 等）执行特定任务，且支持自动触发、团队共享与工程化管理，彻底告别重复的提示词输入。
Agent Skills 的本质不是工具，而是：
> 行为规范 + 专业知识 + 使用时机的组合
---
核心形式
- 一个 Skill 就是一个文件夹，里面必须有一个 SKILL.md 文件（包含说明和元数据），可选其他资源文件（如脚本、示例、参考文档）。
- Skill 是一个 Markdown 文件（SKILL.md），用于教 XCode 在特定场景下按你的方式做事。
- 本质是其实就是相当于给 AI 代理发放一本专业手册，AI 不会每次都从零学习，而是根据任务自动调用手册中的知识。
- 简单来说，过去我们用提示词（prompt）教 AI 做事，现在用 Agent Skills 可以把提示词 + 资源打包成可复用、可共享的技能包，更高效、更可靠。
- 层级 1：技能发现 — AI 先读取所有技能的元数据（name 和 description），判断任务是否相关，这些元数据始终在系统提示中。
- 层级 2：加载核心指令 — 如果相关，AI 自动读取 SKILL.md 的正文内容，获取详细指导。
- 层级 3：加载资源文件 — 只在需要时读取额外文件（如脚本、示例），或通过工具执行脚本。
- XCode（Xmingtec）：xcode.xming-tec.com、XCode CLI、Agent SDK。
- VS Code + GitHub Copilot：项目级（.github/skills/）或个人级技能。
- Cursor：项目级（.cursor/skills/）或全局技能，支持从 GitHub 安装。
- 其他：正在扩展中，标准开源在 https://github.com/agentskills/agentskills。
- 团队有自己的代码规范，但 AI 每次都要手动提醒。
- 需要处理 PDF 表单、调试 GitHub Actions 等复杂流程，AI 可能不知道最佳实践。
- 自动触发：AI 根据任务自动加载相关技能，无需手动输入长提示。
- 可复用 & 可共享：一次创建，全团队或社区使用，支持 Git 版本控制。
- 高效利用上下文：采用渐进式披露（progressive disclosure），只加载需要的部分，避免上下文窗口溢出。
- 跨平台：同一个 Skill 可以在 XCode、VS Code Copilot、Cursor 等工具中使用。
---
Agent Skills 的工作原理
Agent Skills 的关键是渐进式披露，分三层加载：
---
支持的工具和环境
目前主要支持：
---
为什么需要 Skills？
普通 AI 代理（如 XCode 或 Copilot）很聪明，但缺少特定上下文时容易出错。例如：
Agent Skills 解决这些问题：
---
核心概念快速理解
| 概念 | 比喻 | 作用 | |------|------|------| | Skill（技能） | 一个独立的瑞士军刀工具或烹饪食谱 | 完成一项特定任务（如写邮件、分析数据）的完整套件。 | | Instruction（指令） | 工具的使用说明书或食谱的步骤 | 告诉 XCode 具体要做什么、如何思考、输出什么格式。 | | Knowledge（知识） | 工具的零件清单或食谱的食材背景资料 | 上传文件（如产品手册、API 文档）作为 Skill 的专属知识库。 | | Tool（工具） | 工具上的特殊配件（如开瓶器） | 定义 Skill 可以调用的外部 API 或函数，用于获取数据或执行操作。 |
---
Skill 的最小结构
my-skill/
└── SKILL.md （唯一必需）
SKILL.md 基本模板:
---
name: your-skill-name
description: What it does and when XCode should use it
---Skill Title
Instructions
Clear, concrete, actionable rules.Examples
Example usage 1
Example usage 2 Guidelines
Guideline 1
Guideline 2
元数据字段
| 字段 | 必填 | 说明 | |------|------|------| | name | 否 | Skill 显示名称，默认使用目录名，仅支持小写字母、数字和短横线（最长 64 字符） | | description | 推荐 | 技能用途及使用场景，XCode 根据它判断是否自动应用 | | argument-hint | 否 | 自动补全时显示的参数提示，如 [issue-number]、[filename] [format] | | disable-model-invocation | 否 | 设为 true 禁止 XCode 自动触发，仅能手动 /name 调用（默认 false） | | user-invocable | 否 | 设为 false 从 / 菜单隐藏，作为后台增强能力使用（默认 true） | | allowed-tools | 否 | Skill 激活时 XCode 可无授权使用的工具 | | model | 否 | Skill 激活时使用的模型 | | context | 否 | 设为 fork 时在子代理上下文中运行 | | agent | 否 | 子代理类型（配合 context: fork 使用） | | hooks | 否 | 技能生命周期钩子配置 |
Skills 支持在内容中插入动态变量：
| 变量 | 说明 |
|------|------|
| $ARGUMENTS | 调用 Skill 时传入的所有参数 |
| $ARGUMENTS[N] | 按索引访问参数，如 $ARGUMENTS[0] |
| $N | 简写方式，如 $0 表示第一个参数 |
| ${XCODE_SESSION_ID} | 当前会话 ID，用于日志、临时文件、关联输出 |
例如：
---
name: session-logger
description: 记录当前会话活动
---请将以下内容写入日志文件：
logs/${XCODE_SESSION_ID}.log
$ARGUMENTS
调用：
/session-logger 用户登录成功
实际会生成会话专属日志记录。
---