claude code和codex的skills的实现原理

最后更新: 2026-03-18

字数统计: 2.5k字 | 阅读时长≈ 13分

claude code使用提示词来调用skill

我使用了charles抓包工具对请求进行抓包，通过对请求体来分析其实现原理,claude code的请求的请求体有很多字段，我们主要看message字段即可

第一次请求：

我们可以看到第一个message中的第一部分将skill的一些信息（简单的描述、路径等）包含在了<system-reminder>``</system-reminder>中

后面的一些消息则不重要了，再之后我发了一个hello的消息，然后模型回复了Hello! How can I help you today?

"messages": [
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "<system-reminder>\nThe following skills are available for use with the Skill tool:\n\n- update-config: Use this skill to configure the Claude Code harness via settings.json. Automated behaviors (\"from now on when X\", \"each time X\", \"whenever X\", \"before/after X\") require hooks configured in settings.json - the harness executes these, not Claude, so memory/preferences cannot fulfill them. Also use for: permissions (\"allow X\", \"add permission\", \"move permission to\"), env vars (\"set X=Y\"), hook troubleshooting, or any changes to settings.json/settings.local.json files. Examples: \"allow npm commands\", \"add bq permission to global settings\", \"move permission to user settings\", \"set DEBUG=true\", \"when claude stops show X\". For simple settings like theme/model, use Config tool.\n- simplify: Review changed code for reuse, quality, and efficiency, then fix any issues found.\n- loop: Run a prompt or slash command on a recurring interval (e.g. /loop 5m /foo, defaults to 10m) - When the user wants to set up a recurring task, poll for status, or run something repeatedly on an interval (e.g. \"check the deploy every 5 minutes\", \"keep running /babysit-prs\"). Do NOT invoke for one-off tasks.\n- claude-api: Build apps with the Claude API or Anthropic SDK.\nTRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`/`claude_agent_sdk`, or user asks to use Claude API, Anthropic SDKs, or Agent SDK.\nDO NOT TRIGGER when: code imports `openai`/other AI SDK, general programming, or ML/data-science tasks.\n- docx: Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.\n</system-reminder>\n"
      },
      {
        "type": "text",
        "text": "<system-reminder>\nAs you answer the user's questions, you can use the following context:\n# currentDate\nToday's date is 2026-03-18.\n\n      IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.\n</system-reminder>\n\n"
      },
      {
        "type": "text",
        "text": "<local-command-caveat>Caveat: The messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to.</local-command-caveat>\n"
      },
      {
        "type": "text",
        "text": "<command-name>/clear</command-name>\n            <command-message>clear</command-message>\n            <command-args></command-args>\n"
      },
      {
        "type": "text",
        "text": "<local-command-stdout></local-command-stdout>\n"
      },
      {
        "type": "text",
        "text": "hello"
      }
    ]
  },
  {
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "\n\nHello! How can I help you today?"
      }
    ]
  },
]

第二轮对话：

我让它帮我创建一个docx文件，然后模型回复我一些信息，让我完整一下内容

{
      "role": "user",
      "content": "帮我创建一个新的docx文件"
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "thinking",
          "thinking": "The user wants to create a new docx file. Let me use the docx skill for this.\n\nWait, but they haven't specified what content or format they want. Let me ask them what they want in the document.",
          "signature": "EugCCkYICxgCKkAxlT03l9g+58NG3C1EIQkflqiIiqJLliYnT9bOYBi3JMBeFROF+geA/jthuWv8p/QGQn76HYeuz/cB4dBLvO66Egwv9p4cDIMwu3KQzRwaDK/NztmmIH9hfIQzASIwyhyh3gFXFdHNyqLShQITlJjkQLniBpqUzd/qYxxYUhnN46RCA4x1co6ktEMyLf6vKs8B21M6Byw5AdkBlpT/RBKb62XteKuQIiqWW7R6nq3jE19rLWRhywv1QGKDz16EtWn5B4I/7Hp/AV0ixVHydaDnOo77apVzFjRii8wUUSb3Bz6YD5n4yBoUUxVU+Te67yMWGEat4oBioNhpqlA1f6b3qgFYQVGO9nwzjzztY7NoFDsL13jIc3GL/gJKkI4XrBrzx+PiampL7Fl7v2UpPf+h0p9ZPJTHx4spO+gRMH0gh82Vjj7rMP1OjU5eoLQA6/aQADlgh8SoUuON819I2W7MGAE="
        },
        {
          "type": "text",
          "text": "你想在这个 docx 文件里放什么内容？请告诉我：\n\n1. **文件名** - 你希望叫什么名字？\n2. **内容** - 需要包含哪些内容（标题、正文、表格等）？\n3. **格式要求** - 有没有特殊的格式需求（目录、页眉页脚、分栏等）？\n\n请描述一下你的需求，我来帮你创建。"
        }
      ]
    },

