如何设计Agent提示词：Claude Code的18个工具提示词参考
·
周末抓了 Claude Agent SDK 的请求数据，发现里面定义了 18 个工具。之前的续篇主要看了 Skill 工具的结构，这次顺便把其他工具的提示词也整理出来，给自建 agent 做个参考。
Claude Code 版本：v2.1.17。这些提示词写得很讲究，可以学学怎么描述工具、怎么写使用说明、怎么给例子。
Task
{
"name": "Task",
"description": "Launch a new agent to handle complex, multi-step tasks autonomously. \n\nThe Task tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.\n\nAvailable agent types and the tools they have access to:\n\n\nWhen using the Task tool, you must specify a subagent_type parameter to select which agent type to use.\n\nWhen NOT to use the Task tool:\n- If you want to read a specific file path, use the Read or Glob tool instead of the Task tool, to find the match more quickly\n- If you are searching for a specific class definition like \"class Foo\", use the Glob tool instead, to find the match more quickly\n- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Task tool, to find the match more quickly\n- Other tasks that are not related to the agent descriptions above\n\n\nUsage notes:\n- Always include a short description (3-5 words) summarizing what the agent will do\n- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses\n- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.\n- You can optionally run agents in the background using the run_in_background parameter. When an agent runs in the background, you will need to use TaskOutput to retrieve its results once it's done. You can continue to work while background agents run - When you need their results to continue you can use TaskOutput in blocking mode to pause and wait for their results.\n- Agents can be resumed using the `resume` parameter by passing the agent ID from a previous invocation. When resumed, the agent continues with its full previous context preserved. When NOT resuming, each invocation starts fresh and you should provide a detailed task description with all necessary context.\n- When the agent is done, it will return a single message back to you along with its agent ID. You can use this ID to resume the agent later if needed for follow-up work.\n- Provide clear, detailed prompts so the agent can work autonomously and return exactly the information you need.\n- Agents with \"access to current context\" can see the full conversation history before the tool call. When using these agents, you can write concise prompts that reference earlier context (e.g., \"investigate the error discussed above\") instead of repeating information. The agent will receive all prior messages and understand the context.\n- The agent's outputs should generally be trusted\n- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent\n- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.\n- If the user specifies that they want you to run agents \"in parallel\", you MUST send a single message with multiple Task tool use content blocks. For example, if you need to launch both a code-reviewer agent and a test-runner agent in parallel, send a single message with both tool calls.\n\nExample usage:\n\n<example_agent_descriptions>\n\"code-reviewer\": use this agent after you are done writing a signficant piece of code\n\"greeting-responder\": use this agent when to respond to user greetings with a friendly joke\n</example_agent_description>\n\n<example>\nuser: \"Please write a function that checks if a number is prime\"\nassistant: Sure let me write a function that checks if a number is prime\nassistant: First let me use the Write tool to write a function that checks if a number is prime\nassistant: I'm going to use the Write tool to write the following code:\n<code>\nfunction isPrime(n) {\n if (n <= 1) return false\n for (let i = 2; i * i <= n; i++) {\n if (n % i === 0) return false\n }\n return true\n}\n</code>\n<commentary>\nSince a signficant piece of code was written and the task was completed, now use the code-reviewer agent to review the code\n</commentary>\nassistant: Now let me use the code-reviewer agent to review the code\nassistant: Uses the Task tool to launch the code-reviewer agent \n</example>\n\n<example>\nuser: \"Hello\"\n<commentary>\nSince the user is greeting, use the greeting-responder agent to respond with a friendly joke\n</commentary>\nassistant: \"I'm going to use the Task tool to launch the greeting-responder agent\"\n</example>\n",
"input_schema": {
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "A short (3-5 word) description of the task"
},
"prompt": {
"type": "string",
"description": "The task for the agent to perform"
},
"subagent_type": {
"type": "string",
"description": "The type of specialized agent to use for this task"
},
"model": {
"type": "string",
"enum": [
"sonnet",
"opus",
"haiku"
],
"description": "Optional model to use for this agent. If not specified, inherits from parent. Prefer haiku for quick, straightforward tasks to minimize cost and latency."
},
"resume": {
"type": "string",
"description": "Optional agent ID to resume from. If provided, the agent will continue from the previous execution transcript."
},
"run_in_background": {
"type": "boolean",
"description": "Set to true to run this agent in the background. Use TaskOutput to read the output later."
}
},
"required": [
"description",
"prompt",
"subagent_type"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
启动一个新的代理来自主处理复杂的多步骤任务。
Task工具启动专门的代理（子进程）来自主处理复杂任务。每种代理类型都有特定的功能和可用工具。
可用的代理类型及其拥有的工具：
使用Task工具时，必须指定subagent_type参数来选择要使用的代理类型。
何时不使用Task工具：
- 如果你想读取特定文件路径，使用Read或Glob工具而不是Task工具，能更快找到匹配项
- 如果你在搜索特定的类定义，如"class Foo"，使用Glob工具而不是Task工具，能更快找到匹配项
- 如果你在特定文件或2-3个文件集合中搜索代码，使用Read工具而不是Task工具，能更快找到匹配项
- 与上述代理描述无关的其他任务
使用注意事项：
- 始终包含一个简短描述（3-5个词）来概括代理将要做什么
- 尽可能并发启动多个代理以提高性能，要做到这一点，在单个消息中使用多个工具调用
- 当代理完成时，它会向你返回一条消息。代理返回的结果对用户不可见。要向用户展示结果，你应该向用户发送一条文本消息，简要总结结果。
- 你可以使用run_in_background参数在后台运行代理。当代理在后台运行时，完成后你需要使用TaskOutput来获取其结果。你可以在后台代理运行时继续工作，当你需要它们的结果来继续时，可以使用TaskOutput的阻塞模式暂停并等待结果。
- 可以使用`resume`参数通过传递之前调用的代理ID来恢复代理。恢复时，代理会继续保留其之前的完整上下文。如果不恢复，每次调用都是全新的，你应该提供详细的任务描述和所有必要的上下文。
- 当代理完成时，它会向你返回一条消息以及其代理ID。如果需要后续工作，你可以使用此ID稍后恢复代理。
- 提供清晰、详细的提示，以便代理能够自主工作并准确返回你需要的信息。
- 拥有"访问当前上下文"权限的代理可以看到工具调用之前的完整对话历史。使用这些代理时，你可以编写简洁的提示来引用之前的上下文（例如"调查上述讨论的错误"），而不需要重复信息。代理将收到所有先前的消息并理解上下文。
- 代理的输出通常应该是可信的
- 明确告知代理你是期望它编写代码还是只进行研究（搜索、文件读取、网页获取等），因为它不知道用户的意图
- 如果代理描述提到应该主动使用它，那么你应该尽力在用户没有要求之前使用它。使用你的判断力。
- 如果用户指定要你"并行"运行代理，你必须发送一个包含多个Task工具使用内容块的单个消息。例如，如果你需要并行启动code-reviewer代理和test-runner代理，发送一个包含这两个工具调用的单个消息。
使用示例：
<example_agent_descriptions>
"code-reviewer"：在完成编写大量代码后使用此代理
"greeting-responder"：使用此代理以友好的笑话回应用户问候
</example_agent_description>
<example>
user: "请编写一个函数来检查数字是否为素数"
assistant: 当然，让我编写一个函数来检查数字是否为素数
assistant: 首先让我使用Write工具来编写一个检查数字是否为素数的函数
assistant: 我将使用Write工具来编写以下代码：
<code>
function isPrime(n) {
if (n <= 1) return false
for (let i = 2; i * i <= n; i++) {
if (n % i === 0) return false
}
return true
}
</code>
<commentary>
由于已经编写了大量代码且任务已完成，现在使用code-reviewer代理来审查代码
</commentary>
assistant: 现在让我使用code-reviewer代理来审查代码
assistant: 使用Task工具启动code-reviewer代理
</example>
<example>
user: "你好"
<commentary>
由于用户在问候，使用greeting-responder代理以友好的笑话回应
</commentary>
assistant: "我将使用Task工具启动greeting-responder代理"
</example>
【浅析】Task 是 Claude Code 的核心编排工具，专门用来启动子代理干活。
看这个描述就知道不是什么都往 Task 里塞，而是明确说了：搜特定文件用 Glob，搜代码内容用 Grep，读少量文件用 Read。只有真正需要多轮探索的复杂任务才用 Task。这种「能用简单工具就用简单工具」的思路挺对的。
还有个有意思的设计：代理可以恢复执行（resume 参数），保持之前的上下文。这对于需要多轮迭代的复杂任务很有用。
并发执行也强调了好几遍：尽可能在单个消息中启动多个代理。说明对性能也很重要。
TaskOutput
{
"name": "TaskOutput",
"description": "- Retrieves output from a running or completed task (background shell, agent, or remote session)\n- Takes a task_id parameter identifying the task\n- Returns the task output along with status information\n- Use block=true (default) to wait for task completion\n- Use block=false for non-blocking check of current status\n- Task IDs can be found using the /tasks command\n- Works with all task types: background shells, async agents, and remote sessions",
"input_schema": {
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "The task ID to get output from"
},
"block": {
"type": "boolean",
"default": true,
"description": "Whether to wait for completion"
},
"timeout": {
"type": "number",
"minimum": 0,
"maximum": 600000,
"default": 30000,
"description": "Max wait time in ms"
}
},
"required": [
"task_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
- 从正在运行或已完成的任务（后台shell、代理或远程会话）获取输出
- 接受一个标识任务的task_id参数
- 返回任务输出以及状态信息
- 使用block=true（默认值）等待任务完成
- 使用block=false进行非阻塞的当前状态检查
- 可以使用/tasks命令找到任务ID
- 适用于所有任务类型：后台shell、异步代理和远程会话【浅析】TaskOutput 是 Task 的配套工具，专门用来取后台任务的结果。
block 参数控制行为：true 等任务跑完再返回，false 立刻返回当前状态。timeout 默认 30 秒，最大 10 分钟。
这个工具支持三种任务：后台 shell、异步代理、远程会话。任务 ID 通过 /tasks 命令找。
Bash
{
"name": "Bash",
"description": "Executes a given bash command in a persistent shell session with optional timeout, ensuring proper handling and security measures.\n\nIMPORTANT: This tool is for terminal operations like git, npm, docker, etc. DO NOT use it for file operations (reading, writing, editing, searching, finding files) - use the specialized tools for this instead.\n\nBefore executing the command, please follow these steps:\n\n1. Directory Verification:\n - If the command will create new directories or files, first use `ls` to verify the parent directory exists and is the correct location\n - For example, before running \"mkdir foo/bar\", first use `ls foo` to check that \"foo\" exists and is the intended parent directory\n\n2. Command Execution:\n - Always quote file paths that contain spaces with double quotes (e.g., cd \"path with spaces/file.txt\")\n - Examples of proper quoting:\n - cd \"/Users/name/My Documents\" (correct)\n - cd /Users/name/My Documents (incorrect - will fail)\n - python \"/path/with spaces/script.py\" (correct)\n - python /path/with spaces/script.py (incorrect - will fail)\n - After ensuring proper quoting, execute the command.\n - Capture the output of the command.\n\nUsage notes:\n - The command argument is required.\n - You can specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). If not specified, commands will timeout after 120000ms (2 minutes).\n - It is very helpful if you write a clear, concise description of what this command does in 5-10 words.\n - If the output exceeds 30000 characters, output will be truncated before being returned to you.\n - You can use the `run_in_background` parameter to run the command in the background, which allows you to continue working while the command runs. You can monitor the output using the Bash tool as it becomes available. You do not need to use '&' at the end of the command when using this parameter.\n \n - Avoid using Bash with the `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or when these commands are truly necessary for the task. Instead, always prefer using the dedicated tools for these commands:\n - File search: Use Glob (NOT find or ls)\n - Content search: Use Grep (NOT grep or rg)\n - Read files: Use Read (NOT cat/head/tail)\n - Edit files: Use Edit (NOT sed/awk)\n - Write files: Use Write (NOT echo >/cat <<EOF)\n - Communication: Output text directly (NOT echo/printf)\n - When issuing multiple commands:\n - If the commands are independent and can run in parallel, make multiple Bash tool calls in a single message. For example, if you need to run \"git status\" and \"git diff\", send a single message with two Bash tool calls in parallel.\n - If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them together (e.g., `git add . && git commit -m \"message\" && git push`). For instance, if one operation must complete before another starts (like mkdir before cp, Write before Bash for git operations, or git add before git commit), run these operations sequentially instead.\n - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail\n - DO NOT use newlines to separate commands (newlines are ok in quoted strings)\n - Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of `cd`. You may use `cd` if the User explicitly requests it.\n <good-example>\n pytest /foo/bar/tests\n </good-example>\n <bad-example>\n cd /foo/bar && pytest tests\n </bad-example>\n\n# Committing changes with git\n\nOnly create commits when requested by the user. If unclear, ask first. When the user asks you to create a new git commit, follow these steps carefully:\n\nGit Safety Protocol:\n- NEVER update the git config\n- NEVER run destructive/irreversible git commands (like push --force, hard reset, etc) unless the user explicitly requests them \n- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it\n- NEVER run force push to main/master, warn the user if they request it\n- Avoid git commit --amend. ONLY use --amend when ALL conditions are met:\n (1) User explicitly requested amend, OR commit SUCCEEDED but pre-commit hook auto-modified files that need including\n (2) HEAD commit was created by you in this conversation (verify: git log -1 --format='%an %ae')\n (3) Commit has NOT been pushed to remote (verify: git status shows \"Your branch is ahead\")\n- CRITICAL: If commit FAILED or was REJECTED by hook, NEVER amend - fix the issue and create a NEW commit\n- CRITICAL: If you already pushed to remote, NEVER amend unless user explicitly requests it (requires force push)\n- NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive.\n\n1. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following bash commands in parallel, each using the Bash tool:\n - Run a git status command to see all untracked files.\n - Run a git diff command to see both staged and unstaged changes that will be committed.\n - Run a git log command to see recent commit messages, so that you can follow this repository's commit message style.\n2. Analyze all staged changes (both previously staged and newly added) and draft a commit message:\n - Summarize the nature of the changes (eg. new feature, enhancement to an existing feature, bug fix, refactoring, test, docs, etc.). Ensure the message accurately reflects the changes and their purpose (i.e. \"add\" means a wholly new feature, \"update\" means an enhancement to an existing feature, \"fix\" means a bug fix, etc.).\n - Do not commit files that likely contain secrets (.env, credentials.json, etc). Warn the user if they specifically request to commit those files\n - Draft a concise (1-2 sentences) commit message that focuses on the \"why\" rather than the \"what\"\n - Ensure it accurately reflects the changes and their purpose\n3. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following commands:\n - Add relevant untracked files to the staging area.\n - Create the commit with a message ending with:\n \ud83e\udd16 Generated with [Claude Code](https://claude.com/claude-code)\n\n Co-Authored-By: Claude <noreply@anthropic.com>\n - Run git status after the commit completes to verify success.\n Note: git status depends on the commit completing, so run it sequentially after the commit.\n4. If the commit fails due to pre-commit hook:\n - If hook REJECTED the commit (non-zero exit): Fix the issue, then create a NEW commit (NEVER amend)\n - If commit SUCCEEDED but hook auto-modified files (e.g., formatting): You MAY amend to include them, but ONLY if:\n * HEAD was created by you (verify: git log -1 --format='%an %ae')\n * Commit is not pushed (verify: git status shows \"Your branch is ahead\")\n - When in doubt, create a NEW commit instead of amending\n\nImportant notes:\n- NEVER run additional commands to read or explore code, besides git bash commands\n- NEVER use the TodoWrite or Task tools\n- DO NOT push to the remote repository unless the user explicitly asks you to do so\n- IMPORTANT: Never use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input which is not supported.\n- If there are no changes to commit (i.e., no untracked files and no modifications), do not create an empty commit\n- In order to ensure good formatting, ALWAYS pass the commit message via a HEREDOC, a la this example:\n<example>\ngit commit -m \"$(cat <<'EOF'\n Commit message here.\n\n \ud83e\udd16 Generated with [Claude Code](https://claude.com/claude-code)\n\n Co-Authored-By: Claude <noreply@anthropic.com>\n EOF\n )\"\n</example>\n\n# Creating pull requests\nUse the gh command via the Bash tool for ALL GitHub-related tasks including working with issues, pull requests, checks, and releases. If given a Github URL use the gh command to get the information needed.\n\nIMPORTANT: When the user asks you to create a pull request, follow these steps carefully:\n\n1. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following bash commands in parallel using the Bash tool, in order to understand the current state of the branch since it diverged from the main branch:\n - Run a git status command to see all untracked files\n - Run a git diff command to see both staged and unstaged changes that will be committed\n - Check if the current branch tracks a remote branch and is up to date with the remote, so you know if you need to push to the remote\n - Run a git log command and `git diff [base-branch]...HEAD` to understand the full commit history for the current branch (from the time it diverged from the base branch)\n2. Analyze all changes that will be included in the pull request, making sure to look at all relevant commits (NOT just the latest commit, but ALL commits that will be included in the pull request!!!), and draft a pull request summary\n3. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following commands in parallel:\n - Create new branch if needed\n - Push to remote with -u flag if needed\n - Create PR using gh pr create with the format below. Use a HEREDOC to pass the body to ensure correct formatting.\n<example>\ngh pr create --title \"the pr title\" --body \"$(cat <<'EOF'\n## Summary\n<1-3 bullet points>\n\n## Test plan\n[Bulleted markdown checklist of TODOs for testing the pull request...]\n\n\ud83e\udd16 Generated with [Claude Code](https://claude.com/claude-code)\nEOF\n)\"\n</example>\n\nImportant:\n- DO NOT use the TodoWrite or Task tools\n- Return the PR URL when you're done, so the user can see it\n\n# Other common operations\n- View comments on a Github PR: gh api repos/foo/bar/pulls/123/comments",
"input_schema": {
"type": "object",
"properties": {
"command": {
"type": "string",
"description": "The command to execute"
},
"timeout": {
"type": "number",
"description": "Optional timeout in milliseconds (max 600000)"
},
"description": {
"type": "string",
"description": "Clear, concise description of what this command does in 5-10 words, in active voice. Examples:\nInput: ls\nOutput: List files in current directory\n\nInput: git status\nOutput: Show working tree status\n\nInput: npm install\nOutput: Install package dependencies\n\nInput: mkdir foo\nOutput: Create directory 'foo'"
},
"run_in_background": {
"type": "boolean",
"description": "Set to true to run this command in the background. Use TaskOutput to read the output later."
},
"dangerouslyDisableSandbox": {
"type": "boolean",
"description": "Set this to true to dangerously override sandbox mode and run commands without sandboxing."
}
},
"required": [
"command"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
在持久的shell会话中执行给定的bash命令，支持可选的超时设置，确保正确的处理和安全措施。
重要说明：此工具用于终端操作，如git、npm、docker等。不要将其用于文件操作（读取、写入、编辑、搜索、查找文件），对此应该使用专门的工具。
在执行命令之前，请遵循以下步骤：
1. 目录验证：
- 如果命令将创建新目录或文件，首先使用`ls`验证父目录存在并且是正确的位置
- 例如，在运行"mkdir foo/bar"之前，首先使用`ls foo`检查"foo"存在并且是预期的父目录
2. 命令执行：
- 始终使用双引号括起包含空格的文件路径（例如 cd "path with spaces/file.txt"）
- 正确引用的示例：
- cd "/Users/name/My Documents"（正确）
- cd /Users/name/My Documents（错误，会失败）
- python "/path/with spaces/script.py"（正确）
- python /path/with spaces/script.py（错误，会失败）
- 确保正确引用后，执行命令。
- 捕获命令的输出。
使用注意事项：
- command参数是必需的。
- 你可以指定以毫秒为单位的可选超时（最多600000ms / 10分钟）。如果未指定，命令将在120000ms（2分钟）后超时。
- 如果你用5-10个词写清楚简洁地描述这个命令做什么，会很有帮助。
- 如果输出超过30000个字符，输出将在返回给你之前被截断。
- 你可以使用`run_in_background`参数在后台运行命令，这允许你在命令运行时继续工作。你可以使用Bash工具在输出可用时监控它。使用此参数时不需要在命令末尾使用'&'。
- 避免将Bash与`find`、`grep`、`cat`、`head`、`tail`、`sed`、`awk`或`echo`命令一起使用，除非明确指示或这些命令对任务确实是必需的。相反，始终优先使用这些命令的专门工具：
- 文件搜索：使用Glob（而不是find或ls）
- 内容搜索：使用Grep（而不是grep或rg）
- 读取文件：使用Read（而不是cat/head/tail）
- 编辑文件：使用Edit（而不是sed/awk）
- 写入文件：使用Write（而不是echo >/cat <<EOF）
- 通信：直接输出文本（而不是echo/printf）
- 发出多个命令时：
- 如果命令是独立的并且可以并行运行，在单个消息中进行多个Bash工具调用。例如，如果需要运行"git status"和"git diff"，发送一个包含两个并行Bash工具调用的单个消息。
- 如果命令相互依赖并且必须顺序运行，使用单个Bash调用并用'&&'将它们链接在一起（例如，`git add . && git commit -m "message" && git push`）。例如，如果一个操作必须在另一个操作开始之前完成（如mkdir在cp之前，Write在git操作的Bash之前，或git add在git commit之前），则按顺序运行这些操作。
- 仅当你需要按顺序运行命令但不在乎之前的命令是否失败时才使用';'
- 不要使用换行符分隔命令（引号字符串中的换行符是可以的）
- 尝试通过使用绝对路径并避免使用`cd`来在整个会话中保持当前工作目录。如果用户明确要求，你可以使用`cd`。
<good-example>
pytest /foo/bar/tests
</good-example>
<bad-example>
cd /foo/bar && pytest tests
</bad-example>
# 使用git提交更改
仅在用户请求时才创建提交。如果不清楚，请先询问。当用户要求你创建新的git提交时，请仔细遵循以下步骤：
Git安全协议：
- 永远不要更新git配置
- 永远不要运行破坏性/不可逆的git命令（如push --force、hard reset等），除非用户明确要求
- 永远不要跳过钩子（--no-verify、--no-gpg-sign等），除非用户明确要求
- 永远不要强制推送到main/master，如果用户要求则警告用户
- 避免git commit --amend。仅在满足所有条件时使用--amend：
(1) 用户明确要求修改，或者提交成功但pre-commit钩子自动修改了需要包含的文件
(2) HEAD提交是你在本次对话中创建的（验证：git log -1 --format='%an %ae'）
(3) 提交尚未推送到远程（验证：git status显示"Your branch is ahead"）
- 关键：如果提交失败或被钩子拒绝，永远不要修改，修复问题并创建新的提交
- 关键：如果你已经推送到远程，除非用户明确要求（需要强制推送），否则永远不要修改
- 永远不要提交更改，除非用户明确要求你这样做。非常重要，只有在明确要求时才提交，否则用户会觉得你太主动了。
1. 你可以在单个响应中调用多个工具。当请求多个独立的信息片段并且所有命令都可能成功时，为获得最佳性能并行运行多个工具调用。并行运行以下bash命令，每个都使用Bash工具：
- 运行git status命令以查看所有未跟踪的文件。
- 运行git diff命令以查看将要提交的已暂存和未暂存的更改。
- 运行git log命令以查看最近的提交消息，以便你可以遵循此存储库的提交消息风格。
2. 分析所有已暂存的更改（之前已暂存的和新添加的）并起草提交消息：
- 总结更改的性质（例如，新功能、对现有功能的增强、错误修复、重构、测试、文档等）。确保消息准确反映更改及其目的（即"add"意味着全新的功能，"update"意味着对现有功能的增强，"fix"意味着错误修复等）。
- 不要提交可能包含机密的文件（.env、credentials.json等）。如果他们特别要求提交这些文件，请警告用户
- 起草一个简洁（1-2句话）的提交消息，专注于"为什么"而不是"是什么"
- 确保它准确反映更改及其目的
3. 你可以在单个响应中调用多个工具。当请求多个独立的信息片段并且所有命令都可能成功时，为获得最佳性能并行运行多个工具调用。并行运行以下命令：
- 将相关的未跟踪文件添加到暂存区。
- 使用以以下内容结尾的消息创建提交：
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- 提交完成后运行git status以验证成功。
注意：git status取决于提交完成，所以在提交后按顺序运行它。
4. 如果由于pre-commit钩子导致提交失败：
- 如果钩子拒绝了提交（非零退出）：修复问题，然后创建新的提交（永远不要修改）
- 如果提交成功但钩子自动修改了文件（例如，格式化）：你可以修改以包含它们，但仅当：
* HEAD是由你创建的（验证：git log -1 --format='%an %ae'）
* 提交未推送（验证：git status显示"Your branch is ahead"）
- 如果有疑问，创建一个新的提交而不是修改
重要说明：
- 除了git bash命令外，永远不要运行其他命令来读取或探索代码
- 永远不要使用TodoWrite或Task工具
- 除非用户明确要求，否则不要推送到远程存储库
- 重要：永远不要使用带有-i标志的git命令（如git rebase -i或git add -i），因为它们需要交互式输入，而这是不支持的。
- 如果没有要提交的更改（即，没有未跟踪的文件且没有修改），不要创建空的提交
- 为了确保良好的格式，始终通过HEREDOC传递提交消息，如下例所示：
<example>
git commit -m "$(cat <<'EOF'
Commit message here.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
</example>
# 创建拉取请求
通过Bash工具使用gh命令来处理所有与GitHub相关的任务，包括处理问题、拉取请求、检查和发布。如果给出Github URL，使用gh命令获取所需的信息。
重要说明：当用户要求你创建拉取请求时，请仔细遵循以下步骤：
1. 你可以在单个响应中调用多个工具。当请求多个独立的信息片段并且所有命令都可能成功时，为获得最佳性能并行运行多个工具调用。使用Bash工具并行运行以下bash命令，以便了解分支自与主分支分离以来的当前状态：
- 运行git status命令以查看所有未跟踪的文件
- 运行git diff命令以查看将要提交的已暂存和未暂存的更改
- 检查当前分支是否跟踪远程分支并且与远程最新，以便你是否需要推送到远程
- 运行git log命令和`git diff [base-branch]...HEAD`以了解当前分支的完整提交历史（从与基础分支分离的时间开始）
2. 分析将包含在拉取请求中的所有更改，确保查看所有相关的提交（不仅仅是最新的提交，而是将包含在拉取请求中的所有提交！！！），并起草拉取请求摘要
3. 你可以在单个响应中调用多个工具。当请求多个独立的信息片段并且所有命令都可能成功时，为获得最佳性能并行运行多个工具调用。并行运行以下命令：
- 如果需要，创建新分支
- 如果需要，使用-u标志推送到远程
- 使用gh pr create创建PR，格式如下。使用HEREDOC传递主体以确保正确的格式。
<example>
gh pr create --title "the pr title" --body "$(cat <<'EOF'
## Summary
<1-3 bullet points>
## Test plan
[Bulleted markdown checklist of TODOs for testing the pull request...]
🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"
</example>
重要说明：
- 不要使用TodoWrite或Task工具
- 完成后返回PR URL，以便用户可以看到它
# 其他常见操作
- 查看Github PR上的评论：gh api repos/foo/bar/pulls/123/comments【浅析】Bash 是执行终端命令的工具，描述巨长，光是 git 相关的规则就写了一大堆。
核心思路：Bash 只干终端的事（git、npm、docker），文件操作用专门的工具（Read、Write、Edit、Glob、Grep）。这种分离设计挺清晰的。
描述里有很多实用的规则：
-
• 路径有空格必须用双引号
-
• 尽量用绝对路径，少 cd
-
• 独立命令并行跑，依赖命令用 && 串起来
-
• find、grep、cat 这些别用，有专门的工具
Git 安全协议写得很细：不改 git config、不跑 force push、不跳 hooks。什么时候能 amend 什么时候不能，条件列得清清楚楚。这些规则应该是踩过坑总结出来的。
还有个 dangerouslyDisableSandbox 参数，名字就告诉你别瞎用。
Glob
{
"name": "Glob",
"description": "- Fast file pattern matching tool that works with any codebase size\n- Supports glob patterns like \"**/*.js\" or \"src/**/*.ts\"\n- Returns matching file paths sorted by modification time\n- Use this tool when you need to find files by name patterns\n- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead\n- You can call multiple tools in a single response. It is always better to speculatively perform multiple searches in parallel if they are potentially useful.",
"input_schema": {
"type": "object",
"properties": {
"pattern": {
"type": "string",
"description": "The glob pattern to match files against"
},
"path": {
"type": "string",
"description": "The directory to search in. If not specified, the current working directory will be used. IMPORTANT: Omit this field to use the default directory. DO NOT enter \"undefined\" or \"null\" - simply omit it for the default behavior. Must be a valid directory path if provided."
}
},
"required": [
"pattern"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
- 适用于任何代码库大小的快速文件模式匹配工具
- 支持glob模式，如"**/*.js"或"src/**/*.ts"
- 返回按修改时间排序的匹配文件路径
- 当你需要按名称模式查找文件时使用此工具
- 当你进行可能需要多轮glob和grep的开放式搜索时，改用Agent工具
- 你可以在单个响应中调用多个工具。如果有潜在用处，推测性地并行执行多个搜索总是更好的。【浅析】Glob 用来按文件名模式搜索，支持 **/*.js、src/**/*.ts这种 glob 语法。结果按修改时间排序，最近改的排前面。
有个设计原则：简单搜索用 Glob，开放式探索（可能多轮 glob + grep）用 Task 启动 Explore 代理。工具分层，各司其职。
多次强调并行执行：推测性地并行搜多个可能有用的文件总是更好的。别一个一个搜，一起搜。
Grep
{
"name": "Grep",
"description": "A powerful search tool built on ripgrep\n\n Usage:\n - ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.\n - Supports full regex syntax (e.g., \"log.*Error\", \"function\\s+\\w+\")\n - Filter files with glob parameter (e.g., \"*.js\", \"**/*.tsx\") or type parameter (e.g., \"js\", \"py\", \"rust\")\n - Output modes: \"content\" shows matching lines, \"files_with_matches\" shows only file paths (default), \"count\" shows match counts\n - Use Task tool for open-ended searches requiring multiple rounds\n - Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use `interface\\{\\}` to find `interface{}` in Go code)\n - Multiline matching: By default patterns match within single lines only. For cross-line patterns like `struct \\{[\\s\\S]*?field`, use `multiline: true`\n",
"input_schema": {
"type": "object",
"properties": {
"pattern": {
"type": "string",
"description": "The regular expression pattern to search for in file contents"
},
"path": {
"type": "string",
"description": "File or directory to search in (rg PATH). Defaults to current working directory."
},
"glob": {
"type": "string",
"description": "Glob pattern to filter files (e.g. \"*.js\", \"*.{ts,tsx}\") - maps to rg --glob"
},
"output_mode": {
"type": "string",
"enum": [
"content",
"files_with_matches",
"count"
],
"description": "Output mode: \"content\" shows matching lines (supports -A/-B/-C context, -n line numbers, head_limit), \"files_with_matches\" shows file paths (supports head_limit), \"count\" shows match counts (supports head_limit). Defaults to \"files_with_matches\"."
},
"-B": {
"type": "number",
"description": "Number of lines to show before each match (rg -B). Requires output_mode: \"content\", ignored otherwise."
},
"-A": {
"type": "number",
"description": "Number of lines to show after each match (rg -A). Requires output_mode: \"content\", ignored otherwise."
},
"-C": {
"type": "number",
"description": "Number of lines to show before and after each match (rg -C). Requires output_mode: \"content\", ignored otherwise."
},
"-n": {
"type": "boolean",
"description": "Show line numbers in output (rg -n). Requires output_mode: \"content\", ignored otherwise. Defaults to true."
},
"-i": {
"type": "boolean",
"description": "Case insensitive search (rg -i)"
},
"type": {
"type": "string",
"description": "File type to search (rg --type). Common types: js, py, rust, go, java, etc. More efficient than include for standard file types."
},
"head_limit": {
"type": "number",
"description": "Limit output to first N lines/entries, equivalent to \"| head -N\". Works across all output modes: content (limits output lines), files_with_matches (limits file paths), count (limits count entries). Defaults to 0 (unlimited)."
},
"offset": {
"type": "number",
"description": "Skip first N lines/entries before applying head_limit, equivalent to \"| tail -n +N | head -N\". Works across all output modes. Defaults to 0."
},
"multiline": {
"type": "boolean",
"description": "Enable multiline mode where . matches newlines and patterns can span lines (rg -U --multiline-dotall). Default: false."
}
},
"required": [
"pattern"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
一个基于ripgrep构建的强大搜索工具
使用方法：
- 始终使用Grep进行搜索任务。永远不要将`grep`或`rg`作为Bash命令调用。Grep工具已针对正确的权限和访问进行了优化。
- 支持完整的正则表达式语法（例如，"log.*Error"、"function\s+\w+"）
- 使用glob参数（例如，"*.js"、"**/*.tsx"）或type参数（例如，"js"、"py"、"rust"）过滤文件
- 输出模式："content"显示匹配行，"files_with_matches"仅显示文件路径（默认），"count"显示匹配计数
- 对于需要多轮的开放式搜索，使用Task工具
- 模式语法：使用ripgrep（而不是grep）- 字面大括号需要转义（使用`interface\{\}`在Go代码中查找`interface{}`）
- 多行匹配：默认情况下，模式仅匹配单行内的内容。对于跨行模式如`struct \{[\s\S]*?field`，使用`multiline: true`
【浅析】Grep 基于 ripgrep，专门搜代码内容。支持正则、文件类型过滤、三种输出模式（content 显示匹配行、files_with_matches 只显示文件路径、count 显示计数）。
-B、-A、-C 参数可以显示匹配行前后的上下文，理解代码很有用。还支持多行匹配（multiline 参数）。
一个原则：永远用 Grep 工具，别用 Bash 跑 grep 或 rg。工具已经优化过权限了。
跟 Glob 一样，复杂的多轮搜索用 Task 启动 Explore 代理。
ExitPlanMode
{
"name": "ExitPlanMode",
"description": "Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.\n\n## How This Tool Works\n- You should have already written your plan to the plan file specified in the plan mode system message\n- This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote\n- This tool simply signals that you're done planning and ready for the user to review and approve\n- The user will see the contents of your plan file when they review it\n\n## When to Use This Tool\nIMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.\n\n## Handling Ambiguity in Plans\nBefore using this tool, ensure your plan is clear and unambiguous. If there are multiple valid approaches or unclear requirements:\n1. Use the AskUserQuestion tool to clarify with the user\n2. Ask about specific implementation choices (e.g., architectural patterns, which library to use)\n3. Clarify any assumptions that could affect the implementation\n4. Edit your plan file to incorporate user feedback\n5. Only proceed with ExitPlanMode after resolving ambiguities and updating the plan file\n\n## Examples\n\n1. Initial task: \"Search for and understand the implementation of vim mode in the codebase\" - Do not use the exit plan mode tool because you are not planning the implementation steps of a task.\n2. Initial task: \"Help me implement yank mode for vim\" - Use the exit plan mode tool after you have finished planning the implementation steps of the task.\n3. Initial task: \"Add a new feature to handle user authentication\" - If unsure about auth method (OAuth, JWT, etc.), use AskUserQuestion first, then use exit plan mode tool after clarifying the approach.\n",
"input_schema": {
"type": "object",
"properties": {
"launchSwarm": {
"type": "boolean",
"description": "Whether to launch a swarm to implement the plan"
},
"teammateCount": {
"type": "number",
"description": "Number of teammates to spawn in the swarm"
}
},
"additionalProperties": true,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
当你处于计划模式并且已经完成将计划写入计划文件并准备获得用户批准时，使用此工具。
## 此工具的工作原理
- 你应该已经将计划写入计划模式系统消息中指定的计划文件
- 此工具不接受计划内容作为参数，它将从你写入的文件中读取计划
- 此工具仅表示你已完成计划并准备好供用户审查和批准
- 用户在审查时会看到你的计划文件的内容
## 何时使用此工具
重要说明：仅当任务需要规划需要编写代码的任务的实现步骤时，才使用此工具。对于你正在收集信息、搜索文件、读取文件或通常试图理解代码库的研究任务，不要使用此工具。
## 处理计划中的歧义
在使用此工具之前，确保你的计划清晰且无歧义。如果有多种有效方法或要求不明确：
1. 使用AskUserQuestion工具与用户澄清
2. 询问特定的实现选择（例如，架构模式、使用哪个库）
3. 澄清任何可能影响实现的假设
4. 编辑计划文件以纳入用户反馈
5. 仅在解决歧义并更新计划文件后才继续使用ExitPlanMode
## 示例
1. 初始任务："搜索并理解代码库中vim模式的实现" - 不要使用退出计划模式工具，因为你不是在规划任务的实现步骤。
2. 初始任务："帮我实现vim的yank模式" - 在你完成规划任务的实现步骤后，使用退出计划模式工具。
3. 初始任务："添加一个新功能来处理用户身份验证" - 如果不确定身份验证方法（OAuth、JWT等），首先使用AskUserQuestion，然后在澄清方法后使用退出计划模式工具。
【浅析】ExitPlanMode 是计划模式的退出工具。写完计划文件之后调用，让用户审查批准。
一个有意思的设计：这个工具不接收计划内容作为参数，而是从之前写入的文件里读。就是说计划必须先落盘为文件，不能光在对话里说说。
使用限制：只用于需要写代码的任务。研究类任务（搜文件、读代码、理解代码库）不用这个工具。
还有个 launchSwarm 参数，可以启动一群 agents 来执行计划。看起来像是用于复杂任务的并行分发。
Read
{
"name": "Read",
"description": "Reads a file from the local filesystem. You can access any file directly by using this tool.\nAssume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.\n\nUsage:\n- The file_path parameter must be an absolute path, not a relative path\n- By default, it reads up to 2000 lines starting from the beginning of the file\n- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters\n- Any lines longer than 2000 characters will be truncated\n- Results are returned using cat -n format, with line numbers starting at 1\n- This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.\n- This tool can read PDF files (.pdf). PDFs are processed page by page, extracting both text and visual content for analysis.\n- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.\n- This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.\n- You can call multiple tools in a single response. It is always better to speculatively read multiple potentially useful files in parallel.\n- You will regularly be asked to read screenshots. If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths.\n- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.",
"input_schema": {
"type": "object",
"properties": {
"file_path": {
"type": "string",
"description": "The absolute path to the file to read"
},
"offset": {
"type": "number",
"description": "The line number to start reading from. Only provide if the file is too large to read at once"
},
"limit": {
"type": "number",
"description": "The number of lines to read. Only provide if the file is too large to read at once."
}
},
"required": [
"file_path"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
从本地文件系统读取文件。你可以使用此工具直接访问任何文件。
假设此工具能够读取计算机上的所有文件。如果用户提供了文件路径，假设该路径有效。读取不存在的文件是可以的，将返回错误。
使用方法：
- file_path参数必须是绝对路径，而不是相对路径
- 默认情况下，它从文件开头开始读取最多2000行
- 你可以选择指定行偏移和限制（对于长文件特别方便），但建议通过不提供这些参数来读取整个文件
- 任何超过2000个字符的行都将被截断
- 结果使用cat -n格式返回，行号从1开始
- 此工具允许Claude Code读取图像（例如PNG、JPG等）。当读取图像文件时，内容以视觉方式呈现，因为Claude Code是一个多模态大语言模型。
- 此工具可以读取PDF文件（.pdf）。PDF逐页处理，提取文本和视觉内容以进行分析。
- 此工具可以读取Jupyter notebook（.ipynb文件）并返回所有单元格及其输出，结合代码、文本和可视化。
- 此工具只能读取文件，不能读取目录。要读取目录，请通过Bash工具使用ls命令。
- 你可以在单个响应中调用多个工具。推测性地并行读取多个可能有用的文件总是更好的。
- 你经常会被要求读取屏幕截图。如果用户提供了屏幕截图的路径，始终使用此工具查看该路径的文件。此工具适用于所有临时文件路径。
- 如果你读取一个存在但内容为空的文件，你将收到系统提醒警告，而不是文件内容。【浅析】Read 是读文件的核心工具。支持多种格式：普通文本、图片（PNG/JPG）、PDF、Jupyter notebook。因为 Claude Code 是多模态的，所以图片可以直接「看」。
默认读前 2000 行，超过 2000 字符的行会截断。offset 和 limit 参数可以指定读取范围，但建议尽量读整个文件。
file_path 必须是绝对路径。只能读文件不能读目录，读目录用 Bash 跑 ls。
Edit
{
"name": "Edit",
"description": "Performs exact string replacements in files. \n\nUsage:\n- You must use your `Read` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file. \n- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.\n- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.\n- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.\n- The edit will FAIL if `old_string` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use `replace_all` to change every instance of `old_string`. \n- Use `replace_all` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.",
"input_schema": {
"type": "object",
"properties": {
"file_path": {
"type": "string",
"description": "The absolute path to the file to modify"
},
"old_string": {
"type": "string",
"description": "The text to replace"
},
"new_string": {
"type": "string",
"description": "The text to replace it with (must be different from old_string)"
},
"replace_all": {
"type": "boolean",
"default": false,
"description": "Replace all occurences of old_string (default false)"
}
},
"required": [
"file_path",
"old_string",
"new_string"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
在文件中执行精确的字符串替换。
使用方法：
- 在编辑之前，你必须在对话中至少使用一次`Read`工具。如果你尝试在未读取文件的情况下进行编辑，此工具将报错。
- 从Read工具输出编辑文本时，确保保留在行号前缀之后出现的精确缩进（制表符/空格）。行号前缀格式是：空格+行号+制表符。该制表符之后的所有内容都是要匹配的实际文件内容。永远不要在old_string或new_string中包含行号前缀的任何部分。
- 始终优先编辑代码库中的现有文件。除非明确要求，否则永远不要写入新文件。
- 仅在用户明确要求时才使用表情符号。除非被要求，否则避免在文件中添加表情符号。
- 如果`old_string`在文件中不唯一，编辑将失败。提供具有更多周围上下文的更大字符串以使其唯一，或使用`replace_all`来更改`old_string`的每个实例。
- 使用`replace_all`来替换和重命名文件中的字符串。如果你想重命名变量，此参数很有用。【浅析】Edit 用来做字符串替换。old_string 指定要替换的内容，new_string 指定替换后的内容。
关键约束：必须先 Read 了文件才能 Edit。不然会报错。这是为了确保模型知道文件内容是啥再改。
缩进处理有讲究：Read 输出的格式是「空格+行号+制表符+实际内容」，制表符之后的才是真正的文件内容。要保持精确的缩进，不能把行号前缀带进去。
如果 old_string 在文件里不唯一，会失败。解决方法：多带点上下文让它唯一，或者用 replace_all 参数全部替换。
还强调了：优先编辑现有文件，别随便新建文件。
Write
{
"name": "Write",
"description": "Writes a file to the local filesystem.\n\nUsage:\n- This tool will overwrite the existing file if there is one at the provided path.\n- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.\n- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.\n- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.",
"input_schema": {
"type": "object",
"properties": {
"file_path": {
"type": "string",
"description": "The absolute path to the file to write (must be absolute, not relative)"
},
"content": {
"type": "string",
"description": "The content to write to the file"
}
},
"required": [
"file_path",
"content"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
将文件写入本地文件系统。
使用方法：
- 如果提供的路径处存在现有文件，此工具将覆盖它。
- 如果这是现有文件，你必须首先使用Read工具读取文件内容。如果你没有先读取文件，此工具将失败。
- 始终优先编辑代码库中的现有文件。除非明确要求，否则永远不要写入新文件。
- 永远不要主动创建文档文件（*.md）或README文件。仅在用户明确要求时才创建文档文件。
- 仅在用户明确要求时才使用表情符号。除非被要求，否则避免将表情符号写入文件。【浅析】Write 用来写文件，会完全覆盖现有内容。
跟 Edit 一样：如果是现有文件，必须先 Read 再 Write。不然会失败。这是为了防止意外覆盖重要文件。
还有几个原则：
-
• 优先编辑现有文件，别随便新建
-
• 不要主动创建文档文件（*.md）或 README
-
• 不要加 emoji，除非用户明确要求
部分修改用 Edit，完全重写用 Write。分工明确。
NotebookEdit
{
"name": "NotebookEdit",
"description": "Completely replaces the contents of a specific cell in a Jupyter notebook (.ipynb file) with new source. Jupyter notebooks are interactive documents that combine code, text, and visualizations, commonly used for data analysis and scientific computing. The notebook_path parameter must be an absolute path, not a relative path. The cell_number is 0-indexed. Use edit_mode=insert to add a new cell at the index specified by cell_number. Use edit_mode=delete to delete the cell at the index specified by cell_number.",
"input_schema": {
"type": "object",
"properties": {
"notebook_path": {
"type": "string",
"description": "The absolute path to the Jupyter notebook file to edit (must be absolute, not relative)"
},
"cell_id": {
"type": "string",
"description": "The ID of the cell to edit. When inserting a new cell, the new cell will be inserted after the cell with this ID, or at the beginning if not specified."
},
"new_source": {
"type": "string",
"description": "The new source for the cell"
},
"cell_type": {
"type": "string",
"enum": [
"code",
"markdown"
],
"description": "The type of the cell (code or markdown). If not specified, it defaults to the current cell type. If using edit_mode=insert, this is required."
},
"edit_mode": {
"type": "string",
"enum": [
"replace",
"insert",
"delete"
],
"description": "The type of edit to make (replace, insert, delete). Defaults to replace."
}
},
"required": [
"notebook_path",
"new_source"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
用新源代码完全替换Jupyter notebook（.ipynb文件）中特定单元格的内容。Jupyter notebook是结合代码、文本和可视化的交互式文档，通常用于数据分析和科学计算。notebook_path参数必须是绝对路径，而不是相对路径。cell_number是从0开始索引的。使用edit_mode=insert在cell_number指定的索引处添加新单元格。使用edit_mode=delete删除cell_number指定的索引处的单元格。【浅析】NotebookEdit 专门编辑 Jupyter notebook（.ipynb）。notebook 不是普通文本文件，是 JSON 结构，含多个单元格。
三种编辑模式：replace（替换，默认）、insert（插入）、delete（删除）。cell_id 指定要操作的单元格。
cell_type 参数指定单元格类型（code 或 markdown），插入模式必填。
Read 工具也能读 .ipynb，但 NotebookEdit 提供了更精细的单元格操作能力。
WebFetch
{
"name": "WebFetch",
"description": "\n- Fetches content from a specified URL and processes it using an AI model\n- Takes a URL and a prompt as input\n- Fetches the URL content, converts HTML to markdown\n- Processes the content with the prompt using a small, fast model\n- Returns the model's response about the content\n- Use this tool when you need to retrieve and analyze web content\n\nUsage notes:\n - IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead of this one, as it may have fewer restrictions.\n - The URL must be a fully-formed valid URL\n - HTTP URLs will be automatically upgraded to HTTPS\n - The prompt should describe what information you want to extract from the page\n - This tool is read-only and does not modify any files\n - Results may be summarized if the content is very large\n - Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL\n - When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL to fetch the content.\n",
"input_schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "The URL to fetch content from"
},
"prompt": {
"type": "string",
"description": "The prompt to run on the fetched content"
}
},
"required": [
"url",
"prompt"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
- 从指定的URL获取内容并使用AI模型进行处理
- 接受URL和提示作为输入
- 获取URL内容，将HTML转换为markdown
- 使用小型快速模型根据提示处理内容
- 返回模型关于内容的响应
- 当你需要检索和分析网页内容时使用此工具
使用注意事项：
- 重要说明：如果有MCP提供的网页获取工具可用，优先使用该工具而不是此工具，因为它可能有更少的限制。
- URL必须是格式正确的有效URL
- HTTP URL将自动升级为HTTPS
- 提示应该描述你想从页面中提取什么信息
- 此工具是只读的，不会修改任何文件
- 如果内容非常大，结果可能会被总结
- 包括一个自动清理的15分钟缓存，以便在重复访问同一URL时获得更快的响应
- 当URL重定向到不同的主机时，工具将以特殊格式通知你并提供重定向URL。然后你应该使用重定向URL发出新的WebFetch请求以获取内容。
【浅析】WebFetch 用来拓网页，把 HTML 转成 markdown，然后用小模型根据 prompt 提取信息。
有 15 分钟的自清理缓存，重复访问同一 URL 会快很多。
重定向处理：如果 URL 重定向到不同主机，工具会告诉你并提供重定向 URL，需要再发一次请求。
特别说了：如果有 MCP 提供的网页获取工具，优先用那个，限制更少。
TodoWrite
{
"name": "TodoWrite",
"description": "Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.\nIt also helps the user understand the progress of the task and overall progress of their requests.\n\n## When to Use This Tool\nUse this tool proactively in these scenarios:\n\n1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions\n2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations\n3. User explicitly requests todo list - When the user directly asks you to use the todo list\n4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)\n5. After receiving new instructions - Immediately capture user requirements as todos\n6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time\n7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation\n\n## When NOT to Use This Tool\n\nSkip using this tool when:\n1. There is only a single, straightforward task\n2. The task is trivial and tracking it provides no organizational benefit\n3. The task can be completed in less than 3 trivial steps\n4. The task is purely conversational or informational\n\nNOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.\n\n## Examples of When to Use the Todo List\n\n<example>\nUser: I want to add a dark mode toggle to the application settings. Make sure you run the tests and build when you're done!\nAssistant: I'll help add a dark mode toggle to your application settings. Let me create a todo list to track this implementation.\n*Creates todo list with the following items:*\n1. Creating dark mode toggle component in Settings page\n2. Adding dark mode state management (context/store)\n3. Implementing CSS-in-JS styles for dark theme\n4. Updating existing components to support theme switching\n5. Running tests and build process, addressing any failures or errors that occur\n*Begins working on the first task*\n\n<reasoning>\nThe assistant used the todo list because:\n1. Adding dark mode is a multi-step feature requiring UI, state management, and styling changes\n2. The user explicitly requested tests and build be run afterward\n3. The assistant inferred that tests and build need to pass by adding \"Ensure tests and build succeed\" as the final task\n</reasoning>\n</example>\n\n<example>\nUser: Help me rename the function getCwd to getCurrentWorkingDirectory across my project\nAssistant: Let me first search through your codebase to find all occurrences of 'getCwd'.\n*Uses grep or search tools to locate all instances of getCwd in the codebase*\nAssistant: I've found 15 instances of 'getCwd' across 8 different files. Let me create a todo list to track these changes.\n*Creates todo list with specific items for each file that needs updating*\n\n<reasoning>\nThe assistant used the todo list because:\n1. First, the assistant searched to understand the scope of the task\n2. Upon finding multiple occurrences across different files, it determined this was a complex task with multiple steps\n3. The todo list helps ensure every instance is tracked and updated systematically\n4. This approach prevents missing any occurrences and maintains code consistency\n</reasoning>\n</example>\n\n\n<example>\nUser: I need to implement these features for my e-commerce site: user registration, product catalog, shopping cart, and checkout flow.\nAssistant: I'll help implement these features. First, let's add all the features to the todo list.\n*Creates a todo list breaking down each feature into specific tasks based on the project architecture*\nAssistant: Let's start with user registration. This will involve creating database models, API endpoints, and frontend forms that integrate with your existing authentication system.\n\n<reasoning>\nThe assistant used the todo list because:\n1. The user provided multiple complex features to implement in a comma separated list\n2. The todo list helps organize these large features into manageable tasks\n3. This approach allows for tracking progress across the entire implementation\n</reasoning>\n</example>\n\n<example>\nUser: Can you help optimize my React application? It's rendering slowly and has performance issues.</user>\nAssistant: I'll help optimize your React application. First, let me examine your codebase to identify potential performance bottlenecks.\n*Reviews component structure, render patterns, state management, and data fetching*\nAssistant: After analyzing your codebase, I've identified several performance issues. Let me create a todo list to track our optimization efforts.\n*Creates todo list with items like: 1) Implementing memoization for expensive calculations in ProductList, 2) Adding virtualization for long lists in Dashboard, 3) Optimizing image loading in Gallery component, 4) Fixing state update loops in ShoppingCart, 5) Reviewing bundle size and implementing code splitting*\nLet's start by implementing memoization for the expensive calculations in your ProductList component.</assistant>\n\n<reasoning>\nThe assistant used the todo list because:\n1. First, the assistant examined the codebase to identify specific performance issues\n2. Based on this analysis, it identified multiple optimization opportunities\n3. Performance optimization is a non-trivial task requiring multiple steps\n4. The todo list helps methodically track improvements across different components\n5. This systematic approach ensures all performance bottlenecks are addressed\n</reasoning>\n</example>\n\n## Examples of When NOT to Use the Todo List\n\n<example>\nUser: How do I print 'Hello World' in Python?\nAssistant: In Python, you can print \"Hello World\" with this simple code:\n\npython\nprint(\"Hello World\")\n\nThis will output the text \"Hello World\" to the console when executed.</assistant>\n\n<reasoning>\nThe assistant did not use the todo list because this is a single, trivial task that can be completed in one step. There's no need to track multiple tasks or steps for such a straightforward request.\n</reasoning>\n</example>\n\n<example>\nUser: What does the git status command do?\nAssistant: The git status command shows the current state of your working directory and staging area. It displays which changes have been staged, which haven't, and which files aren't being tracked by Git. This is a fundamental command for understanding the current state of your repository before making commits.\n\n<reasoning>\nThe assistant did not use the todo list because this is an informational request with no actual coding task to complete. The user is simply asking for an explanation, not for the assistant to perform multiple steps or tasks.\n</reasoning>\n</example>\n\n<example>\nUser: Can you add a comment to the calculateTotal function to explain what it does?\nAssistant: Sure, let me add a comment to the calculateTotal function to explain what it does.\n* Uses the Edit tool to add a comment to the calculateTotal function *\n\n<reasoning>\nThe assistant did not use the todo list because this is a single, straightforward task confined to one location in the code. Adding a comment doesn't require tracking multiple steps or systematic organization.\n</reasoning>\n</example>\n\n<example>\nUser: Run npm install for me and tell me what happens.\nAssistant: I'll run the npm install command for you.\n\n*Executes: npm install*\n\nThe command completed successfully. Here's the output:\n[Output of npm install command]\n\nAll dependencies have been installed according to your package.json file.\n\n<reasoning>\nThe assistant did not use the todo list because this is a single command execution with immediate results. There are no multiple steps to track or organize, making the todo list unnecessary for this straightforward task.\n</reasoning>\n</example>\n\n## Task States and Management\n\n1. **Task States**: Use these states to track progress:\n - pending: Task not yet started\n - in_progress: Currently working on (limit to ONE task at a time)\n - completed: Task finished successfully\n\n **IMPORTANT**: Task descriptions must have two forms:\n - content: The imperative form describing what needs to be done (e.g., \"Run tests\", \"Build the project\")\n - activeForm: The present continuous form shown during execution (e.g., \"Running tests\", \"Building the project\")\n\n2. **Task Management**:\n - Update task status in real-time as you work\n - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)\n - Exactly ONE task must be in_progress at any time (not less, not more)\n - Complete current tasks before starting new ones\n - Remove tasks that are no longer relevant from the list entirely\n\n3. **Task Completion Requirements**:\n - ONLY mark a task as completed when you have FULLY accomplished it\n - If you encounter errors, blockers, or cannot finish, keep the task as in_progress\n - When blocked, create a new task describing what needs to be resolved\n - Never mark a task as completed if:\n - Tests are failing\n - Implementation is partial\n - You encountered unresolved errors\n - You couldn't find necessary files or dependencies\n\n4. **Task Breakdown**:\n - Create specific, actionable items\n - Break complex tasks into smaller, manageable steps\n - Use clear, descriptive task names\n - Always provide both forms:\n - content: \"Fix authentication bug\"\n - activeForm: \"Fixing authentication bug\"\n\nWhen in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.\n",
"input_schema": {
"type": "object",
"properties": {
"todos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"content": {
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"enum": [
"pending",
"in_progress",
"completed"
]
},
"activeForm": {
"type": "string",
"minLength": 1
}
},
"required": [
"content",
"status",
"activeForm"
],
"additionalProperties": false
},
"description": "The updated todo list"
}
},
"required": [
"todos"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
使用此工具为当前编码会话创建和管理结构化任务列表。这有助于你跟踪进度、组织复杂任务，并向用户展示工作的全面性。
它还有助于用户了解任务的进度和其请求的总体进度。
## 何时使用此工具
在以下情况下主动使用此工具：
1. 复杂的多步骤任务，当任务需要3个或更多不同的步骤或操作时
2. 非平凡且复杂的任务，需要仔细规划或多个操作的任务
3. 用户明确要求待办事项列表，当用户直接要求你使用待办事项列表时
4. 用户提供多个任务，当用户提供要完成的事项列表（编号或逗号分隔）时
5. 收到新指令后，立即将用户要求捕获为待办事项
6. 当你开始处理任务时，在开始工作之前将其标记为in_progress。理想情况下，你应该一次只有一个待办事项处于in_progress状态
7. 完成任务后，将其标记为已完成，并添加在实施期间发现的任何新的后续任务
## 何时不使用此工具
在以下情况下跳过使用此工具：
1. 只有一个简单直接的任务
2. 任务微不足道，跟踪它没有组织上的好处
3. 任务可以在少于3个简单步骤中完成
4. 任务纯粹是对话性或信息性的
请注意，如果只有一个微不足道的任务要做，你不应该使用此工具。在这种情况下，你最好直接完成任务。
## 何时使用待办事项列表的示例
<example>
User: 我想在应用程序设置中添加一个深色模式切换开关。确保完成后运行测试和构建！
Assistant: 我将帮助你在应用程序设置中添加深色模式切换开关。让我创建一个待办事项列表来跟踪此实现。
*创建包含以下项目的待办事项列表：*
1. 在设置页面中创建深色模式切换组件
2. 添加深色模式状态管理（context/store）
3. 为深色主题实现CSS-in-JS样式
4. 更新现有组件以支持主题切换
5. 运行测试和构建过程，解决发生的任何失败或错误
*开始处理第一个任务*
<reasoning>
助手使用待办事项列表是因为：
1. 添加深色模式是一个需要UI、状态管理和样式更改的多步骤功能
2. 用户明确要求之后运行测试和构建
3. 助手推断测试和构建需要通过添加"确保测试和构建成功"作为最终任务来通过
</reasoning>
</example>
<example>
User: 帮我跨项目将函数getCwd重命名为getCurrentWorkingDirectory
Assistant: 让我先搜索你的代码库以找到'getCwd'的所有出现。
*使用grep或搜索工具在代码库中定位getCwd的所有实例*
Assistant: 我在8个不同的文件中找到了15个'getCwd'实例。让我创建一个待办事项列表来跟踪这些更改。
*创建包含每个需要更新的文件的特定项目的待办事项列表*
<reasoning>
助手使用待办事项列表是因为：
1. 首先，助手搜索以了解任务的范围
2. 在发现不同文件中的多个出现后，它确定这是一个具有多个步骤的复杂任务
3. 待办事项列表有助于确保每个实例都被系统地跟踪和更新
4. 这种方法可以防止遗漏任何出现并保持代码一致性
</reasoning>
</example>
<example>
User: 我需要为我的电子商务网站实现这些功能：用户注册、产品目录、购物车和结账流程。
Assistant: 我将帮助实现这些功能。首先，让我们将所有功能添加到待办事项列表中。
*创建一个基于项目架构将每个功能分解为特定任务的待办事项列表*
Assistant: 让我们从用户注册开始。这将涉及创建数据库模型、API端点以及与现有身份验证系统集成的前端表单。
<reasoning>
助手使用待办事项列表是因为：
1. 用户提供了要在逗号分隔列表中实现的多个复杂功能
2. 待办事项列表有助于将这些大型功能组织为可管理的任务
3. 这种方法允许跟踪整个实施过程中的进度
</reasoning>
</example>
<example>
User: 你能帮我优化我的React应用程序吗？它渲染缓慢并且有性能问题。</user>
Assistant: 我将帮助优化你的React应用程序。首先，让我检查你的代码库以识别潜在的性能瓶颈。
*审查组件结构、渲染模式、状态管理和数据获取*
Assistant: 在分析你的代码库后，我发现了几个性能问题。让我创建一个待办事项列表来跟踪我们的优化工作。
*创建包含以下项目的待办事项列表：1) 为ProductList中的昂贵计算实现记忆化，2) 为Dashboard中的长列表添加虚拟化，3) 优化Gallery组件中的图像加载，4) 修复ShoppingCart中的状态更新循环，5) 审查包大小并实现代码分割*
让我们通过为ProductList组件中的昂贵计算实现记忆化来开始。</assistant>
<reasoning>
助手使用待办事项列表是因为：
1. 首先，助手检查代码库以识别特定的性能问题
2. 基于此分析，它确定了多个优化机会
3. 性能优化是一个需要多个步骤的非平凡任务
4. 待办事项列表有助于有条不紊地跟踪不同组件的改进
5. 这种系统方法可确保解决所有性能瓶颈
</reasoning>
</example>
## 何时不使用待办事项列表的示例
<example>
User: 如何在Python中打印'Hello World'？
Assistant: 在Python中，你可以使用这个简单的代码打印"Hello World"：
python
print("Hello World")
执行后将在控制台输出文本"Hello World"。</assistant>
<reasoning>
助手没有使用待办事项列表，因为这是一个可以在一步中完成的单一、微不足道的任务。对于这样一个直接的请求，不需要跟踪多个任务或步骤。
</reasoning>
</example>
<example>
User: git status命令是做什么的？
Assistant: git status命令显示工作目录和暂存区的当前状态。它显示哪些更改已被暂存，哪些尚未暂存，以及哪些文件未被Git跟踪。这是在提交之前了解存储库当前状态的基本命令。
<reasoning>
助手没有使用待办事项列表，因为这是一个信息性请求，没有要完成 actual 的编码任务。用户只是要求解释，而不是要求助手执行多个步骤或任务。
</reasoning>
</example>
<example>
User: 你能给calculateTotal函数添加一个注释来解释它的作用吗？
Assistant: 当然，让我给calculateTotal函数添加一个注释来解释它的作用。
* 使用Edit工具给calculateTotal函数添加注释 *
<reasoning>
助手没有使用待办事项列表，因为这是一个单一、直接的任务，仅限于代码中的一个位置。添加注释不需要跟踪多个步骤或系统组织。
</reasoning>
</example>
<example>
User: 为我运行npm install并告诉我发生了什么。
Assistant: 我将为你运行npm install命令。
*执行：npm install*
命令成功完成。这是输出：
[npm install命令的输出]
已根据你的package.json文件安装了所有依赖项。
<reasoning>
助手没有使用待办事项列表，因为这是一个具有直接结果的单一命令执行。没有多个步骤要跟踪或组织，使得待办事项列表对于这个直接的任务是不必要的。
</reasoning>
</example>
## 任务状态和管理
1. **任务状态**：使用这些状态来跟踪进度：
- pending：任务尚未开始
- in_progress：正在处理（一次限制为一个任务）
- completed：任务成功完成
**重要**：任务描述必须有两种形式：
- content：描述需要做什么的命令式形式（例如，"运行测试"、"构建项目"）
- activeForm：执行期间显示的现在连续形式（例如，"正在运行测试"、"正在构建项目"）
2. **任务管理**：
- 在工作时实时更新任务状态
- 完成后立即将任务标记为完成（不要批量完成）
- 任何时候必须正好有一个任务处于in_progress状态（不能少，也不能多）
- 在开始新任务之前完成当前任务
- 从列表中完全删除不再相关的任务
3. **任务完成要求**：
- 仅当你完全完成任务时，才将其标记为已完成
- 如果遇到错误、阻塞或无法完成，请将任务保持为in_progress
- 被阻塞时，创建一个描述需要解决什么的新任务
- 在以下情况下永远不要将任务标记为已完成：
- 测试失败
- 实施部分完成
- 遇到未解决的错误
- 你找不到必要的文件或依赖项
4. **任务分解**：
- 创建具体的、可操作的项目
- 将复杂的任务分解为更小的、可管理的步骤
- 使用清晰、描述性的任务名称
- 始终提供两种形式：
- content："修复身份验证错误"
- activeForm："正在修复身份验证错误"
如果有疑问，请使用此工具。在任务管理方面积极主动表现出专注，并确保你成功完成所有要求。
【浅析】TodoWrite 用来管理任务列表。跟踪进度、组织复杂任务、向用户展示工作进度。
使用场景很明确：
-
• 复杂多步骤任务（3 步以上）
-
• 用户提供多个任务
-
• 非平凡且复杂的任务
不该用的场景：
-
• 单一简单任务
-
• 3 步内能完成的
-
• 纯聊天或答疑
任务状态就三种：pending、in_progress、completed。任何时候只能有一个 in_progress。
任务描述要两种形式，content（命令式，如「运行测试」）和 activeForm（进行时，如「正在运行测试」）。这样 UI 上显示更友好。
示例给得很充分，正例反例都有，什么时候用什么时候不用写得很清楚。
WebSearch
{
"name": "WebSearch",
"description": "\n- Allows Claude to search the web and use the results to inform responses\n- Provides up-to-date information for current events and recent data\n- Returns search result information formatted as search result blocks, including links as markdown hyperlinks\n- Use this tool for accessing information beyond Claude's knowledge cutoff\n- Searches are performed automatically within a single API call\n\nCRITICAL REQUIREMENT - You MUST follow this:\n - After answering the user's question, you MUST include a \"Sources:\" section at the end of your response\n - In the Sources section, list all relevant URLs from the search results as markdown hyperlinks: [Title](URL)\n - This is MANDATORY - never skip including sources in your response\n - Example format:\n\n [Your answer here]\n\n Sources:\n - [Source Title 1](https://example.com/1)\n - [Source Title 2](https://example.com/2)\n\nUsage notes:\n - Domain filtering is supported to include or block specific websites\n - Web search is only available in the US\n\nIMPORTANT - Use the correct year in search queries:\n - Today's date is 2026-01-24. You MUST use this year when searching for recent information, documentation, or current events.\n - Example: If today is 2025-07-15 and the user asks for \"latest React docs\", search for \"React documentation 2025\", NOT \"React documentation 2024\"\n",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 2,
"description": "The search query to use"
},
"allowed_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Only include search results from these domains"
},
"blocked_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Never include search results from these domains"
}
},
"required": [
"query"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
- 允许Claude搜索网络并使用结果来告知响应
- 为当前事件和最新数据提供最新信息
- 返回格式化为搜索结果块的搜索结果信息，包括作为markdown超链接的链接
- 使用此工具访问Claude知识截止日期之外的信息
- 搜索在单个API调用中自动执行
关键要求，你必须遵循以下内容：
- 回答用户问题后，你必须在响应末尾包含"Sources:"部分
- 在Sources部分，将搜索结果中的所有相关URL列为markdown超链接：[标题](URL)
- 这是强制性的，永远不要跳过在响应中包含来源
- 示例格式：
[你的答案在这里]
Sources:
- [来源标题1](https://example.com/1)
- [来源标题2](https://example.com/2)
使用注意事项：
- 支持域名过滤以包含或阻止特定网站
- 网络搜索仅在美国可用
重要说明，在搜索查询中使用正确的年份：
- 今天的日期是2026-01-24。在搜索最新信息、文档或当前事件时，你必须使用这一年。
- 示例：如果今天是2025-07-15，用户要求"latest React docs"，则搜索"React documentation 2025"，而不是"React documentation 2024"
【浅析】WebSearch 允许 Claude 搜网，用于获取知识截止日期之外的信息。
一个关键要求：回答后必须在末尾加 Sources 部分，列出所有相关 URL 作为 markdown 超链接。这是强制的，不能跳过。体现了对信息来源透明度的重视。
支持域名过滤：allowed_domains 只要某些网站，blocked_domains 不要某些网站。
还有个注意事项：搜索要用当前年份。因为模型有知识截止日期，可能习惯性用旧年份。
网络搜索只在美国可用。
KillShell
{
"name": "KillShell",
"description": "\n- Kills a running background bash shell by its ID\n- Takes a shell_id parameter identifying the shell to kill\n- Returns a success or failure status \n- Use this tool when you need to terminate a long-running shell\n- Shell IDs can be found using the /tasks command\n",
"input_schema": {
"type": "object",
"properties": {
"shell_id": {
"type": "string",
"description": "The ID of the background shell to kill"
}
},
"required": [
"shell_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
- 通过其ID终止正在运行的后台bash shell
- 接受一个标识要终止的shell的shell_id参数
- 返回成功或失败状态
- 当你需要终止长时间运行的shell时使用此工具
- 可以使用/tasks命令找到shell ID
【浅析】KillShell 用来终止后台运行的 bash shell。是 Bash 工具的配套。
有后台任务（run_in_background）就得有终止的方法。shell_id 通过 /tasks 命令找。
AskUserQuestion
{
"name": "AskUserQuestion",
"description": "Use this tool when you need to ask the user questions during execution. This allows you to:\n1. Gather user preferences or requirements\n2. Clarify ambiguous instructions\n3. Get decisions on implementation choices as you work\n4. Offer choices to the user about what direction to take.\n\nUsage notes:\n- Users will always be able to select \"Other\" to provide custom text input\n- Use multiSelect: true to allow multiple answers to be selected for a question\n- If you recommend a specific option, make that the first option in the list and add \"(Recommended)\" at the end of the label\n",
"input_schema": {
"type": "object",
"properties": {
"questions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "The complete question to ask the user. Should be clear, specific, and end with a question mark. Example: \"Which library should we use for date formatting?\" If multiSelect is true, phrase it accordingly, e.g. \"Which features do you want to enable?\""
},
"header": {
"type": "string",
"description": "Very short label displayed as a chip/tag (max 12 chars). Examples: \"Auth method\", \"Library\", \"Approach\"."
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "The display text for this option that the user will see and select. Should be concise (1-5 words) and clearly describe the choice."
},
"description": {
"type": "string",
"description": "Explanation of what this option means or what will happen if chosen. Useful for providing context about trade-offs or implications."
}
},
"required": [
"label",
"description"
],
"additionalProperties": false
},
"minItems": 2,
"maxItems": 4,
"description": "The available choices for this question. Must have 2-4 options. Each option should be a distinct, mutually exclusive choice (unless multiSelect is enabled). There should be no 'Other' option, that will be provided automatically."
},
"multiSelect": {
"type": "boolean",
"description": "Set to true to allow the user to select multiple options instead of just one. Use when choices are not mutually exclusive."
}
},
"required": [
"question",
"header",
"options",
"multiSelect"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 4,
"description": "Questions to ask the user (1-4 questions)"
},
"answers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "User answers collected by the permission component"
}
},
"required": [
"questions"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
当你需要在执行期间向用户提问时，使用此工具。这使你能够：
1. 收集用户偏好或要求
2. 澄清模糊的指令
3. 在工作时获得关于实现选择的决策
4. 为用户提供关于采取什么方向的选择。
使用注意事项：
- 用户始终能够选择"Other"以提供自定义文本输入
- 使用multiSelect: true允许为一个问题选择多个答案
- 如果你推荐特定选项，请将其作为列表中的第一个选项，并在标签末尾添加"(Recommended)"
【浅析】AskUserQuestion 用于执行期间向用户提问。收集偏好、澄清模糊指令、获取实现决策、提供方向选择。
几个设计：
-
• 用户始终能选「Other」提供自定义输入，不会被限制在预定义选项里
-
• multiSelect 可以多选
-
• 推荐选项放第一个，末尾加「(Recommended)」
一次可以问 1-4 个问题。每个问题要提供 question、header（最多 12 字符）、options（2-4 个选项）、multiSelect。
这个工具的设计体现了对用户意图的尊重。先澄清再动手，避免返工。
Skill
{
"name": "Skill",
"description": "Execute a skill within the main conversation\n\n<skills_instructions>\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.\n\nHow to invoke:\n- Use this tool with the skill name only (no arguments)\n- Examples:\n - `skill: \"pdf\"` - invoke the pdf skill\n - `skill: \"xlsx\"` - invoke the xlsx skill\n - `skill: \"ms-office-suite:pdf\"` - invoke using fully qualified name\n\nImportant:\n- When a skill is relevant, you must invoke this tool IMMEDIATELY as your first action\n- NEVER just announce or mention a skill in your text response without actually calling this tool\n- This is a BLOCKING REQUIREMENT: invoke the relevant Skill tool BEFORE generating any other response about the task\n- Only use skills listed in <available_skills> below\n- Do not invoke a skill that is already running\n- Do not use this tool for built-in CLI commands (like /help, /clear, etc.)\n</skills_instructions>\n\n<available_skills>\n<skill>\n<name>\nfeishu-docx\n</name>\n<description>\nExport Feishu/Lark cloud documents to Markdown. Supports docx, sheets, bitable, and wiki. Use this skill when you need to read, analyze, or reference content from Feishu knowledge base. (project)\n</description>\n<location>\nmanaged\n</location>\n</skill>\n</available_skills>\n",
"input_schema": {
"type": "object",
"properties": {
"skill": {
"type": "string",
"description": "The skill name (no arguments). E.g., \"pdf\" or \"xlsx\""
}
},
"required": [
"skill"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
在主对话中执行技能
<skills_instructions>
当用户要求你执行任务时，检查以下任何可用技能是否可以帮助更有效地完成任务。技能提供专门的功能和领域知识。
如何调用：
- 仅使用技能名称使用此工具（无参数）
- 示例：
- `skill: "pdf"` - 调用pdf技能
- `skill: "xlsx"` - 调用xlsx技能
- `skill: "ms-office-suite:pdf"` - 使用完全限定名称调用
重要说明：
- 当技能相关时，你必须立即将此工具作为你的第一个操作调用
- 永远不要只是在不实际调用此工具的情况下在文本响应中宣布或提及技能
- 这是一个阻止性要求：在生成关于任务的任何其他响应之前调用相关的Skill工具
- 仅使用下面<available_skills>中列出的技能
- 不要调用已经在运行的技能
- 不要将此工具用于内置CLI命令（如/help、/clear等）
</skills_instructions>
<available_skills>
<skill>
<name>
feishu-docx
</name>
<description>
将飞书/Lark云文档导出为Markdown。支持docx、sheets、bitable和wiki。当你需要从飞书知识库读取、分析或参考内容时，请使用此技能。(project)
</description>
<location>
managed
</location>
</skill>
</available_skills>
【浅析】Skill 用于执行技能。技能提供专门的功能和领域知识，帮助更高效地完成任务。
关键设计：「立即调用」。技能相关时必须立即调用，不能只是在文本里提一嘴。这是 BLOCKING REQUIREMENT，生成任何其他响应之前先调用 Skill 工具。
调用方式很简单：只用技能名称，不带参数。比如 skill: "pdf"。
技能系统体现了功能模块化和可扩展性。可以轻松添加新功能而不改核心工具集。
SlashCommand
{
"name": "SlashCommand",
"description": "Execute a slash command within the main conversation\n\nHow slash commands work:\nWhen you use this tool or when a user types a slash command, you will see <command-message>{name} is running\u2026</command-message> followed by the expanded prompt. For example, if .claude/commands/foo.md contains \"Print today's date\", then /foo expands to that prompt in the next message.\n\nUsage:\n- `command` (required): The slash command to execute, including any arguments\n- Example: `command: \"/review-pr 123\"`\n\nIMPORTANT: Only use this tool for custom slash commands that appear in the Available Commands list below. Do NOT use for:\n- Built-in CLI commands (like /help, /clear, etc.)\n- Commands not shown in the list\n- Commands you think might exist but aren't listed\n\nNotes:\n- When a user requests multiple slash commands, execute each one sequentially and check for <command-message>{name} is running\u2026</command-message> to verify each has been processed\n- Do not invoke a command that is already running. For example, if you see <command-message>foo is running\u2026</command-message>, do NOT use this tool with \"/foo\" - process the expanded prompt in the following message\n- Only custom slash commands with descriptions are listed in Available Commands. If a user's command is not listed, ask them to check the slash command file and consult the docs.\n",
"input_schema": {
"type": "object",
"properties": {
"command": {
"type": "string",
"description": "The slash command to execute with its arguments, e.g., \"/review-pr 123\""
}
},
"required": [
"command"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
在主对话中执行斜杠命令
斜杠命令的工作原理：
当你使用此工具或用户输入斜杠命令时，你将看到<command-message>{name} is running…</command-message>，后跟扩展的提示。例如，如果.claude/commands/foo.md包含"Print today's date"，则/foo在下一个消息中扩展为该提示。
使用方法：
- `command`（必需）：要执行的斜杠命令，包括任何参数
- 示例：`command: "/review-pr 123"`
重要说明：仅将此工具用于下面"Available Commands"列表中出现的自定义斜杠命令。不要用于：
- 内置CLI命令（如/help、/clear等）
- 列表中未显示的命令
- 你认为可能存在但未列出的命令
注意事项：
- 当用户请求多个斜杠命令时，按顺序执行每个命令并检查<command-message>{name} is running…</command-message>以验证每个命令都已处理
- 不要调用已经在运行的命令。例如，如果你看到<command-message>foo is running…</command-message>，不要使用"/foo"调用此工具，处理以下消息中的扩展提示
- Available Commands中仅列出了带有描述的自定义斜杠命令。如果用户的命令未列出，请他们检查斜杠命令文件并查阅文档。
【浅析】SlashCommand 用于执行斜杠命令。斜杠命令是用户自定义的，存在 .claude/commands/ 目录下的 .md 文件里。
工作原理：比如 .claude/commands/foo.md 包含「Print today's date」，则 /foo 会扩展为这个提示。类似于别名或宏。
使用限制：只能用于 Available Commands 列表里的自定义命令。不能用于内置命令（如 /help）、未列出的命令、称“我觉得可能存在”的命令。
用户可以通过创建斜杠命令封装常用的提示或操作序列，提高效率。
EnterPlanMode
{
"name": "EnterPlanMode",
"description": "Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.\n\n## When to Use This Tool\n\n**Prefer using EnterPlanMode** for implementation tasks unless they're simple. Use it when ANY of these conditions apply:\n\n1. **New Feature Implementation**: Adding meaningful new functionality\n - Example: \"Add a logout button\" - where should it go? What should happen on click?\n - Example: \"Add form validation\" - what rules? What error messages?\n\n2. **Multiple Valid Approaches**: The task can be solved in several different ways\n - Example: \"Add caching to the API\" - could use Redis, in-memory, file-based, etc.\n - Example: \"Improve performance\" - many optimization strategies possible\n\n3. **Code Modifications**: Changes that affect existing behavior or structure\n - Example: \"Update the login flow\" - what exactly should change?\n - Example: \"Refactor this component\" - what's the target architecture?\n\n4. **Architectural Decisions**: The task requires choosing between patterns or technologies\n - Example: \"Add real-time updates\" - WebSockets vs SSE vs polling\n - Example: \"Implement state management\" - Redux vs Context vs custom solution\n\n5. **Multi-File Changes**: The task will likely touch more than 2-3 files\n - Example: \"Refactor the authentication system\"\n - Example: \"Add a new API endpoint with tests\"\n\n6. **Unclear Requirements**: You need to explore before understanding the full scope\n - Example: \"Make the app faster\" - need to profile and identify bottlenecks\n - Example: \"Fix the bug in checkout\" - need to investigate root cause\n\n7. **User Preferences Matter**: The implementation could reasonably go multiple ways\n - If you would use AskUserQuestion to clarify the approach, use EnterPlanMode instead\n - Plan mode lets you explore first, then present options with context\n\n## When NOT to Use This Tool\n\nOnly skip EnterPlanMode for simple tasks:\n- Single-line or few-line fixes (typos, obvious bugs, small tweaks)\n- Adding a single function with clear requirements\n- Tasks where the user has given very specific, detailed instructions\n- Pure research/exploration tasks (use the Task tool with explore agent instead)\n\n## What Happens in Plan Mode\n\nIn plan mode, you'll:\n1. Thoroughly explore the codebase using Glob, Grep, and Read tools\n2. Understand existing patterns and architecture\n3. Design an implementation approach\n4. Present your plan to the user for approval\n5. Use AskUserQuestion if you need to clarify approaches\n6. Exit plan mode with ExitPlanMode when ready to implement\n\n## Examples\n\n### GOOD - Use EnterPlanMode:\nUser: \"Add user authentication to the app\"\n- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)\n\nUser: \"Optimize the database queries\"\n- Multiple approaches possible, need to profile first, significant impact\n\nUser: \"Implement dark mode\"\n- Architectural decision on theme system, affects many components\n\nUser: \"Add a delete button to the user profile\"\n- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates\n\nUser: \"Update the error handling in the API\"\n- Affects multiple files, user should approve the approach\n\n### BAD - Don't use EnterPlanMode:\nUser: \"Fix the typo in the README\"\n- Straightforward, no planning needed\n\nUser: \"Add a console.log to debug this function\"\n- Simple, obvious implementation\n\nUser: \"What files handle routing?\"\n- Research task, not implementation planning\n\n## Important Notes\n\n- This tool REQUIRES user approval - they must consent to entering plan mode\n- If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work\n- Users appreciate being consulted before significant changes are made to their codebase\n",
"input_schema": {
"type": "object",
"properties": {},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
}Description-简要翻译
当你即将开始一个非平凡的实施任务时，主动使用此工具。在编写代码之前获得用户对方法的签名可防止浪费精力并确保一致性。此工具将你转换为计划模式，你可以在其中探索代码库并为用户批准设计实施方法。
## 何时使用此工具
**除非实施任务很简单，否则优先使用EnterPlanMode**。当以下任何条件适用时使用它：
1. **新功能实施**：添加有意义的新功能
- 示例："添加一个注销按钮" - 应该放在哪里？点击后应该发生什么？
- 示例："添加表单验证" - 什么规则？什么错误消息？
2. **多种有效方法**：任务可以通过几种不同的方式解决
- 示例："为API添加缓存" - 可以使用Redis、内存、基于文件等
- 示例："提高性能" - 许多优化策略可能
3. **代码修改**：影响现有行为或结构的更改
- 示例："更新登录流程" - 到底应该改变什么？
- 示例："重构此组件" - 目标架构是什么？
4. **架构决策**：任务需要选择模式或技术
- 示例："添加实时更新" - WebSockets vs SSE vs 轮询
- 示例："实现状态管理" - Redux vs Context vs 自定义解决方案
5. **多文件更改**：任务可能会涉及超过2-3个文件
- 示例："重构身份验证系统"
- 示例："添加一个新的API端点并包含测试"
6. **要求不明确**：在了解完整范围之前需要探索
- 示例："使应用程序更快" - 需要分析和识别瓶颈
- 示例："修复结账中的错误" - 需要调查根本原因
7. **用户偏好很重要**：实施可能合理地有多种方式
- 如果你会使用AskUserQuestion来澄清方法，请改用EnterPlanMode
- 计划模式允许你先探索，然后提供带有上下文的选项
## 何时不使用此工具
仅对于简单任务跳过EnterPlanMode：
- 单行或几行修复（拼写错误、明显错误、小调整）
- 添加具有明确要求的单个函数
- 用户提供非常具体、详细指令的任务
- 纯研究/探索任务（改用带有explore代理的Task工具）
## 计划模式中发生的事情
在计划模式中，你将：
1. 使用Glob、Grep和Read工具彻底探索代码库
2. 了解现有模式和架构
3. 设计实施方法
4. 向用户展示你的计划以供批准
5. 如果你需要澄清方法，使用AskUserQuestion
6. 准备实施时使用ExitPlanMode退出计划模式
## 示例
### 好的 - 使用EnterPlanMode：
User: "向应用程序添加用户身份验证"
- 需要架构决策（会话vs JWT、令牌存储位置、中间件结构）
User: "优化数据库查询"
- 多种方法可能，需要先分析，影响重大
User: "实现深色模式"
- 主题系统的架构决策，影响许多组件
User: "向用户配置文件添加删除按钮"
- 看起来简单但涉及：放置位置、确认对话框、API调用、错误处理、状态更新
User: "更新API中的错误处理"
- 影响多个文件，用户应该批准该方法
### 坏的 - 不要使用EnterPlanMode：
User: "修复README中的拼写错误"
- 直接，无需计划
User: "添加一个console.log来调试此函数"
- 简单，明显的实施
User: "哪些文件处理路由？"
- 研究任务，不是实施计划
## 重要说明
- 此工具需要用户批准，他们必须同意进入计划模式
- 如果不确定是否使用它，倾向于计划，最好预先达成一致而不是重做工作
- 用户赞赏在对代码库进行重大更改之前进行协商
【浅析】EnterPlanMode 用于在开始非平凡任务前进入计划模式。先获得用户对方案的批准，避免浪费精力。
什么时候用：
-
• 新功能实现
-
• 多种有效方法
-
• 影响现有行为的代码修改
-
• 架构决策
-
• 改超过 2-3 个文件
-
• 要求不明确
-
• 用户偏好很重要
什么时候不用：
-
• 单行或几行修复
-
• 添加单个函数（要求明确）
-
• 用户已给出详细指令
-
• 纯研究/探索任务（用 Task + Explore 代理）
计划模式里会用 Glob/Grep/Read 探索代码库，设计方案，向用户展示计划，然后用 ExitPlanMode 退出。
示例给得很详细，什么时候该用什么时候不该用都列清楚了。
如果不确定该不该用，倾向于用。预先达成一致比返工好。
总结
整理完这 18 个工具提示词，有几个观察：
1. 工具职责划分清晰
Bash 只干终端的事，文件操作用 Read/Write/Edit，搜索用 Glob/Grep。每个工具干一件事，干好一件事。这比搞一个万能工具然后靠参数区分要清晰得多。
2. 防止模型「偷懒」的措辞
很多地方反复强调「必须」「永远不要」「立即」。比如 Skill 工具写了「BLOCKING REQUIREMENT」「IMMEDIATELY」，就是怕模型只是嘴上说说但不实际调用工具。这种强硬措辞是实践中总结出来的。
3. 工具之间有层次
简单任务用简单工具（Glob/Grep/Read），复杂任务用 Task 启动专门的代理。工具描述里经常写「When NOT to use」，告诉模型什么时候别用这个工具、该用哪个工具。
4. 安全规则写得很细
Bash 里的 Git 安全协议、Write/Edit 的「先 Read 再改」要求、各种参数的限制。这些规则肯定是踩过坑的。
5. 并行执行反复强调
几乎每个搜索类工具都写了「推测性地并行执行多个搜索总是更好的」。Task 工具也强调「尽可能在单个消息中启动多个代理」。性能优化意识很强。
6. 示例给得很充分
特别是 TodoWrite、EnterPlanMode 这些复杂工具，正例反例都给了，什么时候用什么时候不用写得很清楚。
这些提示词可以作为自建 agent 的参考。不一定要照抄，但思路可以借鉴：怎么描述工具职责、怎么写使用限制、怎么给例子、怎么防止模型走偏。
最后
从0到1！大模型(LLM)最全学习路线图，建议收藏！
想入门大模型(LLM)却不知道从哪开始? 我根据最新的技术栈和我自己的经历&理解，帮大家整理了一份LLM学习路线图，涵盖从理论基础到落地应用的全流程!拒绝焦虑，按图索骥~~
因篇幅有限，仅展示部分资料，需要点击下方链接即可前往获取