name: skill-authoring description: Claude Code技能、MCP工具和AI代理能力的设计和开发最佳实践。适用于创建技能、编写SKILL.md文件、设计工具描述或优化触发。触发于“创建技能”、“技能模板”、“编写技能说明”、SKILL.md、metadata.json、渐进披露、触发优化、MCP工具设计或技能测试。不涉及具体框架或语言（使用专用技能）。
AI代理技能最佳实践
AI代理技能的设计和开发指南，包括Claude Code技能和MCP工具。包含46条规则，分为8个类别，按影响力优先排序，指导技能创建、评审和优化。
何时应用
- 创建新的Claude Code技能或MCP工具
- 编写或评审SKILL.md元数据和描述
- 优化技能触发可靠性
- 为渐进披露构建内容结构
- 测试技能激活和行为
- 为代理工作流设计工具接口
核心原则
1. 描述驱动激活。 Claude根据用户意图匹配描述来选择技能。包括具体能力、触发关键词和负面案例。描述模糊的技能激活不一致或从不激活。
2. 前置关键指令。 Claude可能截断长内容。将非协商规则放在前100行。将重要约束放在末尾会被忽略。
3. 渐进披露节省令牌。 仅在需要时加载详细内容。2000行的技能每次激活都浪费上下文。结构为：SKILL.md（概述）→ references/（细节）→ scripts/（执行）。
4. 测试激活，而不仅仅是执行。 技能工作完美但从不触发则提供零价值。在部署前使用真实用户短语、同义词和边缘案例测试。
5. 每个域一个技能。 重叠的技能创建激活冲突。按清晰边界（语言、框架、工作流阶段）拆分，使用不同的触发关键词。
规则类别
| 优先级 | 类别 | 影响力 | 前缀 |
|---|---|---|---|
| 1 | 技能元数据设计 | 关键 | meta- |
| 2 | 描述工程 | 关键 | desc- |
| 3 | 内容结构 | 高 | struct- |
| 4 | 触发优化 | 高 | trigger- |
| 5 | 渐进披露 | 中高 | prog- |
| 6 | MCP工具设计 | 中 | mcp- |
| 7 | 测试和验证 | 中 | test- |
| 8 | 维护和分发 | 低中 | maint- |
快速参考
1. 技能元数据设计（关键）
meta-name-format- 使用小写连字符分隔的技能名称meta-name-hyphen-boundaries- 名称从不以连字符开头或结尾meta-name-no-consecutive-hyphens- 避免名称中连续连字符meta-name-uniqueness- 确保技能名称全局唯一meta-required-frontmatter- 包含所有必需的前置元数据字段meta-allowed-frontmatter-fields- 仅使用允许的前置元数据字段meta-frontmatter-yaml-syntax- 使用有效的YAML前置元数据语法meta-name-length- 保持技能名称少于64个字符meta-directory-match- 技能名称与目录名称匹配
2. 描述工程（关键）
desc-specific-capabilities- 在描述中命名具体能力desc-trigger-keywords- 在描述中包含用户触发关键词desc-third-person-voice- 以第三人称编写描述desc-length-optimization- 优化描述长度以便发现desc-avoid-vague-terms- 在描述中避免模糊术语desc-differentiate-similar-skills- 用不同触发区分相似技能desc-include-negative-cases- 包含负面案例以提高精确度
3. 内容结构（高）
struct-header-hierarchy- 使用一致的标题层次结构struct-instructions-first- 将关键指令放在内容早期struct-imperative-instructions- 以祈使语气编写指令struct-code-blocks-with-language- 在代码块中指定语言struct-line-limit- 保持SKILL.md少于500行struct-single-responsibility- 每个域一个技能
4. 触发优化（高）
trigger-slash-command-aliases- 在描述中包含斜杠命令别名trigger-file-type-patterns- 在描述中包含文件类型模式trigger-workflow-stages- 在描述中引用工作流阶段trigger-error-patterns- 在调试技能中包含错误模式trigger-synonym-coverage- 覆盖同义词和替代措辞
5. 渐进披露（中高）
prog-three-level-disclosure- 实现三级渐进披露prog-one-level-deep-links- 将参考链接限制为一级深度prog-scripts-execute-not-read- 执行脚本而不是读取代码prog-lazy-load-examples- 延迟加载示例和参考材料prog-mutual-exclusion- 分离互斥上下文
6. MCP工具设计（中）
mcp-tool-naming- 使用清晰的动作-对象工具名称mcp-parameter-descriptions- 记录所有工具参数mcp-error-messages- 返回可操作的错误消息mcp-tool-scope- 设计单一目的工具mcp-allowed-tools- 使用允许工具进行安全约束mcp-idempotent-operations- 设计幂等工具操作
7. 测试和验证（中）
test-trigger-phrases- 使用真实用户短语测试技能激活test-edge-cases- 使用边缘案例输入测试技能test-negative-scenarios- 测试技能在无关请求上不触发test-instruction-clarity- 使用新鲜上下文测试指令清晰度
8. 维护和分发（低中）
maint-semantic-versioning- 使用语义版本控制进行技能发布maint-changelog- 为技能更新维护变更日志maint-plugin-packaging- 将技能打包为插件用于分发maint-audit-security- 从外部源安装前审计技能安全性
创建规则
复制 assets/templates/_template.md 并遵循前置元数据模式：
---
title: 规则标题在此
impact: 关键|高|中高|中|低中|低
impactDescription: 量化影响力（例如，“2-10倍改进”）
tags: 前缀, 技术, 相关概念
---
参考文件使用模式：references/{prefix}-{slug}.md