review-skills

审查技能

根据长度、意图范围和触发模式方面的最佳实践，审查并分析一项技能。

前提条件

分析前，请阅读以下资源，了解技能编写原则：

1. ./references/skill-creator/SKILL.md - 核心原则、结构和渐进式披露
2. references/spec.md - 完整的 Agent Skills 规范（合规性检查必需）
3. references/validate.md - 验证清单（在步骤 2 中使用）
4. ./references/skill-creator/references/workflows.md - 工作流模式（如相关）
5. ./references/skill-creator/references/output-patterns.md - 输出模式（如相关）

Anthropic 参考示例（必需）

分析前，必须阅读 Anthropic 仓库中的参考技能。这对于校准审查至关重要。

1. 确保缓存可用：检查 ./.cache/anthropics-skills/ 是否存在。如果不存在（或已过期），运行：

   python scripts/download_anthropics_skills.py
   

2. 至少阅读 3 个参考技能：分析前，请阅读 ./.cache/anthropics-skills/skills/ 中的这些 SKILL.md 文件：

   始终阅读以下高质量示例：

   • pdf/SKILL.md - 结构良好的工作流技能，具有清晰的触发条件
   • docx/SKILL.md - 文档处理模式的良好示例
   • skill-creator/SKILL.md - 展示最佳实践的元技能

   然后阅读 1-2 个与待审查技能相似的技能：

   • 对于基于工作流的技能：xlsx/SKILL.md、pptx/SKILL.md
   • 对于工具/API 技能：mcp-builder/SKILL.md
   • 对于创意/设计技能：brand-guidelines/SKILL.md、frontend-design/SKILL.md
   • 对于测试技能：webapp-testing/SKILL.md

3. 记录用于比较的模式：阅读时，留意以下方面：

   • 描述的结构（触发模式）
   • SKILL.md 正文的长度和详略程度
   • 参考资料的组织和使用方式
   • 简洁性与完整性之间的平衡

步骤

步骤 1：接收待审查的技能

用户必须提供要审查的技能文件夹/路径。如果未提供，请提示：

“请提供要审查的技能文件夹路径（例如，.claude/skills/my-skill/）”

步骤 2：验证技能结构

使用验证清单（references/validate.md），确认技能通过所有基本检查：

1. 文件结构：存在 SKILL.md
2. Frontmatter 格式：--- 分隔符之间是有效的 YAML
3. 允许的属性：仅限 name、description、license、compatibility、metadata、allowed-tools
4. 名称验证：
   • 仅使用连字符格式（小写字母、数字和连字符）
   • 不以连字符开头或结尾，不含连续连字符（--）
   • 最多 64 个字符
   • 与目录名称匹配
5. 描述验证：
   • 不含尖括号（< 或 >）
   • 最多 1024 个字符
   • 不能为空

如果验证失败：停止审查并报告具体的验证错误。技能必须通过基本验证，才能继续完整审查。

步骤 3：阅读技能

阅读完整的技能结构：

• SKILL.md（frontmatter 和正文）
• references/、scripts/、assets/ 目录中的所有文件

重要：仅分析用户提供的技能。

步骤 4：验证规范合规性

检查技能是否符合 Agent Skills 规范（references/spec.md）。确认以下内容：

目录结构

• 技能所在目录与 name 字段匹配
• 包含必需文件 SKILL.md
• 可选目录遵循惯例：scripts/、references/、assets/

Frontmatter 合规性

字段	检查项
name	1-64 个字符，仅含小写字母、数字和连字符，不以连字符开头或结尾，不含 --，与目录名称匹配
description	1-1024 个字符，不能为空，需说明技能的用途和适用时机
license	如存在，应简短（许可证名称或文件引用）
compatibility	如存在，最多 500 个字符
metadata	如存在，键和值均为字符串
allowed-tools	如存在，应为空格分隔的工具列表

正文内容

• frontmatter 后的 Markdown 格式
• 建议：分步说明、示例、边缘情况
• 少于 500 行（将详细内容移至参考资料）

