AI Agent Skill 实战指南

2026/3/24

AIAgentSkillLLM

Skill 解决一个问题：通用模型如何获得项目特定知识。

Skill = instructions + scripts + resources

一个 Skill 包含：

  • instructions（SKILL.md）：怎么做的指令
  • scripts（scripts/）：可执行的脚本
  • resources（references/、assets/）：参考资料和模板

一、Claude Code 中的 Skill

存放位置

位置路径作用域
Personal~/.claude/skills/用户所有项目
Project.claude/skills/当前项目
Plugin<plugin>/skills/插件启用时

目录结构

my-skill/
├── SKILL.md          # 必需：指令 + 元数据
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考文档
└── assets/           # 可选：模板、资源

SKILL.md 格式

---
name: deploy
description: 部署到生产环境。当用户提到部署、发布、上线时使用。
allowed-tools: Bash(npm run *), Bash(git *), Read
---

# 部署流程

1. 运行测试：`npm test`
2. 构建：`npm run build:prod`
3. 部署：`rsync -avz dist/ server:/var/www/`

## 坑位
- `/health` 端点数据库挂了也返回 200，用 `/ready` 检查

动态上下文注入

`!`command` 语法在发送给模型前执行：

---
name: pr-review
description: 代码审查
---

## PR 信息
- Diff: !`gh pr diff`
- Commits: !`gh pr view --json commits`

安装社区 Skill

# 添加 marketplace
/plugin marketplace add anthropics/skills

# 安装 skill 包
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

二、主流 Skill 资源

官方资源

资源说明
anthropics/skillsAnthropic 官方 Skill 仓库
agentskills.ioAgent Skills 开放标准文档

anthropics/skills 包含：

  • 文档处理：docx、pdf、pptx、xlsx（Claude 文档功能的底层实现）
  • 开发工具：MCP server 生成、Web 测试
  • 创意应用：艺术、音乐、设计
  • 企业工作流：品牌指南、通信模板

社区市场

平台说明
ClawHubSkill 市场，支持版本管理和搜索
Notion SkillsNotion 官方 Skill

ClawHub 用法：

# 安装 skill
npx clawhub@latest install <skill-name>

跨工具兼容

支持 Agent Skills 标准的工具：

工具Skill 目录
Claude Code.claude/skills/
Cursor.cursor/skills/ 或 .agents/skills/
VS Code Copilot.github/skills/
Gemini CLI.gemini/skills/
OpenAI Codex.codex/skills/

同一个 Skill 可以在多个工具里用。

三、高手技巧

1. 从真实任务提取，不要让 LLM 凭空写

最差的 Skill：让 Claude “帮我写一个部署 Skill”。

最好的 Skill：自己做一遍任务，把纠正点写进去。

你和 Agent 部署了三次，每次都纠正它：
- "先跑测试"
- "用 build:prod 不是 build"
- "检查 /ready 不是 /health"

→ 这些纠正就是 Skill 的核心内容

2. “Gotchas” 是金矿

Skill 里最有价值的是坑位列表：

## 常见陷阱

- `users` 表用软删除，查询必须加 `WHERE deleted_at IS NULL`
- 用户 ID 在数据库叫 `user_id`，auth 服务叫 `uid`，billing API 叫 `accountId`
- 部署后等 30 秒再检查健康状态，服务启动有延迟

经验：每次纠正 Agent 时，顺手更新对应 Skill 的 gotchas。

3. 只写 Agent 不知道的

测试方法：“没有这条指令，Agent 会犯错吗？”

  • 会犯错 → 保留
  • 不会 → 删掉
<!-- ❌ Agent 已经知道 -->
PDF 是一种常见的文件格式...

<!-- ✅ Agent 不知道的 -->
我们的 PDF 都是 GBK 编码，提取时指定 encoding

4. 具体程度匹配脆弱程度

任务类型指令风格
多种方法可行给方向，让 Agent 自己选
只有一种正确方法精确步骤
出错代价高越具体越好
<!-- 灵活任务 -->
检查代码安全性，关注 SQL 注入、XSS、敏感信息泄露

<!-- 脆弱任务 -->
数据库迁移必须按此顺序：
1. python scripts/migrate.py --verify --backup
2. 确认输出包含 "backup created"
3. python scripts/migrate.py --execute

5. 提供默认，不要菜单

<!-- ❌ 选择困难 -->
你可以用 pypdf、pdfplumber、PyMuPDF...

<!-- ✅ 明确默认 -->
用 pdfplumber。扫描件用 pdf2image + pytesseract。

6. 渐进式披露

保持 SKILL.md < 500 行，详细内容放 references/：

deploy/
├── SKILL.md              # 核心流程（200 行）
└── references/
    ├── rollback.md       # 回滚指南（按需加载）
    └── troubleshooting.md # 故障排查（按需加载）

在 SKILL.md 里告诉 Agent 什么时候加载：

部署失败时，阅读 references/troubleshooting.md 诊断问题

四、什么时候需要 Skill？

  • Agent 重复犯同样的错误
  • 你每次都要手动告诉 Agent 同样的信息
  • 团队有多人使用 Agent，需要统一规范

参考资料

📝 文章反馈