企业官网建设流程全解析

• 人工智能
• AI 应用
• 桌面应用
• 代码智能体
• MCP Clients

导读

Skills 是 Claude Code 体系内的"扩展能力引擎"，它让开发者可以用纯 Markdown 文件（含 YAML frontmatter）为 Agent 定义可复用的专业化工作流——代码审查、TDD、调试、批量处理等标准流程都能固化成一条斜杠命令。本文以 cc-haha 仓库 docs/internals/skills.md 为主线，完整覆盖 Skill 的六种来源、Frontmatter 字段全解、三种调用方式、inline/fork 两种执行上下文、条件激活机制与权限控制，并结合 src/skills/ 与 src/tools/SkillTool/ 的源码实现，讲清"一个 Skill 从磁盘文件到进入模型对话"的完整链路。读完你可以直接上手创建、配置、共享和管控自己的 Skill。

什么是 Skills？

Skills 是 Claude Code 的可扩展能力插件系统。每个 Skill 是一个目录下的 Markdown 文件（含 YAML frontmatter），它定义了一段专门的提示词和行为配置，让 Agent 在特定场景下执行专业化的工作流。与硬编码在二进制里的内建命令不同，Skill 以纯文本形式存在，谁都可以写、可以改、可以分享。

核心能力一览：

在 cc-haha 的整体架构（见 docs/internals/index.md）中，Skills 属于 CLI 内核的横切能力之一：入口层初始化后，Skills 与插件、MCP、OAuth、记忆等服务一起被主链路调用。桌面端、IM 端最终都复用同一套 CLI 内核，因此 Skills 在任意入口下行为一致。

六种 Skill 来源

Agent 从 6 个不同来源加载 Skills，按优先级从高到低依次为：Bundled（内置）、Managed（策略管理）、User（用户）、Project（项目）、Plugin（插件）、MCP（MCP 服务器）。优先级决定同名冲突时的解析结果，理解这一点对排查"为什么我写的 Skill 没生效"至关重要。

1. Bundled（内置 Skills）

编译到 CLI 二进制中，所有用户可用。以 TypeScript 定义，通过registerBundledSkill()注册（见 src/skills/bundledSkills.ts）。从 src/skills/bundled/index.ts 的initBundledSkills()可以看到，内置 Skills 在 CLI 启动时同步注册，部分还受特性门控（feature flag）约束。

当前内置 Skills：

仓库中 src/skills/bundled/ 目录给出了这些内置 Skill 的实体实现：例如verify.ts、debug.ts、simplify.ts、remember.ts、skillify.ts、dream.ts、loop.ts、claudeApi.ts等，其中claude-api、verify、imagegen还携带了配套的 SKILL.md 与文档目录。

2. Managed（策略管理 Skills）

由组织策略控制，存放在<managed-path>/.claude/skills/，适用于企业部署。加载路径来自getManagedFilePath()（见 src/skills/loadSkillsDir.ts 中getSkillsPath()对policySettings的处理），这类 Skill 的权限由组织统一下发，用户不能随意修改。

3. User（用户 Skills）

用户个人定义，存放在~/.claude/skills/；同时也会读取跨工具开放标准目录~/.agents/skills/。

~/.claude/skills/ ├── my-review/ │ └── SKILL.md ← 主 Skill 文件 ├── deploy-check/ │ └── SKILL.md └── ... ~/.agents/skills/ ← 开放标准目录，与 Codex / Cursor / Gemini CLI 共享 └── pdf-processing/ └── SKILL.md

从 src/skills/skillRoots.ts 的实现看，用户级根目录按.claude在前、.agents在后的顺序注册，且共享同一scopeKey: 'user'——这意味着同一层级的同名 Skill 会被视为冲突而非合法的覆盖关系，.claude中的版本优先。

4. Project（项目 Skills）

项目级别定义，存放在.claude/skills/或.agents/skills/，可提交到版本控制，随代码库分发给所有协作者。

