Skip to content

LeoYeAI/agent-master-skills / skills/agent-skill-reviewer

skill-reviewer

Verified

审核/审查 Skill 代码质量的专业工具。当用户说"检查 skill"、"审核 skill"、"review {名称} skill"、"skill 写得怎么样"、"帮我看看这个 skill 有什么问题"时使用。依据 Anthropic 官方指南进行结构验证、YAML 前置信息检查、描述质量评估、指令完整性审查,并输出详细的问题报告和改进建议。

references/official-guide-summary.md

View on GitHub
# Anthropic 官方 Skills 开发指南 - 精简参考

> **注意**:这是精简版,用于快速查阅常用规范。
> 完整指南请参考:`anthropic-skills-development-guide.md`

---
## YAML 前置信息规范

### 必填字段

```yaml
---
name: skill-name-in-kebab-case
description: 它做什么以及什么时候用。包含具体的触发短语。
---
```

### 可选字段

```yaml
license: MIT                          # 开源协议
allowed-tools: "Bash(python:*) WebFetch"  # 限制工具访问
compatibility: Requires network access    # 运行环境需求(1-500 字符)
metadata:
  author: Company Name
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]
```

### 安全限制

**禁止:**
- XML 尖括号(`<` `>`)
- 以 "claude" 或 "anthropic" 开头的技能名

---

## Description 字段最佳实践

### 格式模板

`[能做什么] + [什么时候用] + [主要功能]`

### 好的写法 ✅

```
# 具体且可操作
description: 分析 Figma 设计文件并生成开发者交接文档。
  当用户上传 .fig 文件,或者问"设计规格"、"组件文档"、
  "设计转代码交接"时使用。

# 包含触发词
description: 管理 Linear 项目工作流,包括冲刺规划、任务创建和状态追踪。
  当用户提到"冲刺"、"Linear 任务"、"项目规划",
  或者要求"创建工单"时使用。

# 价值主张清晰
description: PayFlow 的端到端客户引导工作流。
  处理账户创建、支付设置和订阅管理。
  当用户说"引导新客户"、"设置订阅"或"创建 PayFlow 账户"时使用。
```

### 差的写法 ❌

```
# 太模糊
description: 帮助处理项目。

# 没有触发条件
description: 创建复杂的多页文档系统。

# 太技术化
description: 实现具有层次关系的 Project 实体模型。
```

---

## 文件夹结构

```
your-skill-name/
├── SKILL.md              # 必须
├── scripts/              # 可选
│   ├── process_data.py
│   └── validate.sh
├── references/           # 可选
│   ├── api-guide.md
│   └── examples/
└── assets/               # 可选
    └── report-template.md
```

### 命名规则

**文件夹名:**
- ✅ kebab-case:`notion-project-setup`
- ❌ 空格:`Notion Project Setup`
- ❌ 下划线:`notion_project_setup`
- ❌ 大写:`NotionProjectSetup`

**SKILL.md:**
- ✅ `SKILL.md`(精确,区分大小写)
- ❌ `skill.md`, `SKILL.MD`, `skill-guide.md`

---

## 主体指令最佳实践

### 推荐结构

```markdown
# 你的技能名称

## 指令

### 第 1 步:[第一个主要步骤]
清楚说明这步要做什么。

示例:
```bash
python scripts/fetch_data.py --project-id PROJECT_ID
```
预期输出:[描述成功时应该看到什么]

### 第 2 步:[下一步骤]

## 示例

### 示例 1:[常见场景]
用户说:"设置一个新的营销活动"
操作:
1. 通过 MCP 获取现有活动
2. 用提供的参数创建新活动
结果:活动创建成功,附上确认链接

## 故障排查

错误:[常见错误消息]
原因:[为什么会出现]
解决方法:[怎么修]
```

### 组织原则(重要)

**按任务组织,而非按概念:**

✅ 好的组织方式:
```
## 编码和解码
## 检查字符
## 转换格式
## 批量处理
```

❌ 差的组织方式:
```
## 理论概述
## 基本概念
## 高级主题
## 背景介绍
```

