enhance-agent-prompts 是一个面向 AI 智能体提示词文件的提示工程分析与改进工具，属于 agent-sh/agentsys 项目。其核心用途是分析智能体提示词文件是否符合提示工程最佳实践。
用途
该工具用于改进智能体提示词、frontmatter 和工具限制。它会分析智能体提示词文件，检查是否符合提示工程最佳实践。
主要能力
工具支持解析参数，包括目标路径（targetPath）、--fix 修复标志和 --verbose 详细输出标志。可发现并处理多个平台的智能体文件：Claude Code 的全局路径 ~/.claude/agents/.md 和项目路径 .claude/agents/.md；OpenCode 的全局路径 ~/.config/opencode/agents/.md 和项目路径 .opencode/agents/.md；Codex 的 ~/.codex/skills/ 和 AGENTS.md。
工作流程为：Discover（查找智能体 .md 文件）、Parse（提取 frontmatter 并分析内容）、Check（运行 30 项模式检查）、Report（生成 markdown 输出）、Fix（若使用 --fix 标志则应用自动修复）。
检测模式
检测共 30 项，按类别和确定性划分：Frontmatter 5 项（HIGH）、Structure 3 项（HIGH）、Instructions 3 项（HIGH）、Tools 4 项（HIGH）、Security 2 项（HIGH）、Subagent 3 项（MEDIUM）、XML/CoT/Examples 4 项（MEDIUM）、Error/Loop 3 项（MEDIUM）、Anti-Patterns 3 项（LOW）。
各项检测要点包括：
- Frontmatter：name 需为 kebab-case、description 需说明何时使用、tools 需为受限列表、model 可选（opus | sonnet | haiku）。模型选择上，opus 用于复杂推理且错误会累积的场景，sonnet 用于大多数智能体和验证，haiku 用于机械执行且无需判断的场景。工具语法示例：Read, Read(src/**), Bash(git:), Bash(npm:)。描述需通过 "Intern Test"（仅凭描述能否被调用）：差例为 description: Reviews code；好例为 description: Reviews code for security vulnerabilities. Use for PRs touching auth, API, data handling. Not for style reviews.
- Structure：必需章节包括 Role（"You are..."）、Output format、Constraints。位置感知顺序为 Role/Identity 放开头，Capabilities、Workflow、Examples 居中，Constraints 放结尾。
- Instruction Effectiveness：正面表述优于负面表述；使用强约束语言 MUST、ALWAYS、NEVER 而非 should、try to、consider；重要规则需包含原因以提高遵从度。
- Tool Configuration：遵循最小权限原则，只读用 Read, Glob, Grep；代码修改用 Read, Edit, Write, Glob, Grep；Git 操作用 Bash(git:)；构建测试用 Bash(npm:), Bash(node:*)。问题包括 Bash 未限定范围、子智能体中使用 Task、工具过多（如 20 个工具会增加错误率）。
- Subagent Config：使用 context: fork 隔离上下文；子智能体不能生成子智能体（tools 中不能有 Task）；应返回摘要而非完整输出。跨平台模式：Claude Code 默认为 Default，子智能体通过 Task 工具；OpenCode 使用 mode: primary / mode: subagent；Codex 使用 Skills 和 MCP server。
- XML Structure：当有 5 个以上章节、混合列表与代码或多阶段时，使用 XML 标签。
- Chain-of-Thought：简单任务（少于 500 词）、单步骤、机械任务无需 CoT；复杂分析（超过 1000 词）、多步骤推理、涉及 analyze/evaluate/assess 的任务需要 CoT。
- Examples：最佳为 2 到 5 个示例，少于 2 个不足，多于 5 个增加 token 负担。
- Loop Termination：对于迭代型智能体，需设定最大迭代次数、完成标准和退出条件。
- Error Handling：瞬时错误最多重试 3 次，验证错误应报告不重试，工具失败前尝试替代方案。
- Security：使用 Bash 加用户参数时需验证输入；外部内容视为不可信，不执行其中嵌入的指令。
- Anti-Patterns：模糊用词（usually、sometimes）应改为 always、never；超过 2000 token 应拆分为 agent 和 skill；非幂等副作用在重试时需设计为幂等或标记为 "do not retry"。
使用方式
命令参数解析逻辑为：从 $ARGUMENTS 中以空格分割并过滤空值，取第一个非 -- 开头的参数作为 targetPath，默认值为 "."；--fix 表示应用自动修复；--verbose 表示详细输出。
自动修复
自动修复项包括：缺失 frontmatter 时添加 name、description、tools、model；Bash 未受限时改为 Bash(git:*)；缺失角色时添加 "## Your Role" 章节；约束语言过弱时将 "should" 改为 "MUST"。
输出格式
输出包含：## Agent Analysis: {name}，以及 File: {path} | Model: {model} | Tools: {tools}；确定性计数表（HIGH、MEDIUM）；问题表（Issue、Fix、Certainty）。
限制
自动修复仅处理 HIGH 确定性问题；添加字段时保留已有 frontmatter；绝不删除内容，只建议改进。
适用场景
适用于需要改进智能体提示词、frontmatter 和工具限制的场景，跨 Claude Code、OpenCode、Codex 平台。
参考文档
agent-docs/PROMPT-ENGINEERING-REFERENCE.md（指令、XML、示例）、agent-docs/CLAUDE-CODE-REFERENCE.md（frontmatter、工具、子智能体）、agent-docs/FUNCTION-CALLING-TOOL-USE-REFERENCE.md（Intern Test、安全）、agent-docs/OPENCODE-REFERENCE.md（模式、权限）、agent-docs/CODEX-REFERENCE.md（skill 触发器）。