mcpField
S
skill-authoring

skill-authoring

github.com/pproencaAgent 工作流220327 次安装11 周前更新
代码仓库

关于 skill-authoring

用于创建、审查和改进 AI Agent 技能的指南，涵盖 Claude Code 技能与 MCP 工具。46 条规则涉及元数据、触发、内容结构、渐进式披露、工具设计、测试和维护。

主要功能

  1. 018 个类别的 46 条规则
  2. 02技能元数据与描述指南
  3. 03触发与激活优化
  4. 04内容渐进式披露
  5. 05MCP 工具设计与验证

适用场景

  1. 01创建或审查 Agent 技能
  2. 02提升技能触发的可靠性
  3. 03组织技能内容与参考资料
  4. 04测试工具接口与技能行为

MCP 相关

指南提供 MCP 工具设计建议，涵盖命名、参数说明、工具范围和错误消息。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/pproenca/dot-skills --skill skill-authoring

安装后在 Claude Code 中输入/skill-authoring确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

AGENTS.md
metadata.json
assets/templates/
_template.md
references/
_sections.md
desc-avoid-vague-terms.md
desc-differentiate-similar-skills.md
desc-include-negative-cases.md
desc-length-optimization.md
desc-specific-capabilities.md
desc-third-person-voice.md
desc-trigger-keywords.md
maint-audit-security.md
maint-changelog.md
maint-plugin-packaging.md
maint-semantic-versioning.md
mcp-allowed-tools.md
mcp-error-messages.md
mcp-idempotent-operations.md
mcp-parameter-descriptions.md
mcp-tool-naming.md
mcp-tool-scope.md
meta-allowed-frontmatter-fields.md
meta-directory-match.md
meta-frontmatter-yaml-syntax.md
meta-name-format.md
meta-name-hyphen-boundaries.md
meta-name-length.md
meta-name-no-consecutive-hyphens.md
meta-name-uniqueness.md
meta-required-frontmatter.md

详细介绍

AI Agent 技能最佳实践

AI Agent 技能的设计与开发指南，涵盖 Claude Code 技能和 MCP 工具。包含 8 个类别、46 条规则，并按影响力排序，以指导技能的创建、审查和优化。

适用场景

  • 创建新的 Claude Code 技能或 MCP 工具
  • 编写或审查 SKILL.md 元数据和描述
  • 优化技能触发的可靠性
  • 设计内容结构，实现渐进式披露
  • 测试技能的激活与行为
  • 为 Agent 工作流设计工具接口

核心原则

1. 描述决定激活。 Claude 会根据描述与用户意图的匹配情况来选择技能。描述中应包含具体能力、触发关键词和不适用的情况。描述含糊的技能可能无法稳定激活，甚至从不激活。

2. 将关键指令放在前面。 Claude 可能会截断较长的内容。应将不可妥协的规则放在前 100 行。把重要约束埋在末尾，它们就会被忽略。

3. 渐进式披露可节省令牌。 仅在需要时加载详细内容。一个 2000 行的技能每次激活都会浪费上下文。结构应为：SKILL.md（概述）→ references/（详情）→ scripts/（执行）。

4. 测试激活，而不只是执行。 一个运行完美却从不触发的技能毫无价值。部署前，应使用真实用户表达、同义词和边缘情况进行测试。

5. 每个领域使用一个技能。 重叠的技能会造成激活冲突。应按明确的边界（语言、框架、工作流阶段）拆分，并使用不同的触发关键词。

规则类别

优先级类别影响前缀
1技能元数据设计CRITICALmeta-
2描述设计CRITICALdesc-
3内容结构HIGHstruct-
4触发优化HIGHtrigger-
5渐进式披露MEDIUM-HIGHprog-
6MCP 工具设计MEDIUMmcp-
7测试与验证MEDIUMtest-
8维护与分发LOW-MEDIUMmaint-

快速参考

1. 技能元数据设计（CRITICAL）
  • meta-name-format - 使用小写连字符格式的技能名称
  • meta-name-hyphen-boundaries - 名称不得以连字符开头或结尾
  • meta-name-no-consecutive-hyphens - 避免名称中出现连续连字符
  • meta-name-uniqueness - 确保技能名称全局唯一
  • meta-required-frontmatter - 包含所有必需的 frontmatter 字段
  • meta-allowed-frontmatter-fields - 仅使用允许的 frontmatter 字段
  • meta-frontmatter-yaml-syntax - 使用有效的 YAML frontmatter 语法
  • meta-name-length - 技能名称保持在 64 个字符以内
  • meta-directory-match - 确保技能名称与目录名称一致
2. 描述设计（CRITICAL）
  • 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. 内容结构（HIGH）
  • struct-header-hierarchy - 使用一致的标题层级
  • struct-instructions-first - 将关键指令放在内容前面
  • struct-imperative-instructions - 使用祈使语气编写指令
  • struct-code-blocks-with-language - 为代码块注明语言
  • struct-line-limit - 将 SKILL.md 控制在 500 行以内
  • struct-single-responsibility - 每个领域使用一个技能
  • project-conventions - 保留仓库特定的技能约定
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 - 使用 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，并遵循 frontmatter 架构：

---
title: Rule Title Here
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
impactDescription: Quantified impact (e.g., "2-10x improvement")
tags: prefix, technique, related-concepts
---

参考文件采用以下格式：references/{prefix}-{slug}.md

参考资料

评论

支持 Markdown