┌─────────────────────────────────────┐
│ 1. YAML Frontmatter (Metadata)      │ ← 配置
│    ---                              │
│    name: skill-name                 │
│    description: Brief overview      │
│    allowed-tools: "Bash, Read"      │
│    version: 1.0.0                   │
│    ---                              │
├─────────────────────────────────────┤
│ 2. Markdown Content (Instructions)  │ ← Claude 的提示词
│                                     │
│    Purpose explanation              │
│    Detailed instructions            │
│    Examples and guidelines          │
│    Step-by-step procedures          │
└─────────────────────────────────────┘

---
name: skill-creator
description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
license: Complete terms in LICENSE.txt
---

function formatSkill(skill) {
  let description = skill.whenToUse
    ? `${skill.description} - ${skill.whenToUse}`
    : skill.description;

  return `"${skill.name}": ${description}`;
}

"skill-creator": Create well-structured, reusable skills... - When user wants to build a custom skill package with scripts, references, or assets

# ✅ skill-creator 允许多个工具
allowed-tools: "Read,Write,Bash,Glob,Grep,Edit"

# ✅ 仅特定 git 命令
allowed-tools: "Bash(git status:*),Bash(git diff:*),Bash(git log:*),Read,Grep"

# ✅ 仅文件操作
allowed-tools: "Read,Write,Edit,Glob,Grep"

# ❌ 不必要的表面积
allowed-tools: "Bash,Read,Write,Edit,Glob,Grep,WebSearch,Task,Agent"

# ❌ 具有所有 npm 命令的不必要表面积
allowed-tools: "Bash(npm:*),Read,Write"

model: "claude-opus-4-20250514"  # 使用特定模型
model: "inherit"                 # 使用会话的当前模型（默认）

---
# Frontmatter 在此处
---

# [简短目的陈述 - 1-2 句]

## 概述
[此 skill 的功能、何时使用、提供什么]

## 先决条件
[所需工具、文件或上下文]

## 指令

### 步骤 1：[第一个操作]
[命令式指令]
[如需要，提供示例]

### 步骤 2：[下一个操作]
[命令式指令]

### 步骤 3：[最后操作]
[命令式指令]

## 输出格式
[如何构建结果]

## 错误处理
[失败时该做什么]

## 示例
[具体使用示例]

## 资源
[如果捆绑，引用 scripts/、references/、assets/]

## Skill 创建过程

### 步骤 1：通过具体示例理解 Skill
### 步骤 2：规划可重用的 Skill 内容
### 步骤 3：初始化 Skill
### 步骤 4：编辑 Skill
### 步骤 5：打包 Skill

❌ Read /home/user/project/config.json
✅ Read {baseDir}/config.json

my-skill/
├── SKILL.md              # 核心提示词和指令
├── scripts/              # 可执行的 Python/Bash 脚本
├── references/           # 加载到上下文中的文档
└── assets/               # 模板和二进制文件

从头开始创建新 skill 时，始终运行 `init_skill.py` 脚本。该脚本可以方便地生成一个新的模板 skill 目录，自动包含 skill 所需的所有内容，使 skill 创建过程更加高效可靠。

用法：

```scripts/init_skill.py <skill-name> --path <output-directory>```

脚本：
  - 在指定路径创建 skill 目录
  - 生成带有适当 frontmatter 和 TODO 占位符的 SKILL.md 模板
  - 创建示例资源目录：scripts/、references/ 和 assets/
  - 在每个目录中添加可自定义或删除的示例文件

#### 1.4 学习框架文档

**加载并阅读以下参考文件：**

- **MCP 最佳实践：** [📋 查看最佳实践](./reference/mcp_best_practices.md) - 所有 MCP 服务器的核心指南

**对于 Python 实现，还要加载：**
- **Python SDK 文档：** 使用 WebFetch 加载 `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
- [🐍 Python 实现指南](./reference/python_mcp_server.md) - Python 特定的最佳实践和示例

**对于 Node/TypeScript 实现，还要加载：**
- **TypeScript SDK 文档：** 使用 WebFetch 加载 `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
- [⚡ TypeScript 实现指南](./reference/node_mcp_server.md) - Node/TypeScript 特定的最佳实践和示例