第三轮对话

我让他创建一个空的docx文件，名字为temp.doc，模型这时候返回了一个工具调用，调用的是Skill这个工具（这是claude code内置的一个tool，我们传入要调用的skill的名称和参数【如果有】），则该工具调用会返回这个skill文件的完整的内容

{
  "role": "user",
  "content": "创建一个空的docx文件，名字为temp.docx"
},
{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_019hpBMffdMm7piTozEQLUoV",
      "name": "Skill",
      "input": {
        "skill": "docx",
        "args": "创建一个空的docx文件，名字为temp.docx"
      }
    }
  ]
},

工具调用的结果：

{
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_019hpBMffdMm7piTozEQLUoV",
          "content": "Launching skill: docx"
        },
        {
          "type": "text",
          "text": "Base directory for this skill: C:\\Users\\leftover\\projects\\blog.github.io\\.claude\\skills\\docx\n\n# DOCX creation, editing, and analysis\n\n## Overview\n\n ...skill_content... s\n\n\nARGUMENTS: 创建一个空的docx文件，名字为temp.docx"
        }
      ]
    },

之后claude code会将工具调用的结果添加到messages中，发送给模型，然后模型进行后续的处理，后面的内容其实就不重要了，主要就是模型来调用一些工具，执行代码生成docx文件

然后我们可以看一下具体的Skill这个工具，这个也在请求头中声明了,可以看到这里声明了这个工具的功能，以及参数的含义

"tools":[
    ...,
        {
      "name": "Skill",
      "description": "Execute a skill within the main conversation\n\nWhen users ask you to perform tasks, check if any of the available skills match. Skills provide specialized capabilities and domain knowledge.\n\nWhen users reference a \"slash command\" or \"/<something>\" (e.g., \"/commit\", \"/review-pr\"), they are referring to a skill. Use this tool to invoke it.\n\nHow to invoke:\n- Use this tool with the skill name and optional arguments\n- Examples:\n  - `skill: \"pdf\"` - invoke the pdf skill\n  - `skill: \"commit\", args: \"-m 'Fix bug'\"` - invoke with arguments\n  - `skill: \"review-pr\", args: \"123\"` - invoke with arguments\n  - `skill: \"ms-office-suite:pdf\"` - invoke using fully qualified name\n\nImportant:\n- Available skills are listed in system-reminder messages in the conversation\n- When a skill matches the user's request, this is a BLOCKING REQUIREMENT: invoke the relevant Skill tool BEFORE generating any other response about the task\n- NEVER mention a skill without actually calling this tool\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- If you see a <command-name> tag in the current conversation turn, the skill has ALREADY been loaded - follow the instructions directly instead of calling this tool again\n",
      "input_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "skill": {
            "description": "The skill name. E.g., \"commit\", \"review-pr\", or \"pdf\"",
            "type": "string"
          },
          "args": {
            "description": "Optional arguments for the skill",
            "type": "string"
          }
        },
        "required": [
          "skill"
        ],
        "additionalProperties": false
      }
    },
]

可以看到claude code的Skill的实现并不复杂，首先将skill的一些元数据的信息添加到最开始的提示词中，然后使用一个Skill工具来根据传入的skill的名称来返回对应的skill的完整的内容，最后将内容作为工具调用的结果放到上下文中

