什么是 AI Agent Skill?
基础原理Skill 是一个包含 SKILL.md 指令文件及可选脚本/模板的独立目录。Agent 启动时只加载名称与简短描述,匹配到任务时才按需读取完整指令。
实操建议:相比把所有规范都塞进全局提示词,Skill 能大幅节省上下文窗口并减少模型注意力分散。
Skills 让大模型从“通用聊天助手”变成“懂你工程规范的专家”。这里整理了从概念理解、目录安装到自建调试的完整实操指南。
Skill 是一个包含 SKILL.md 指令文件及可选脚本/模板的独立目录。Agent 启动时只加载名称与简短描述,匹配到任务时才按需读取完整指令。
一个规范的 Skill 至少包含 SKILL.md,复杂技能可附带 scripts/、references/ 或 templates/ 子目录供 Agent 按需调用。
my-skill/
├── SKILL.md # 必需:YAML 元数据 + Markdown 指令
├── scripts/ # 可选:辅助脚本(bash / python)
├── references/ # 可选:补充参考文档
└── examples/ # 可选:标准输出示例将开源 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将团队专属的工作流 Skill 放在代码仓库根目录的约定目录中,随 Git 提交,所有成员拉取代码后即可自动获得一致的 Agent 行为。
your-project/
├── .agents/skills/ # 通用项目级 skills 目录
│ └── deploy-check/
│ └── SKILL.md
└── src/支持在 ~/.gemini/antigravity-cli/skills/ 与 ~/.gemini/config/skills/ 下放置自定义 Skill,并在对话中自动匹配或通过斜杠命令触发。
~/.gemini/antigravity-cli/skills/<skill-name>/SKILL.md
~/.gemini/config/skills/<skill-name>/SKILL.md主流终端与编辑器 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强制 Agent 先写失败测试再实现功能(Red-Green-Refactor),或在提交前按编码规范与需求规格双维度自动审查代码。
规范化“复现问题 → 定位根因 → 验证修复”的诊断闭环,或在调研新技术时强制交叉核对一手文档并输出结构化结论。
YAML 头部的 name 与 description 决定了 Agent 何时激活该 Skill。description 必须写清“做什么”以及“什么场景下使用”。
---
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. 检查所有路由是否返回统一错误结构...