在 Claude Code 的生态系统中，自定义 skill 是扩展 Agent 能力边界的核心机制。不同于传统的插件系统，Claude Code 的 skill 采用了更轻量化的设计理念，通过声明式的元数据和结构化的指令文件，让开发者能够以极低的摩擦成本为 AI 助手注入领域特定能力。本文以 GitHub 项目 destiny 为例 —— 一款由开发者 xodn348 构建的每日运势占卜插件 —— 系统性地剖析自定义 skill 的工程化实现路径。
Claude Code Skill 的核心架构
Claude Code 的 skill 系统建立在两个关键概念之上：技能目录结构与 SKILL.md 元数据声明。每个 skill 本质上是一个独立的文件夹，放置在 ~/.claude/skills/ 目录下，其核心包含一个 SKILL.md 文件。这个文件采用 YAML 前置元数据（frontmatter）加 Markdown 正文的混合格式，前者定义 skill 的名称、触发条件和行为参数，后者则描述 AI 在激活该 skill 时应遵循的指令集。
从架构设计角度看，这种模式借鉴了现代 CLI 工具的配置即代码理念。SKILL.md 中的 frontmatter 负责「何时触发」的判断逻辑 —— 当用户的输入匹配特定关键词、文件类型或项目上下文时，Claude Code 会自动加载对应的 skill 并将其指令注入到系统提示中。这种隐式激活机制避免了显式的命令调用，使得 skill 能够在用户无感知的情况下增强 AI 的专业能力。
以 destiny 项目为参照，其 skill 定义必然包含类似 name: destiny、description: Daily fortune-telling plugin for Claude Code 的元数据，以及详细的占卜流程指令。这种设计让 Claude 在识别到用户提及「运势」「占卜」「今日运势」等意图时，无缝切换到占卜师角色。
SKILL.md 的工程化设计要素
编写高质量的 SKILL.md 需要平衡多重考量：指令的清晰度、触发条件的精准度、以及输出格式的一致性。从工程视角审视，一个完善的 skill 指令文件通常包含以下结构化区块：
前置元数据区 负责定义 skill 的身份标识与激活规则。核心字段包括 name（技能唯一标识）、description（人类可读的能力描述）、trigger（触发条件，可配置为关键词、正则表达式或文件类型匹配）。对于 destiny 这类娱乐性 skill，触发条件通常设置为一组意图明确的短语，如「今日运势」「算一卦」「 fortune 」等。
系统指令区 是 skill 的核心本体，定义了 AI 在该 skill 激活时的行为规范。这部分需要明确以下要素：角色设定（你是谁）、输入解析规则（如何理解用户需求）、输出格式规范（结构化响应模板）、以及安全边界（禁止做什么）。以占卜插件为例，指令中会明确要求 AI 使用非确定性语言、避免对真实事件做出确定性预测、以及保持娱乐而非迷信的基调。
示例与变体区 通过提供输入 - 输出对，帮助 AI 更精准地理解期望的行为模式。这在复杂场景下尤为重要 —— 单纯的文字指令可能产生歧义，但配合具体示例，AI 能够更好地掌握输出风格与内容结构。
Python 工具集成：超越纯指令的扩展
对于需要动态数据处理或外部 API 调用的 skill，单纯的指令注入方式存在局限。Claude Code 支持通过 Python 模块扩展 skill 的能力边界，这也是 destiny 项目采用的技术路径。在 ~/.claude/skills/ 目录之外，开发者可以在项目仓库中编写 Python 工具函数，通过 Claude Code 的 SDK 注册为可调用工具。
这种混合架构实现了指令定义与工具实现的分离。SKILL.md 负责「做什么」的决策逻辑，而 Python 代码负责「怎么做」的具体执行。以每日运势为例，Python 层可以负责：获取当前日期与时间、基于生日生成星座 / 生肖映射、调用随机数生成器产生塔罗牌结果、以及格式化输出结构。指令层则负责将这些工具调用串联为流畅的用户体验。
从工程实践角度看，Python 工具的注册需要遵循 Claude Code SDK 的接口规范。开发者需要在代码中定义工具函数，标注其参数类型与返回值结构，并通过 SDK 的注册接口将工具暴露给 AI。AI 在执行 skill 指令时，会根据上下文判断是否需要调用工具，并在工具返回结果后继续完成指令流程。
Agent 扩展开发范式的思考
destiny 项目的存在揭示了 Claude Code 生态的一个核心趋势：AI 助手正在从通用工具向可定制化平台演进。自定义 skill 机制的本质，是允许开发者以「prompt as configuration」的方式重新定义 AI 的行为边界，而无需深入修改底层模型或基础设施。
这种范式的工程价值在于其低门槛与高灵活性。相比于传统 Agent 框架需要编写的复杂编排代码，Claude Code skill 只需一个 Markdown 文件即可完成定义。同时，由于 skill 指令最终会被注入到系统提示中，开发者无需担心工具调用失败导致的流程中断 ——AI 能够以自然语言的方式处理各种边缘情况。
对于希望构建领域专属 AI 助手的开发者，建议从以下路径入手：首先，明确 skill 的核心价值与触发场景，确保其解决的是高频、明确的需求；其次，在 SKILL.md 中精细化定义输入解析与输出格式规则，利用示例消除歧义；最后，对于需要动态能力的场景，通过 Python 工具层补充处理逻辑。这种分层架构既保持了 skill 的简洁性，又赋予了足够的扩展空间。
destiny 项目的成功（累计 28 颗 GitHub 星标）表明，娱乐性、场景化的 skill 有着真实的市场需求。随着 Claude Code 生态的持续成熟，更多垂直领域的自定义 skill 将不断涌现，为 AI 助手的个性化发展提供丰富的实践经验。
资料来源：本文关于 Claude Code skill 架构的概述参考了 Claude 官方文档与社区实践，destiny 项目信息来源于 GitHub 仓库 xodn348/destiny。