**常见操作应该优先:**
- 基础用法 → 变体 → 高级 → 边界情况
- 不要:配置说明 → 理论背景 → 最后才是基础用法

---

### 写作模式

**✅ 要具体,要说清楚怎么操作:**
```
运行 `python scripts/validate.py --input {filename}` 来检查数据格式。
如果验证失败,常见原因有:
- 缺少必填字段(把它加到 CSV 里)
- 日期格式不对(要用 YYYY-MM-DD)
```

**❌ 别含糊其词:**
```
继续之前请先验证数据。
```

**✅ 要包含错误处理:**
```
## 常见问题

### MCP 连接失败
看到 "Connection refused" 时:
1. 确认 MCP 服务器在运行:检查 设置 > 扩展
2. 确认 API 密钥有效
3. 尝试重连:设置 > 扩展 > [你的服务] > 重新连接
```

**✅ 要用渐进式引用:**
```
写查询之前,请先看 `references/api-patterns.md`,里面有:
- 速率限制指南
- 分页模式
- 错误码和处理方式
```

### 示例密度指南

**参考目标:每 5-30 行 1 个代码块**

| 密度 | 评价 |
|------|------|
| 5-30 行/块 | 理想范围 |
| 3-5 行/块 | 略高,可能是短命令集或碎片化 |
| 30-40 行/块 | 略低,考虑增加示例 |
| >40 行/块 | 严重不足,文字太多 |
| <3 行/块 | 过高,可能过于碎片化 |

**说明:**
- 长代码示例(完整函数、配置块)自然会拉高行数,这是合理的
- 短命令集(如 CLI 参数列表)密度高也是正常的
- 多命令速查类型技能(如 cheat sheet)密度可能更高
- 关键是避免大段文字无任何示例

**示例质量检查清单:**
- [ ] 语言标签正确(```bash, ```python 等)
- [ ] 语法正确,命令可执行
- [ ] 展示了预期输出或结果说明
- [ ] 使用真实值(非 foo/bar/baz)
- [ ] 无占位符(TODO, FIXME, xxx)
- [ ] 自包含或有设置说明

### 可执行性指南

**核心问题:Agent 能否按照这些指令产生正确结果?**

**祈使句 vs 建议句:**

✅ 好的写法(祈使句):
```
运行 X 命令
创建 Y 文件
验证 Z 配置
如果失败,检查...
```

❌ 差的写法(建议句):
```
你可以考虑运行 X
建议创建 Y
可能需要验证 Z
最好检查一下...
```

**步骤顺序:**
- 前置条件必须在行动之前说明
- 不要假设用户已经知道某些信息

**错误处理:**
- 说明失败时怎么做
- 提供具体的错误消息和解决方法

**结果描述:**
- 说明如何验证成功
- 展示预期输出样例

---

## Tips/技巧部分编写指南

Tips 部分是技能的精华,编码了示例无法传达的专业知识。

### 推荐结构

```markdown
## 技巧

- **最重要的原则** — 为什么它最关键,不遵守会怎样。

- **常见陷阱** — 具体说明陷阱是什么,如何避免。

- **性能优化** — 具体的优化技巧,有前后对比更好。

- **工具匹配** — 检查 requires 与实际使用是否匹配。

- **最佳标准** — 你自己会收藏使用吗?
```

### 好的 Tips ✅

```
- **Description 最重要** — 它占实际影响力的 40% 以上。完美的 skill 配上糟糕的 description 也不会被找到。

- **先数代码块** — 少于 8 个代码块的 skill 几乎总是过于抽象而无用。

- **Makefile 头号陷阱** — 缩进必须用 Tab,不能用空格。

- **使用 flock 防止 cron 任务重叠执行** — 具体工具 + 具体场景。

- **按任务组织 vs 按概念组织** — 这是最关键的结构质量差异。
```

### 差的 Tips ❌

```
- 确保测试你的代码 — 太笼统,没有信息量
- 小心并发执行 — 不够具体,没有说明怎么小心
- 阅读官方文档 — 推卸责任,不是实用技巧
- 保持代码简洁 — 正确的废话
```

### 评分标准(8 分)