使用 {baseDir}/assets/report-template.html 的模板作为报告结构。
引用 {baseDir}/assets/diagram.png 的架构图。

在目标目录上运行 scripts/analyzer.py：

`python {baseDir}/scripts/analyzer.py --path "$USER_PATH" --output report.json`

解析生成的 `report.json` 并呈现发现。

allowed-tools: "Bash(python {baseDir}/scripts/*:*), Read, Write"

## 处理工作流
1. 使用 Read 工具读取输入文件
2. 根据格式解析内容
3. 按照规范转换数据
4. 使用 Write 工具写入输出
5. 报告完成并提供摘要

allowed-tools: "Read, Write"

## 分析过程
1. 使用 Grep 查找相关代码模式
2. 读取每个匹配的文件
3. 分析漏洞
4. 生成结构化报告

allowed-tools: "Grep, Read"

执行分析管道：
npm install && npm run lint && npm test

报告每个阶段的结果。

allowed-tools: "Bash(npm install:*), Bash(npm run:*), Read"

## 工作流

### 步骤 1：初始设置
1. 询问用户项目类型
2. 验证先决条件是否存在
3. 创建基本配置
在继续之前等待用户确认。

### 步骤 2：配置
1. 呈现配置选项
2. 要求用户选择设置
3. 生成配置文件
在继续之前等待用户确认。

### 步骤 3：初始化
1. 运行初始化脚本
2. 验证设置成功
3. 报告结果

## 生成过程
1. 从 {baseDir}/assets/template.html 读取模板
2. 解析用户需求
3. 填充模板占位符：
   -  → 用户提供的名称
   -  → 生成的摘要
   -  → 当前日期
4. 将填充的模板写入输出文件
5. 报告完成

## 迭代分析

### 第 1 遍：广泛扫描
1. 搜索整个代码库以查找模式
2. 识别高级问题
3. 对发现进行分类

### 第 2 遍：深度分析
对于每个高级问题：
1. 读取完整的文件上下文
2. 分析根本原因
3. 确定严重性

### 第 3 遍：建议
对于每个发现：
1. 研究最佳实践
2. 生成特定修复
3. 估计工作量

呈现包含所有发现和建议的最终报告。

## 上下文收集
1. 读取项目 README.md 以获取概述
2. 分析 package.json 以获取依赖关系
3. Grep 代码库以查找特定模式
4. 检查 git 历史记录以获取最近的更改
5. 将发现综合成连贯的摘要

Pd = {
  name: "Skill",  // 工具名称常量：$N = "Skill"

  inputSchema: {
    command: string  // 例如，"pdf"、"skill-creator"
  },

  outputSchema: {
    success: boolean,
    commandName: string
  },

  // 🔑 关键字段：这生成 skills 列表
  prompt: async () => fN2(),

  // 验证和执行
  validateInput: async (input, context) => { /* 5 个错误代码 */ },
  checkPermissions: async (input, context) => { /* allow/deny/ask */ },
  call: async *(input, context) => { /* yields messages + context modifier */ }
}

async function fN2() {
  let A = await atA(),
    {
      modeCommands: B,
      limitedRegularCommands: Q
    } = vN2(A),
    G = [...B, ...Q].map((W) => W.userFacingName()).join(", ");
  l(`Skills and commands included in Skill tool: ${G}`);
  let Z = A.length - B.length,
    Y = nS6(B),
    J = aS6(Q, Z);
  return `Execute a skill within the main conversation

<skills_instructions>
When 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.

How to use skills:
- Invoke skills using this tool with the skill name only (no arguments)
- When you invoke a skill, you will see <command-message>The "{name}" skill is loading</command-message>
- The skill's prompt will expand and provide detailed instructions on how to complete the task
- Examples:
  - \`command: "pdf"\` - invoke the pdf skill
  - \`command: "xlsx"\` - invoke the xlsx skill
  - \`command: "ms-office-suite:pdf"\` - invoke using fully qualified name

Important:
- Only use skills listed in <available_skills> below
- Do not invoke a skill that is already running
- Do not use this tool for built-in CLI commands (like /help, /clear, etc.)
</skills_instructions>

<available_skills>
${Y}${J}
</available_skills>
`;
}

{
  "model": "claude-sonnet-4-5-20250929",
  "system": "You are Claude Code, Anthropic's official CLI...",  // ← 系统提示词
  "messages": [
    {"role": "user", "content": "Help me create a new skill"},
    // ... 对话历史
  ],
  "tools": [  // ← 发送给 Claude 的工具数组
    {
      "name": "Skill",  // ← 元工具
      "description": "Execute a skill...\n\n<skills_instructions>...\n\n<available_skills>\n...",
      "input_schema": {
        "type": "object",
        "properties": {
          "command": {
            "type": "string",
            "description": "The skill name (no arguments)"  // ← 单个 skill 的名称
          }
        }
      }
    },
    {
      "name": "Bash",
      "description": "Execute bash commands...",
      // ...
    },
    {
      "name": "Read",
      // ...
    }
    // ... 其他工具
  ]
}

let metadata = [
  `<command-message>${statusMessage}</command-message>`,
  `<command-name>${skillName}</command-name>`,
  args ? `<command-args>${args}</command-args>` : null
].filter(Boolean).join('\n');

// 消息 1：无 isMeta 标志 → 默认为 false → 可见
messages.push({
  content: metadata,
  autocheckpoint: checkpointFlag
});

<command-message>The "pdf" skill is loading</command-message>
<command-name>pdf</command-name>
<command-args>report.pdf</command-args>

let skillPrompt = await skill.getPromptForCommand(args, context);

// 如果需要，使用前置/附加内容进行扩充
let fullPrompt = prependContent.length > 0 || appendContent.length > 0
  ? [...prependContent, ...appendContent, ...skillPrompt]
  : skillPrompt;

// 消息 2：明确的 isMeta: true → 隐藏
messages.push({
  content: fullPrompt,
  isMeta: true  // 从 UI 隐藏，发送到 API
});

您是 PDF 处理专家。

您的任务是使用 pdftotext 工具从 PDF 文档中提取文本。

## 过程

1. 验证 PDF 文件是否存在
2. 运行 pdftotext 命令提取文本
3. 读取输出文件
4. 向用户呈现提取的文本

## 可用工具

您可以访问：
- Bash(pdftotext:*) - 用于运行 pdftotext 命令
- Read - 用于读取提取的文本
- Write - 如果需要，用于保存结果

## 输出格式

清晰格式化地呈现提取的文本。

基本目录：/path/to/skill
用户参数：report.pdf

let allMessages = [
  createMessage({ content: metadata, autocheckpoint: flag }),  // 1. 元数据
  createMessage({ content: skillPrompt, isMeta: true }),       // 2. Skill 提示词
  ...attachmentMessages,                                       // 3. 附件（条件）
  ...(allowedTools.length || skill.model ? [
    createPermissionsMessage({                                 // 4. 权限（条件）
      type: "command_permissions",
      allowedTools: allowedTools,
      model: skill.useSmallFastModel ? getFastModel() : skill.model
    })
  ] : [])
];

┌─────────────────────────────────────────────┐
│ The "pdf" skill is loading                  │
│                                             │
│ You are a PDF processing specialist.        │
│                                             │
│ Your task is to extract text from PDF       │
│ documents using the pdftotext tool.         │
│                                             │
│ ## Process                                  │
│                                             │
│ 1. Validate the PDF file exists             │
│ 2. Run pdftotext command to extract text    │
│ 3. Read the output file                     │
│ ... [500 more lines] ...                    │
└─────────────────────────────────────────────┘

async function getAllCommands() {
  // 并行从所有来源加载
  let [userCommands, skillsAndPlugins, pluginCommands, builtins] =
    await Promise.all([
      loadUserCommands(),      // ~/.claude/commands/
      loadSkills(),            // .claude/skills/ + plugins
      loadPluginCommands(),    // 插件定义的命令
      getBuiltinCommands()     // 硬编码命令
    ]);

  return [...userCommands, ...skillsAndPlugins, ...pluginCommands, ...builtins]
    .filter(cmd => cmd.isEnabled());
}

// 特定 skill 加载
async function loadPluginSkills(plugin) {
  // 检查插件是否有 skills
  if (!plugin.skillsPath) return [];

  // 支持两种模式：
  // 1. skillsPath 中的根 SKILL.md
  // 2. 带有 SKILL.md 的子目录

  const skillFiles = findSkillMdFiles(plugin.skillsPath);
  const skills = [];

  for (const file of skillFiles) {
    const content = readFile(file);
    const { frontmatter, markdown } = parseFrontmatter(content);

    skills.push({
      type: "prompt",
      name: `${plugin.name}:${getSkillName(file)}`,
      description: `${frontmatter.description} (plugin:${plugin.name})`,
      whenToUse: frontmatter.when_to_use,  // ← 注意：下划线！
      allowedTools: parseTools(frontmatter['allowed-tools']),
      model: frontmatter.model === "inherit" ? undefined : frontmatter.model,
      isSkill: true,
      promptContent: markdown,
      // ... 其他字段
    });
  }

  return skills;
}

{
  type: "prompt",
  name: "pdf",
  description: "Extract text from PDF documents (plugin:document-tools)",
  whenToUse: "When user wants to extract or process text from PDF files",
  allowedTools: ["Bash(pdftotext:*)", "Read", "Write"],
  model: undefined,  // 使用会话模型
  isSkill: true,
  disableModelInvocation: false,
  promptContent: "You are a PDF processing specialist...",
  // ... 其他字段
}

async function getSkillsForSkillTool() {
  const allCommands = await getAllCommands();

  return allCommands.filter(cmd =>
    cmd.type === "prompt" &&
    cmd.isSkill === true &&
    !cmd.disableModelInvocation &&
    (cmd.source !== "builtin" || cmd.isModeCommand === true) &&
    (cmd.hasUserSpecifiedDescription || cmd.whenToUse)  // ← 必须有一个！
  );
}

function formatSkill(skill) {
  let name = skill.name;
  let description = skill.whenToUse
    ? `${skill.description} - ${skill.whenToUse}`
    : skill.description;

  return `"${name}": ${description}`;
}

内部推理：
- 用户想要"从 report.pdf 中提取文本"
- 这是 PDF 处理任务
- 查看可用的 skills...
- "pdf"：从 PDF 文档中提取文本 - 当用户想要从 PDF 文件中提取或处理文本时
- 这匹配！用户想要从 PDF 中提取文本
- 决策：使用 command="pdf" 调用 Skill 工具

{
  "type": "tool_use",
  "id": "toolu_123abc",
  "name": "Skill",
  "input": {
    "command": "pdf"
  }
}

async validateInput({ command }, context) {
  let skillName = command.trim().replace(/^\//, "");

  // 错误 1：空
  if (!skillName) return { result: false, errorCode: 1 };

  // 错误 2：未知 skill
  const allSkills = await getAllCommands();
  if (!skillExists(skillName, allSkills)) {
    return { result: false, errorCode: 2 };
  }

  // 错误 3：无法加载
  const skill = getSkill(skillName, allSkills);
  if (!skill) return { result: false, errorCode: 3 };

  // 错误 4：禁用模型调用
  if (skill.disableModelInvocation) {
    return { result: false, errorCode: 4 };
  }

  // 错误 5：不是基于提示词的
  if (skill.type !== "prompt") {
    return { result: false, errorCode: 5 };
  }

  return { result: true };
}

async checkPermissions({ command }, context) {
  const skillName = command.trim().replace(/^\//, "");
  const permContext = (await context.getAppState()).toolPermissionContext;

  // 检查拒绝规则
  for (const [pattern, rule] of getDenyRules(permContext)) {
    if (matches(skillName, pattern)) {
      return { behavior: "deny", message: "Blocked by permission rules" };
    }
  }

  // 检查允许规则
  for (const [pattern, rule] of getAllowRules(permContext)) {
    if (matches(skillName, pattern)) {
      return { behavior: "allow" };
    }
  }

  // 默认：询问用户
  return { behavior: "ask", message: `Execute skill: ${skillName}` };
}

async *call({ command }, context) {
  const skillName = command.trim().replace(/^\//, "");
  const allSkills = await getAllCommands();
  const skill = getSkill(skillName, allSkills);

  // 加载 skill 提示词
  const promptContent = await skill.getPromptForCommand("", context);

  // 生成元数据标签
  const metadata = [
    `<command-message>The "${skill.userFacingName()}" skill is loading</command-message>`,
    `<command-name>${skill.userFacingName()}</command-name>`
  ].join('\n');

  // 创建消息
  const messages = [
    { type: "user", content: metadata },  // 用户可见
    { type: "user", content: promptContent, isMeta: true },  // 对用户隐藏，对 Claude 可见
    // ... 附件、权限
  ];

  // 提取配置
  const allowedTools = skill.allowedTools || [];
  const modelOverride = skill.model;

  // 使用执行上下文修改器产生结果
  yield {
    type: "result",
    data: { success: true, commandName: skillName },
    newMessages: messages,

    // 🔑 执行上下文修改函数
    contextModifier(context) {
      let modified = context;

      // 注入允许的工具
      if (allowedTools.length > 0) {
        modified = {
          ...modified,
          async getAppState() {
            const state = await context.getAppState();
            return {
              ...state,
              toolPermissionContext: {
                ...state.toolPermissionContext,
                alwaysAllowRules: {
                  ...state.toolPermissionContext.alwaysAllowRules,
                  command: [
                    ...state.toolPermissionContext.alwaysAllowRules.command || [],
                    ...allowedTools  // ← 预先批准这些工具
                  ]
                }
              }
            };
          }
        };
      }

      // 覆盖模型
      if (modelOverride) {
        modified = {
          ...modified,
          options: {
            ...modified.options,
            mainLoopModel: modelOverride
          }
        };
      }

      return modified;
    }
  };
}

// 为第 1 轮发送到 API 的完整消息数组
{
  model: "claude-sonnet-4-5-20250929",
  messages: [
    {
      role: "user",
      content: "Extract text from report.pdf"
    },
    {
      role: "assistant",
      content: [
        {
          type: "tool_use",
          id: "toolu_123abc",
          name: "Skill",
          input: { command: "pdf" }
        }
      ]
    },
    {
      role: "user",
      content: "<command-message>The \"pdf\" skill is loading</command-message>\n<command-name>pdf</command-name>"
      // isMeta: false（默认）- 对 UI 中的用户可见
    },
    {
      role: "user",
      content: "You are a PDF processing specialist...\n\n## Process\n1. Validate PDF exists\n2. Run pdftotext...",
      isMeta: true  // 从 UI 隐藏，发送到 API
    },
    {
      role: "user",
      content: {
        type: "command_permissions",
        allowedTools: ["Bash(pdftotext:*)", "Read", "Write"],
        model: undefined
      }
    }
  ]
}

我将从 report.pdf 中提取文本。让我处理文件。

[遵循 pdf skill 的指令]
1. 验证 report.pdf 是否存在
2. 运行 pdftotext 命令提取文本
3. 读取输出文件
4. 向您呈现提取的文本

{
  "type": "tool_use",
  "id": "toolu_456def",
  "name": "Bash",
  "input": {
    "command": "pdftotext report.pdf output.txt",
    "description": "Extract text from PDF using pdftotext"
  }
}