chaterm.cn

Appearance

Skills 故障排除与最佳实践 ​

本页介绍如何编写高质量的 Skills、优化性能以及避免常见问题。有关配置说明，请参阅 Skills 使用指南。

编写高质量的 Skills ​

1. 清晰的命名和描述 ​

TIP

AI 使用 Skill 的描述来决定何时应用它。模糊的描述会导致匹配遗漏或不准确。

  • 编写具体的描述：明确说明 Skill 的用途和适用场景。包含重要关键词，并说明前置条件和预期结果。
  • 使用一致的命名：选择清晰、描述性的名称。可以添加分类前缀，如 k8s-、docker-、git-。在所有 Skills 中保持命名风格一致。

2. 结构化的步骤 ​

  • 保持逻辑清晰

    • 按执行顺序组织步骤。
    • 使用编号列表明确顺序。
    • 在行为分支处添加必要的判断和分支。

  • 详细具体

    • 包含完整的命令和参数。
    • 说明每个步骤的意图。
    • 在需要时提供示例和预期输出。

3. 错误处理和回滚 ​

  • 处理失败情况

    • 识别可能的错误条件。
    • 为每个错误路径提供处理步骤。
    • 说明如何判断操作是否成功。

  • 定义回滚流程

    • 对可能产生影响的操作，提供回滚步骤。
    • 说明如何将系统恢复到操作前的状态。

WARNING

修改基础设施或数据的 Skills 应始终包含回滚部分。缺少回滚说明时，失败的操作可能导致系统处于不一致的状态。

4. 可维护性 ​

  • 使用变量而非硬编码

    • 尽量避免硬编码特定值。
    • 使用占位符（如 <pod-name>、<namespace>）保持 Skill 的可复用性。
    • 记录每个变量的含义和有效范围。

  • 模块化设计

    • 将复杂工作流拆分为更小、更专注的部分。
    • 让每个步骤只负责一个关注点。
    • 保持 Skills 易于测试和后续修改。

性能优化 ​

控制启用的 Skills 数量 ​

INFO

每个启用的 Skill 都会注入到 AI 系统提示中。启用过多的 Skills 会增加 token 用量，并可能分散 AI 的注意力。

  • 只启用需要的：仅开启与当前任务相关的 Skills。定期清理不再使用的 Skills。
  • 按场景加载：根据当前任务切换不同的 Skill 集合。使用分组按场景管理 Skills，为不同工作流维护不同的集合。

优化 Skill 内容 ​

  • 精简步骤：移除不必要的步骤，合并可以安全并行执行的步骤，优化命令执行顺序以获得更快的反馈。
  • 降低复杂度：避免在单个 Skill 中使用过于复杂的条件逻辑。将非常复杂的 Skill 拆分为多个更简单的 Skills。将大量内容存储在资源文件中而非内联文本中。

参考资料 ​

Terminal Skills 官方仓库 ​

  • GitHub：chaterm/terminal-skills
  • 说明：专为终端工作流设计的精选 Skills 集合，涵盖各种运维和开发使用场景。

后续阅读 ​