| 维度 | 分值 | 说明 |
|------|------|------|
| 5-10 条技巧 | 2 分 | 少于 5 条覆盖不足,多于 10 条不够精炼 |
| 非显而易见 | 2 分 | 不能是常识或正确的废话 |
| 具体可执行 | 2 分 | 有具体工具、方法或场景 |
| 不矛盾主体 | 1 分 | 不能与主体指令冲突 |
| 覆盖陷阱 | 1 分 | 针对特定主题的踩坑点 |

---

## 渐进式披露

三层结构:

1. **第一层(YAML 前置信息)**
   - 每次都会加载到系统提示
   - 内容精简:~100 词
   - 让 Claude 知道"做什么、什么时候用"

2. **第二层(SKILL.md 正文)**
   - 任务相关时加载
   - 理想 <500 行
   - 500-600 行:给出提醒,不扣分
   - 超过 600 行:需要精简
   - 保持聚焦

3. **第三层(references/)**
   - 按需加载
   - 无限制
   - 详细文档放这里

### 组织模式

按领域组织多框架技能:
```
cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md
```

---

## 故障排查指南

### 技能不触发

**症状:** 技能从来不自动加载

**解决:** 修改 description 字段

**自查清单:**
- 描述是不是太笼统?("帮助处理项目"不够用)
- 有没有用户可能实际说的触发词?
- 如果涉及文件类型,有没有提到?

**调试技巧:**
问 Claude:"你什么时候会用 [技能名] 这个技能?"
Claude 会引用 description 里的内容。

---

### 技能触发太频繁

**症状:** 技能在不相关的查询里也出现了

**解决方法:**

1. 加负触发词:
```
description: 用于 CSV 文件的高级数据分析,适合统计建模、回归、聚类分析。
  不要用于简单数据探索(请改用 data-viz 技能)。
```

2. 描述更具体:
```
# 太宽泛
description: 处理文档

# 更好
description: 处理 PDF 法律文件以供合同审查
```

---

### 指令没有被遵守

**常见原因及解决:**

1. **指令太冗长**
   - 保持简洁
   - 多用列表和编号
   - 详细参考文档移到单独文件

2. **关键指令被埋没**
   - 重要内容放在最前面
   - 用 `## 重要` 或 `## 关键` 这样的标题
   - 关键点可以重复

3. **语言模糊**
```
# 不好
确保正确验证相关内容

# 好
关键:在调用 create_project 之前,必须确认:
- 项目名称非空
- 至少分配了一个团队成员
- 开始日期不在过去
```

4. **模型"偷懒"**
```
## 执行说明
- 请花足够时间彻底完成
- 质量比速度更重要
- 不要跳过验证步骤
```

---

## 上下文太大/响应变慢

**原因:**
- SKILL.md 内容太多
- 同时启用的技能太多
- 所有内容都加载了,没有用渐进式披露

**解决方法:**

1. 精简 SKILL.md
   - 详细文档移到 `references/`
   - 用链接引用而非内联
   - SKILL.md 尽量控制在 5,000 词以内

2. 减少同时启用的技能数量
   - 超过 20-50 个就要考虑精简
   - 建议按需选择性启用

---

## 完整技能示例

```markdown
---
name: document-creator
description: 创建专业格式的文档(DOCX、PPTX、XLSX)。
  当用户说"创建文档"、"生成报告"、"制作幻灯片"、
  "导出 Excel"或上传模板文件时使用。
---

# Document Creator

## 工作流程

### 第 1 步:确认需求
- 文档类型(DOCX/PPTX/XLSX)
- 内容主题
- 格式要求

### 第 2 步:创建文档
运行创建脚本:
```bash
python scripts/create_docx.py --title "报告标题" --content "内容"
```

### 第 3 步:输出
保存文档并提供下载链接

## 示例

### 示例 1:创建 Word 文档
用户说:"帮我创建一个项目报告文档"
操作:
1. 确认报告标题和章节
2. 运行创建脚本
3. 输出 DOCX 文件

## 故障排查

### 文档创建失败
原因:Python 环境缺失依赖
解决:`pip install python-docx`
```

---

*本文档基于 Anthropic 官方 Skills 开发指南精简整理*
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall