Claude Code 插件与 Skill 系统深度分析

// 注册中心 — 一个简单的 Map<string, BuiltinPluginDefinition>
const BUILTIN_PLUGINS: Map<string, BuiltinPluginDefinition> = new Map()

// 注册入口
export function registerBuiltinPlugin(
  definition: BuiltinPluginDefinition,
): void {
  BUILTIN_PLUGINS.set(definition.name, definition)
}

export type BuiltinPluginDefinition = {
  name: string
  description: string
  version?: string
  skills?: BundledSkillDefinition[]     // 提供的技能
  hooks?: HooksSettings                 // 提供的钩子
  mcpServers?: Record<string, McpServerConfig>  // 提供的 MCP 服务
  isAvailable?: () => boolean           // 可用性检查
  defaultEnabled?: boolean              // 默认开启状态
}

// 优先级：用户设置 > 插件默认值 > true
const isEnabled =
  userSetting !== undefined
    ? userSetting === true
    : (definition.defaultEnabled ?? true)

export type BundledSkillDefinition = {
  name: string
  description: string
  aliases?: string[]
  whenToUse?: string                    // 模型自动触发指南
  argumentHint?: string
  allowedTools?: string[]               // 白名单工具
  model?: string                        // 模型覆写
  disableModelInvocation?: boolean      // 仅用户可调用
  userInvocable?: boolean
  isEnabled?: () => boolean
  hooks?: HooksSettings
  context?: 'inline' | 'fork'           // 执行上下文
  agent?: string
  files?: Record<string, string>        // 附带的参考文件
  getPromptForCommand: (args, context) => Promise<ContentBlockParam[]>
}

// 1. 定义 Skill → registerBundledSkill()
// 2. 转换为 Command 对象，推入 bundledSkills[] 数组
// 3. CLI 启动时 initBundledSkills() 批量注册

// 文件操作触发 → 沿路径向上查找 .claude/skills/ → 加载 → 通知监听者
export async function discoverSkillDirsForPaths(filePaths, cwd)
export async function addSkillDirectories(dirs)

export function activateConditionalSkillsForPaths(filePaths, cwd)

z.object({
  skill: z.string(),           // Skill 名称
  args: z.string().optional(), // 可选参数
})

async function executeForkedSkill(command, commandName, args, context, ...) {
  const agentId = createAgentId()
  const { modifiedGetAppState, baseAgent, promptMessages, skillContent } =
    await prepareForkedCommandContext(command, args, context)

  for await (const message of runAgent({
    agentDefinition,
    promptMessages,
    toolUseContext: { ...context, getAppState: modifiedGetAppState },
    ...
  })) {
    agentMessages.push(message)
    // 进度上报...
  }
}

registerBundledSkill({
  name: 'debug',
  description: 'Enable debug logging for this session and help diagnose issues',
  allowedTools: ['Read', 'Grep', 'Glob'],
  disableModelInvocation: true,  // 仅用户可调用
  async getPromptForCommand(args) {
    enableDebugLogging()
    const tail = await tailDebugLog(debugLogPath, 20)
    // 生成包含日志末尾、错误分析指令的 prompt
    return [{ type: 'text', text: `# Debug Skill\n...${tail}...` }]
  },
})

registerBundledSkill({
  name: 'remember',
  description: 'Review auto-memory entries and propose promotions...',
  isEnabled: () => isAutoMemoryEnabled(),  // 条件启用
  async getPromptForCommand(args) {
    return [{ type: 'text', text: SKILL_PROMPT }]  // 静态 prompt
  },
})

registerBundledSkill({
  name: 'skillify',
  description: "Capture this session's repeatable process into a skill",
  allowedTools: ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'AskUserQuestion', 'Bash(mkdir:*)'],
  disableModelInvocation: true,
  async getPromptForCommand(args, context) {
    const sessionMemory = await getSessionMemoryContent()
    const userMessages = extractUserMessages(context.messages)
    // 模板替换：注入会话记忆和用户消息
    const prompt = SKILLIFY_PROMPT
      .replace('{{sessionMemory}}', sessionMemory)
      .replace('{{userMessages}}', userMessages.join('\n\n---\n\n'))
    return [{ type: 'text', text: prompt }]
  },
})

registerBundledSkill({
  name: 'verify',
  description: DESCRIPTION,
  files: SKILL_FILES,  // 附带参考文件
  async getPromptForCommand(args) {
    return [{ type: 'text', text: SKILL_BODY }]
  },
})

// mcpSkillBuilders.ts — 叶子模块，只导入类型
export type MCPSkillBuilders = {
  createSkillCommand: typeof createSkillCommand
  parseSkillFrontmatterFields: typeof parseSkillFrontmatterFields
}
let builders: MCPSkillBuilders | null = null

export function registerMCPSkillBuilders(b: MCPSkillBuilders): void { builders = b }
export function getMCPSkillBuilders(): MCPSkillBuilders { ... }

registerMCPSkillBuilders({
  createSkillCommand,
  parseSkillFrontmatterFields,
})

async function getAllCommands(context: ToolUseContext): Promise<Command[]> {
  const mcpSkills = context
    .getAppState()
    .mcp.commands.filter(
      cmd => cmd.type === 'prompt' && cmd.loadedFrom === 'mcp',
    )
  if (mcpSkills.length === 0) return getCommands(getProjectRoot())
  const localCommands = await getCommands(getProjectRoot())
  return uniqBy([...localCommands, ...mcpSkills], 'name')
}

// Security: MCP skills are remote and untrusted
if (loadedFrom !== 'mcp') {
  finalContent = await executeShellCommandsInPrompt(finalContent, ...)
}