your-project/ ├── .claude/ │ └── skills/ │ ├── lint-fix/ │ │ └── SKILL.md │ └── test-runner/ │ └── SKILL.md └── .agents/ └── skills/ ← 团队共享，其它 Agent 工具同样能发现 └── deploy-app/ └── SKILL.md

项目级根目录的扫描范围由getProjectSkillRoots()定义：从 cwd 向上遍历到 git 根目录（最终不超过 HOME），每个目录层级是独立的 scope，因此pkg/.claude/skills/foo与pkg/.agents/skills/foo冲突，而pkg/...与repo-root/...不冲突。

关于.agents/skills/（Agent Skills 开放标准）

.agents/skills/是跨客户端共享目录规范（agentskills.io）约定的目录名，OpenAI Codex、Cursor、Gemini CLI、opencode 等工具都会扫描它。放在这里的技能不必再往每个工具的私有目录里复制一份。cc-haha 的实现在 src/skills/skillRoots.ts 中由AGENT_SKILLS_DIR = '.agents'常量驱动，并配套完整的开关逻辑：

• 两种目录同时生效，SKILL.md格式完全一致，无需改写。
• 同一层级下若出现同名技能，.claude/优先，.agents/中的同名项被忽略（会记录一条 warn 日志）。不同层级（如用户级与项目级）同名仍按原有规则各自保留。
• 通过软链接共享同一份技能时会自动识别为同一个，不会重复加载——去重逻辑基于realpath()解析后的文件标识（getFileIdentity()），见 src/skills/loadSkillsDir.ts。
• 如需关闭，在settings.json中设置"disableAgentSkillsDirectory": true，或设置环境变量CLAUDE_CODE_DISABLE_AGENT_SKILLS_DIR=1。关闭后.claude/skills/不受影响。源码中isAgentSkillsDirectoryEnabled()会先检查环境变量、再读 settings，两者任一命中即关闭。
• 技能市场安装、/skillify创建等写入操作仍然写到~/.claude/skills/。

5. Plugin（插件 Skills）

由已安装的插件提供。插件通过 manifest 的skillsPath/skillsPaths声明 Skills 目录。命名格式：{pluginName}:{skillName}。

例如：superpowers:code-reviewer superpowers:brainstorming

插件 Skill 的加载流程（见 docs/internals/skills-internals.md）会读取manifest.skillsPath与manifest.skillsPaths[]，支持${CLAUDE_PLUGIN_ROOT}、${CLAUDE_PLUGIN_DATA}、${CLAUDE_SKILL_DIR}、${user_config.X}等变量替换，命名空间展开为{pluginName}:{namespace}:{skillName}。

6. MCP（MCP 服务器 Skills）

由连接的 MCP 服务器提供，命名格式：mcp__server-name__prompt-name。MCP 的 prompts 通过fetchCommandsForClient()转换为 Command 对象（见 src/services/mcp/client.ts），由feature('MCP_SKILLS')特性门控控制可用性。

