返回首页AI Agent Skills 指南
Antigravity · Claude Code · Codex · 通用 SKILL.md 规范

如何给 AI Agent 安装与使用 Skills

Skills 让大模型从“通用聊天助手”变成“懂你工程规范的专家”。这里整理了从概念理解、目录安装到自建调试的完整实操指南。

什么是 AI Agent Skill?

基础原理

Skill 是一个包含 SKILL.md 指令文件及可选脚本/模板的独立目录。Agent 启动时只加载名称与简短描述,匹配到任务时才按需读取完整指令。

实操建议:相比把所有规范都塞进全局提示词,Skill 能大幅节省上下文窗口并减少模型注意力分散。

标准 Skill 目录结构

目录规范

一个规范的 Skill 至少包含 SKILL.md,复杂技能可附带 scripts/、references/ 或 templates/ 子目录供 Agent 按需调用。

目录结构示例
my-skill/
├── SKILL.md          # 必需:YAML 元数据 + Markdown 指令
├── scripts/          # 可选:辅助脚本(bash / python)
├── references/       # 可选:补充参考文档
└── examples/         # 可选:标准输出示例
实操建议:保持 SKILL.md 精简,把冗长的 API 手册或示例拆到 references/ 中按需读取。

通过 Git Clone 安装到全局目录

推荐方式

将开源 Skill 仓库克隆到本地,或直接把单个 Skill 文件夹复制到对应 Agent 的全局 skills 目录即可生效。

终端命令示例
# 1. 克隆包含 skills 的仓库
git clone https://github.com/your-org/agent-skills.git ~/.agent-skills-repo

# 2. 软链接单个 skill 到目标目录(便于后续 git pull 更新)
ln -s ~/.agent-skills-repo/tdd ~/.claude/skills/tdd
实操建议:使用软链接(ln -s)可以在多款 Agent 之间共享同一份 Skill,更新也只需 pull 一次。

项目级本地安装(团队共享)

团队协作

将团队专属的工作流 Skill 放在代码仓库根目录的约定目录中,随 Git 提交,所有成员拉取代码后即可自动获得一致的 Agent 行为。

项目级目录示例
your-project/
├── .agents/skills/        # 通用项目级 skills 目录
│   └── deploy-check/
│       └── SKILL.md
└── src/
实操建议:适合沉淀项目特有的部署规范、代码评审清单或数据库迁移流程。

Antigravity (agy CLI)

全局 + 内置

支持在 ~/.gemini/antigravity-cli/skills/ 与 ~/.gemini/config/skills/ 下放置自定义 Skill,并在对话中自动匹配或通过斜杠命令触发。

Antigravity 默认路径
~/.gemini/antigravity-cli/skills/<skill-name>/SKILL.md
~/.gemini/config/skills/<skill-name>/SKILL.md
实操建议:安装后无需重启复杂配置,新开会话即可在可用 Skills 列表中被识别。

Claude Code / Codex / Cursor

生态通用

主流终端与编辑器 Agent 均已兼容 SKILL.md 规范,分别扫描各自用户目录下的 skills/ 或项目根目录的 .agents/skills/。

常见路径参考
# Claude Code
~/.claude/skills/<skill-name>/SKILL.md

# Codex / 通用 .agents 规范
~/.codex/skills/<skill-name>/SKILL.md
./.agents/skills/<skill-name>/SKILL.md
实操建议:如果同时使用多款工具,建议统一维护在 ~/.agents/skills/,再软链接到各工具目录。

工程实践类:TDD & Code Review

高频必备

强制 Agent 先写失败测试再实现功能(Red-Green-Refactor),或在提交前按编码规范与需求规格双维度自动审查代码。

实操建议:在复杂重构或修 Bug 前显式要求 Agent 启用 tdd 或 code-review,能明显降低回归风险。

排查与调研类:Diagnosing Bugs & Research

效率提升

规范化“复现问题 → 定位根因 → 验证修复”的诊断闭环,或在调研新技术时强制交叉核对一手文档并输出结构化结论。

实操建议:遇到偶现 Bug 或性能退化时,使用诊断类 Skill 可避免 Agent 盲目猜错并乱改代码。

编写高质量 SKILL.md Frontmatter

核心技巧

YAML 头部的 name 与 description 决定了 Agent 何时激活该 Skill。description 必须写清“做什么”以及“什么场景下使用”。

SKILL.md 最小模板
---
name: api-error-audit
description: Audit REST API handlers for consistent error codes and logging. Use when adding or modifying backend endpoints.
---

# API Error Audit
1. 检查所有路由是否返回统一错误结构...
实操建议:写完后可以开一个新对话,故意用自然语言描述相关需求,测试 Agent 是否能准确触发该 Skill。