渐进式披露

• 元数据（约 100 个 token）：启动时加载名称和描述
• 指令（建议少于 5000 个 token）：激活时加载 SKILL.md 正文
• 资源（按需加载）：根据需要加载脚本、参考资料和素材

文件引用

• 使用相对于 skill 根目录的路径
• 引用保持一层深（避免深层嵌套链）

如果发现规范违规：在审查输出中清楚记录，并提供具体的修复方法。

第 5 步：分析 Skill

从以下四个方面进行分析，并与从 Anthropic 的仓库中读取的参考 skill 进行比较：

A. 长度分析

使用 skill-creator 中的渐进式披露指南，评估：

• description 字段中的词数
• SKILL.md 正文的行数／词数
• 参考文件的数量和大小
• SKILL.md 与参考文件之间的重复内容

B. 意图范围分析

评估：

• 该 skill 服务的所有意图
• 该 skill 是否处理多个不同的用例
• 拆分是否有助于提高触发准确性
• 权衡：上下文效率与维护开销

需要回答的问题：

• 该 skill 是否试图处理过多内容？
• 是否存在值得拆分为独立 skill 的不同用户意图？

C. 触发分析（关键）

description 字段是主要的触发机制。请针对以下三类触发因素进行评估：

触发类型	检查内容
用户意图	是否描述了用户想要执行的操作？（例如“部署”“创建”“编辑”）
技术上下文	是否提及代码模式、文件类型、导入项？（例如“base44.entities.*”“.jsonc 文件”）
项目技术栈	是否提及框架、工具、文件结构？（例如“Vite”“Next.js”“base44/”）

检查：

• description 是否同时涵盖基于意图和基于技术的触发条件？
• 是否足够具体，能够正确触发，同时又足够宽泛，不会遗漏情况？
• 是否存在该 skill 应触发却可能无法触发的情形？
• 是否能与类似 skill 清楚区分？

良好的触发模式示例：

ACTIVATE when (1) INTENT - user wants to [action]; (2) TECHNICAL - code contains [patterns], uses [APIs]; (3) CONTEXT - project has [structure/files]

第 6 步：提供建议

总结调查结果，并给出可执行的建议：

1. 规范合规性：需要进行哪些修复才能符合规范？
2. 长度：应该删减或拆分哪些内容？
3. 意图范围：应该拆分还是合并？
4. 触发条件：如何改进 description？

输出格式

## Skill Review: [Skill Name]

### Reference Skills Compared
- [List the 3-5 Anthropic skills you read before this review]

### Summary
[1-2 sentence overview]

### Validation Result
- **Status**: [Pass/Fail]
- **Details**: [Validation output or errors]

### Spec Compliance
- Directory structure: [Pass/Fail - details]
- Frontmatter fields: [Pass/Fail - details]
- Body content: [Pass/Recommendations]
- Progressive disclosure: [Pass/Recommendations]
- File references: [Pass/Recommendations]
- **Assessment**: [Compliant/Partially compliant/Non-compliant]
- **Fixes Required**: [List of specific fixes if any]

### Length Analysis
- Description: X words
- SKILL.md body: X lines / X words
- Reference files: X files
- **Assessment**: [Pass/Needs attention]
- **Recommendations**: [Specific suggestions]

### Intent Scope Analysis
- Intents served: [List]
- **Assessment**: [Focused/Broad/Too broad]
- **Recommendations**: [Split suggestions if applicable]

### Trigger Analysis
- Intent coverage: [Yes/Partial/No]
- Technical coverage: [Yes/Partial/No]
- Stack coverage: [Yes/Partial/No]
- **Assessment**: [Strong/Adequate/Weak]
- **Recommendations**: [Specific description improvements]

### Overall Recommendations
1. [Priority 1 action item - spec compliance fixes if any]
2. [Priority 2 action item]
3. [Priority 3 action item]
4. [Priority 4 action item]