安全限制：MCP Skills 为远程不受信来源，禁止执行!`... 内联 shell 命令——在getPromptForCommand中会跳过executeShellCommandsInPrompt()这一步。

Skill 定义格式

目录结构

每个 Skill 是一个目录，包含一个SKILL.md文件（文件名必须是SKILL.md，大小写不敏感）：

skill-name/ └── SKILL.md ← 文件名必须是 SKILL.md（大小写不敏感）

Frontmatter 完整字段

--- name: 我的技能 # 显示名称（可选，默认用目录名） description: 这个技能做什么 # 描述（必填，缺少时自动从内容提取） when_to_use: 什么时候该用这个技能 # 使用场景说明（可选） version: 1.0.0 # 版本号（可选） # ── 调用控制 ── user-invocable: true # 用户能否通过 /skill-name 调用（默认 true） disable-model-invocation: false # 禁止模型通过 Skill tool 调用（可选） argument-hint: "<文件路径>" # 参数提示（可选） # ── 执行配置 ── context: inline # 执行上下文：inline（默认）或 fork（子代理） agent: general-purpose # fork 时使用的代理类型（可选） model: sonnet # 模型覆盖：haiku / sonnet / opus / inherit（可选） effort: high # 思考力度：low / medium / high / max（可选） allowed-tools: "Bash, Read" # 允许使用的工具（逗号分隔或 YAML 列表） shell: bash # Shell 类型：bash（默认）或 powershell # ── 条件激活 ── paths: "src/**/*.ts, test/**/*.ts" # Glob 模式，只在匹配文件被操作时激活 # ── 生命周期 Hook ── hooks: PreToolUse: - matcher: "Bash" hooks: - command: "echo 'Before bash'" once: true # 仅执行一次 --- # Skill 正文内容 这里是 Markdown 格式的提示词，Claude 调用此 Skill 时会看到这些内容。 支持的特殊语法： - `${CLAUDE_SKILL_DIR}` — 展开为 Skill 所在目录 - `${CLAUDE_SESSION_ID}` — 展开为当前会话 ID - `$ARGUMENTS` / `${ARG1}` — 参数替换 - !`shell command` — 内联 Shell 命令执行

关于上述字段的源码佐证：parseSkillFrontmatterFields()（见 src/skills/loadSkillsDir.ts）负责把 frontmatter 解析为结构化的 Command 对象，其中description的提取优先级为：frontmatter 中的description字段 → Markdown 第一个#标题 → 技能名称兜底；model走parseUserSpecifiedModel()别名解析；effort走parseEffortValue()；Hook 配置经parseHooksFromFrontmatter()校验后按HooksSchema落库。FrontmatterData类型的完整定义可参考 src/utils/frontmatterParser.ts。

Frontmatter 字段速查表

调用方式

方式一：用户斜杠命令

直接在终端输入/skill-name：

> /commit > /review-pr 123 > /verify

前提：Skill 的user-invocable必须为true。

方式二：模型自动调用

Agent 在对话中识别到合适的 Skill 时，通过 SkillTool 自动调用：

用户：帮我审查一下这段代码 Claude：[通过 SkillTool 调用 superpowers:code-reviewer]

前提：Skill 的disable-model-invocation不能为true。模型看到的 SkillTool 提示词（src/tools/SkillTool/prompt.ts）明确要求：当某个 Skill 匹配时，先生成任何其他回复之前调用该工具；可用的 Skill 列表通过 system-reminder 消息注入；绝不提及一个 Skill 却不调用工具；不重复调用正在运行的 Skill。

方式三：嵌套调用

一个 Skill 执行过程中可以触发另一个 Skill：

/verify → 内部调用 → /simplify

遥测中通过invocation_trigger: 'nested-skill'追踪。

调用优先级

当同名 Skill 存在于多个来源时，按以下顺序解析（先匹配先用）：

1. Bundled（内置） ← 最高优先级 2. Built-in Plugin（内置插件） 3. Skill Dirs（用户/项目目录） 4. Workflow Commands 5. Plugin Commands（插件命令） 6. Plugin Skills（插件技能） 7. Built-in Commands（内建命令） ← 最低优先级

该顺序在源码loadAllCommands()（见 src/commands.ts）中得到精确印证：函数把bundledSkills → builtinPluginSkills → skillDirCommands → workflowCommands → pluginCommands → pluginSkills → COMMANDS()依次拼接成最终的命令表，并使用memoize按 cwd 缓存加载结果，避免重复磁盘 I/O。值得注意的是，skillDirCommands内部又按 managed → user → project（各自最具体优先）→--add-dir的顺序排列，因此策略级 Skill 在同目录层级内拥有更高话语权。

执行上下文

Inline 模式（默认）

Skill 内容展开到当前对话中，Agent 直接看到提示词并在同一上下文中执行。

context: inline # 默认值，可省略

特点：

• 共享父对话的 token 预算
• 可以访问对话历史上下文
• allowedTools限制当前轮次可用工具
• model覆盖当前轮次使用的模型

从源码看，inline 路径由processPromptSlashCommand()承载：先经command.getPromptForCommand(args, context)展开内容（完成${CLAUDE_SKILL_DIR}、${CLAUDE_SESSION_ID}、$ARGUMENTS替换与内联 shell 执行），再注册 Skill 级 Hook、记录addInvokedSkill()，最后通过返回的contextModifier()闭包更新 allowedTools、model 与 effort——其中模型覆盖通过resolveSkillModelOverride()保留[1m]之类的后缀标记。

Fork 模式（子 Agent）

Skill 在隔离的子 Agent中运行，拥有独立的 token 预算和上下文。

context: fork agent: general-purpose # 可选，指定代理类型

特点：

• 独立的 token 预算，不消耗父对话额度
• 隔离的对话上下文
• 可指定不同的 agent 类型（如Bash、general-purpose）
• 执行完成后提取结果返回父对话
• 支持进度汇报（onProgress回调）

Fork 路径由executeForkedSkill()驱动（见 src/utils/forkedAgent.ts 的prepareForkedCommandContext()）：先获取 Skill 内容与工具白名单（parseToolListFromCLI），再通过createGetAppStateWithAllowedTools()修改 AppState 以收紧工具集，选择command.agent ?? 'general-purpose'作为子代理类型，把 Skill 内容包装成一条用户消息喂给runAgent()，最后从子代理消息中提取最后一条 assistant 文本作为结果嵌入 tool_result。fork 执行后不产生newMessages，这是它和 inline 在返回结构上的本质区别。

两种模式对比

条件激活

Skill 可以通过pathsfrontmatter 实现按需激活，只在操作匹配文件时才对模型可见。这能显著节省上下文：一个带paths的 Skill 在启动时被放入conditionalSkillsMap 而不暴露给模型，只有用户真正操作了匹配文件后才会被激活。

配置方式

--- name: TypeScript 修复 description: 修复 TypeScript 类型错误 paths: "src/**/*.ts, test/**/*.ts" ---

工作原理

1. 启动时加载所有 Skill 2. 带 paths 的 Skill 存入 conditionalSkills Map（不暴露给模型） 3. 当用户操作文件时（Read/Write/Edit） 4. activateConditionalSkillsForPaths() 用 ignore 库匹配 5. 匹配成功 → 移入 dynamicSkills Map → 模型可见 6. 一旦激活，在会话内持续有效

源码确认（见 src/skills/loadSkillsDir.ts）：加载时"无 paths → unconditionalSkills（立即可用），有 paths → conditionalSkills Map（等待激活）"；运行时activateConditionalSkillsForPaths()用ignore库把文件路径转为 cwd 相对路径后匹配 Glob 模式，命中即移入dynamicSkillsMap，同时记录遥测事件tengu_dynamic_skills_changed，并触发skillsLoaded.emit()使命令缓存失效，下一轮对话即加载新列表。

动态发现

除了条件激活，Skills 还支持运行时发现——操作深层目录文件时自动向上寻找技能目录：

1. 用户操作某个深层目录中的文件 2. discoverSkillDirsForPaths() 从文件路径向上遍历 3. 寻找 .claude/skills/ 与 .agents/skills/ 目录（不超过 cwd） 4. 跳过 .gitignore 忽略的目录 5. 发现新目录 → addSkillDirectories() → 加载并注册

discoverSkillDirsForPaths()（见 src/skills/loadSkillsDir.ts）从文件所在目录一路向上遍历到 cwd（不含 cwd 本身），逐层检查.claude/skills是否存在且未被.gitignore忽略，最终按深度从深到浅排序返回——这意味着就近的 Skill 优先级更高。缓存失效链为：skillsLoaded.emit()→clearCommandMemoizationCaches()（清空loadAllCommands、getSkillToolCommands、getSlashCommandToolSkills等缓存）→ 下一轮对话加载新列表。

权限控制

自动允许

如果 Skill 只包含"安全属性"（无allowedTools、无hooks、无fork），将自动获准执行，无需用户确认。源码中skillHasOnlySafeProperties()检查SAFE_SKILL_PROPERTIES白名单（type、name、description、source、loadedFrom 等基础字段）；核心逻辑是"新增的 frontmatter 字段默认需要权限，除非显式加入白名单"。

手动确认

包含工具限制、Hook 或 fork 执行的 Skill，首次调用时会提示用户：

Execute skill: my-custom-skill Allow? (y)es / (n)o / (a)lways allow / (d)eny

权限规则

处理顺序：deny 规则 → allow 规则 → 安全属性检查 → 询问用户。对应源码checkPermissions()的五步：Deny 规则检查（含精确匹配"commit" === commandName与前缀匹配"review:*"）→ 远程 Skill 自动允许（_canonical_<slug>前缀，Ant 专属实验性）→ Allow 规则检查 → 安全属性自动允许 → 默认询问用户（并给出"精确允许 + 前缀允许"的建议）。

快速参考

创建一个 Skill

# 1. 创建目录 mkdir -p ~/.claude/skills/my-skill # 2. 创建 SKILL.md cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF' --- name: 我的技能 description: 一个示例 Skill user-invocable: true --- # 技能内容 你好，这是我的自定义 Skill。 EOF

想偷懒的话，直接在终端输入/skillify可以让 Agent 帮你生成 Skill。仓库内置的skillify.ts（src/skills/bundled/skillify.ts）就是干这个的。

常用操作

Skill 可用性矩阵

深入：一个 Skill 从磁盘到对话的完整生命周期

结合 docs/internals/skills-internals.md 与源码，可以把上述内容串成一条清晰的链路，共四个阶段：

1. 发现与注册：CLI 启动时initBundledSkills()注册内置 Skills；getSkillDirCommands(cwd)并行加载 managed/user/project/--add-dir四个层级的目录 Skills，再经getFileIdentity()（realpath）去重、按paths分离条件 Skills；最终loadAllCommands()按优先级聚合全部来源并 memoize。
2. 注入到对话：每轮对话由getSkillListingAttachments()（src/utils/attachments.ts）生成 skill 列表，经formatCommandsWithinBudget()按上下文预算截断后，包装为<system-reminder>用户消息注入。预算常量为SKILL_BUDGET_CONTEXT_PERCENT = 0.01（上下文窗口的 1%）、DEFAULT_CHAR_BUDGET = 8000、MAX_LISTING_DESC_CHARS = 250（见 src/tools/SkillTool/prompt.ts）——技能列表只用于发现，正文在调用时才加载，因此编写描述时应先写清触发条件和用途，把操作步骤、示例和参考文件放进正文。
3. 调用与执行：SkillTool.validateInput()校验（错误码：1 格式无效、2 未知技能、4 模型调用被禁用、5 非 prompt 类型、6 远程技能未发现）→checkPermissions()权限检查 →SkillTool.call()按context分流到 inline 的processPromptSlashCommand()或 fork 的executeForkedSkill()。inline 内容通过addInvokedSkill()记录到会话状态，确保上下文压缩后仍可恢复。
4. 运行时发现：文件操作触发discoverSkillDirsForPaths()动态发现新目录与activateConditionalSkillsForPaths()条件激活，随后clearCommandMemoizationCaches()让下一轮对话加载最新列表。

Skill 级的 Hook 由registerSkillHooks()（src/utils/hooks/registerSkillHooks.ts）注册为会话级 Hook：遍历HOOK_EVENTS（PreToolUse、PostToolUse、Stop 等），为每个 matcher 调用addSessionHook()，once: true的 Hook 在首次执行后自动removeSessionHook()。

源码索引与延伸阅读

核心文件：

延伸阅读：Skills 的底层实现细节（发现、注入、fork 执行）可继续阅读 docs/internals/skills-internals.md；Skills 在整体架构中的位置参见 docs/internals/index.md；多 Agent 体系（fork 依赖的子代理机制）参见 docs/internals/agent.md 与 docs/internals/agent-internals.md。

• 人工智能
• AI 应用
• 桌面应用
• 代码智能体
• MCP Clients