制作检查网站质量的AI智能体技能库

## 把仓库按网站质量主题拆成一个个技能 将仓库视为一组自包含的智能体能力，而不是一个庞大的指令文件。将综合审计与专注于性能、可访问性、可发现性、总体质量和用户体验指标的技能分开，使智能体只加载任务所需的能力。 将仓库级文档、贡献规则、许可信息和智能体指导保留在根目录。每个技能目录负责其主要指令文件、自动化脚本和详细参考资料。不要把面向用户的指导、可执行辅助工具或源材料隐藏在无关目录中。 更改技能前，先确定其触发契约、归属文件、依赖项、验证路径以及与其他技能的关系。 ## 确定文件夹和文件的命名，并写好SKILL.md的头部信息 为每个技能提供一个包含有效YAML前置元数据的`SKILL.md`文件，其中包括： - 使用kebab-case的`name`； - 用一句话说明何时使用该技能并包含切实触发短语的`description`； - 必要时包含许可证元数据； - 仓库进行相关跟踪时，包含稳定的作者和版本元数据。 始终使用精确且一致的命名约定： - 技能目录使用kebab-case； - 主要指令文件必须准确命名为`SKILL.md`； - 脚本文件名使用kebab-case和适当的可执行扩展名； - 参考文件名遵循仓库记录的大写命名约定。 保持技能包自包含，并确保技能中提到的每条路径都能在受支持的仓库布局内解析。 ## SKILL.md保持在500行以内，细节移到参考文件 主要技能必须少于500行。将触发条件、核心工作流、关键约束和导航放在`SKILL.md`中；将详细说明、大型示例和专业材料移入参考资料。 编写具体、可执行的指导。每条指导都应包含简短标题、直接指令，以及应用它所需的值或阈值。优先说明要检查什么、要作出什么决定，以及用什么证据证明完成。 当确定性或重复性工作的输出会占用推理上下文时，使用脚本处理。不要在主要技能和多份参考资料中重复同一流程。 ## 展示修改前后的代码，以及好坏分档的阈值表 当指导规则约束可执行行为时，同时展示问题模式和修正后的模式。示例应足够小，能够独立理解，并且必须验证其确实有效。 例如，图像稳定性指导应对比一个信息不足的图像与一个声明了尺寸和实用加载元数据的图像： 问题：图像元素只有`src="hero.jpg"`。改进：同一元素还包含`width="1200"`、`height="600"`、`alt="Hero image"`和`loading="lazy"`。 对于可比较的质量阈值，使用表格明确列出良好、中等和较差范围。注明单位和边界运算符，使读者无需推断限制是否包含边界值。 ## 编写出错即停、以JSON输出结果的Shell脚本 Shell辅助工具必须快速失败、可供机器读取，并且能够安全清理： - 使用shebang声明预期的Shell； - 启用`set -e`等快速失败行为； - 将进度和状态消息发送到标准错误； - 将JSON等机器可读结果发送到标准输出； - 安全创建临时文件并注册清理trap； - 保持自包含，或记录每项外部依赖和前提条件。 不要把面向人的诊断信息混入机器可读流。在将辅助工具视为可复用自动化之前，测试成功、失败、格式错误的输入和清理行为。 ## 每个参考文件只讲一个主题，并从技能中链接 每份参考资料只聚焦一个主题，提供实用示例，并链接回权威材料。可能时，将单份参考资料保持在少于200行，使智能体无需加载无关上下文即可独立读取。 从主要技能或维护中的索引链接每份参考资料。移除过时链接和重复指导，并让最接近的权威来源负责维护可变事实。 参考资料用于提供深度，而不是堆放信息。每份参考资料都应帮助智能体作出或执行一项明确决定。 ## 发布技能前检查头部信息、示例、链接和脚本 提交或发布技能前： 1. 解析并验证YAML前置元数据。 2. 确认描述中包含可用的触发短语。 3. 运行或以其他方式验证每个可执行示例。 4. 确认每个被引用的文件都存在，且每个内部链接都能解析。 5. 通过脚本记录的接口运行脚本，并验证输出通道行为。 6. 根据适用的智能体技能规范验证技能包。 语法检查成功是必要条件，但并不充分。触发描述、示例、参考资料和脚本必须与技能承诺的行为一致。 ## 按严重到轻微给问题排序，建议不绑定特定框架 按照一致的标准排列发现事项： 1. **严重：** 安全漏洞或功能完全失效。 2. **高：** 严重的性能故障或重大的可访问性障碍。 3. **中：** 对性能、可发现性或搜索质量具有实际意义的改进机会。 4. **低：** 代码风格或轻微优化机会。 保持Web指导不依赖具体框架。首先展示标准HTML、CSS和JavaScript，将框架特定说明放在单独章节中；除非任务必须依赖某个框架，否则优先使用标准平台API。 先审查影响最大的正确性问题和访问障碍，再把精力用于风格改进。 ## 更新技能时不破坏触发它的短语 更新技能描述时保持向后兼容，并让已有触发短语继续有效。随实现一起更新版本元数据，并在仓库要求的变更记录或提交说明中记录破坏性变更。 结构发生变化时，同时更新主要技能、受影响的参考资料、脚本、示例和链接。检查最终差异，排查意外扩大范围、过时的生成材料和重复指令。 每次行为变更后，重新运行聚焦的验证清单。当触发路径、示例或被引用的资源仍未验证时，不要声称更新后的技能已经就绪。