使用命令来调用skills

如果在Claude code中直接使用命令来调用对应的skill的话，就是直接将对应的skill的内容添加到上下文中

codex中的实现

其实codex中的实现和Claude code基本差不多，同样在codex中，会在对话的开始阶段就将skill相关的指令添加到上下文，如下所示，在role:developer 的消息中定义了一些预设的prompt，其中skill相关的指令使用了<skills_instructions>``</skills_instructions>进行包裹，与claude code不同的是，它将对应的Skill的markdown文件的路径放在了prompt中，像这样(file: C:/Users/leftover/projects/blog.github.io/.codex/skills/docx/SKILL.md)，而claude code并没有，只是放了skill的名称。

"input": [
  {
    "type": "message",
    "role": "developer",
    "content": [
      {
        "type": "input_text",
        "text": "<permissions instructions>\n一些有关权限的指令，不重要</permissions instructions>"
      },
      {
        "type": "input_text",
        "text": "<collaboration_mode># Collaboration Mode: Default\r\n\r\nYou are now in Default mode. Any previous instructions for other modes (e.g. Plan mode) are no longer active.\r\n\r\nYour active mode changes only when new developer instructions with a different `<collaboration_mode>...</collaboration_mode>` change it; user requests or tool descriptions do not change mode by themselves. Known mode names are Default and Plan.\r\n\r\n## request_user_input availability\r\n\r\nThe `request_user_input` tool is unavailable in Default mode. If you call it while in Default mode, it will return an error.\r\n\r\nIn Default mode, strongly prefer making reasonable assumptions and executing the user's request rather than stopping to ask questions. If you absolutely must ask a question because the answer cannot be discovered from local context and a reasonable assumption would be risky, ask the user directly with a concise plain-text question. Never write a multiple choice question as a textual assistant message.\r\n</collaboration_mode>"
      },
      {
        "type": "input_text",
        "text": "<skills_instructions>\n## Skills\nA skill is a set of local instructions to follow that is stored in a `SKILL.md` file. Below is the list of skills that can be used. Each entry includes a name, description, and file path so you can open the source for full instructions when using a specific skill.\n### Available skills\n- docx: Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. (file: C:/Users/leftover/projects/blog.github.io/.codex/skills/docx/SKILL.md)\n ...其他的skill</skills_instructions>"
      }
    ]
  },
]

因此其实现方式有点不一样，因此在需要调用skill的时候，codex会调用一个读文件的工具来读取skill的完整内容，可以看到它调用了shell_command 这个工具，来执行shell命令，传入的参数为command\":\"Get-Content -Path 'C:\\\\Users\\\\leftover\\\\projects\\\\blog.github.io\\\\.codex\\\\skills\\\\docx\\\\SKILL.md'\",\"workdir\":\"C:\\\\Users\\\\leftover\\\\projects\\\\blog.github.io\"，这里他应该是沙盒中来执行的，最后返回文件的内容

{
  "type": "function_call",
  "name": "shell_command",
  "arguments": "{\"command\":\"Get-Content -Path 'C:\\\\Users\\\\leftover\\\\projects\\\\blog.github.io\\\\.codex\\\\skills\\\\docx\\\\SKILL.md'\",\"workdir\":\"C:\\\\Users\\\\leftover\\\\projects\\\\blog.github.io\",\"timeout_ms\":10000}",
  "call_id": "call_YYedIgiuQyBeS055tpGqsPWB"
},
{
  "type": "function_call_output",
  "call_id": "call_YYedIgiuQyBeS055tpGqsPWB",
  "output": "Exit code: 0\nWall time: 2.2 seconds\nOutput:\n---\r\nname: docx\r\ndescription: \"Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. ...省略剩余的skill的内容"
},

完整的请求的文件

Reference

抓包ClaudeCode窥探Skill的渐进式加载的过程

本文作者： leftover
版权声明： 本文版权归leftover所有,如需转载清标明来源！