企业官网建设流程全解析

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

这篇指南以 cc-haha 桌面端（docs/en/desktop/skills.md）的技能与技能市场功能为主线，系统讲解技能（Skill）与 Agent 的本质区别、技能市场的聚合来源与安全徽标解读、安装前的安全审查流程、已装技能的分组管理与跨客户端.agents/skills/约定。读完本文，你将能够安全地安装第三方技能、管理本机全部技能来源，并掌握SKILL.md的编写格式、六种加载来源与调用/执行/权限控制机制，同时结合仓库源码印证每一处实现细节。

什么是技能：与 Agent 的本质区别

技能是别人已经写好的一套「做法」。安装之后，Claude 遇到匹配场景时就会照着这套流程执行。例如一个「PDF 处理」技能会告诉它用哪个库、按什么顺序拆分页面、遇到加密文件如何处理——你不需要每次重新交代一遍。

技能与 Agent 的区别：

从源码看，桌面端用 desktop/src/types/skill.ts 中的SkillMeta统一描述一个技能：它记录name、description、source（来源）、userInvocable（是否可被/技能名调用）、version、contentLength（正文长度，用于估算 token 占用）以及hasDirectory等信息，还有SkillDetail负责把技能的文件树（tree）和文件内容（files）暴露给界面层，这正是详情页「文档模式 / 代码模式」的数据基础。

技能市场：聚合 ClawHub 与 SkillHub

点击侧边栏的技能市场（Skills Market）即可进入。市场同时聚合ClawHub和SkillHub两个来源，列表向下滚动时会自动加载更多内容——没有「加载更多」按钮。

顶部有三个筛选器：

• 来源（Source）— 全部 / ClawHub / SkillHub。
• 安全状态（Security）— 见下文「安全徽标」。
• 安装状态（Install status）— 全部技能 / 已安装 / 未安装。

搜索框支持按名称和关键词匹配。

这一「无限滚动」行为在源码中有明确实现：desktop/src/components/market/MarketHome.tsx 定义了PREFETCH_MARGIN = '400px'，注释说明它会在最后一行卡片仍然在屏时就提前请求下一页，让骨架屏成为「还有更多内容」的提示而不是一道需要点击的墙。整个列表由useMarketStore驱动的nextCursor/loadMore/loadMoreError状态支撑，配合useMarketGridFill完成网格占位填充。

如何读懂安全徽标

每张卡片右上角都有一个安全徽标，它反映的是来源方（source）的扫描结果，不是本应用自身的审计结论：

「未审计」不等于不安全，只是没人查过；「存在风险」的技能除非你逐行读懂了它在干什么，否则不要安装。

源码侧，desktop/src/components/market/SecurityBadge.tsx 把四种状态映射为四种视觉语义：verified与benign映射为success，unknown映射为neutral，flagged映射为danger，并分别使用BadgeCheck、ShieldCheck、ShieldQuestion、ShieldAlert图标——「未审计」用问号盾牌、「存在风险」用告警盾牌，界面语义与本文的解读一一对应。

安装之前：三条必做的安全审查

技能会带来新的工具、脚本和外部依赖，安装后 Claude 就可能执行它们。市场页面顶部的免责声明是真实的：这些技能来自社区第三方来源，本应用不对其内容做安全审计。

官方建议的安装前检查流程：

1. 打开详情页的「文件（Files）」标签，通读SKILL.md及其配套脚本；
2. 拿不准就交给 Claude 先扫一遍——例如直接说「帮我看看这个技能的文件里有没有可疑的东西」；
3. 确认你确实需要它。装得多不等于更强，每个技能都会占用上下文。

从源码看，详情页的文件浏览能力由 desktop/src/components/market/SkillDetailView.tsx、FilePreview.tsx与FrontmatterPanel.tsx协作完成，能够把技能的SKILL.md、配套脚本以文件树形式展开并预览，同时高亮其 YAML frontmatter 字段，方便你在安装前逐项核对。

点击「安装」会弹出确认框，其中明确写有：安装位置、安全提示，以及「安装完成后，技能将在新会话中生效」的提醒。已经打开的会话不会立刻拿到新技能——必须新建一条会话。

desktop/src/components/market/InstallConfirmDialog.tsx 的源码印证了这一点：确认框内展示了来源、版本号、安全徽标（SecurityBadge），以及安装路径（如…/skills/{slug.toLowerCase()}/）；且当securityStatus为flagged或unknown时，会切换为告警/疑问图标（ShieldAlert/ShieldQuestion），用 UI 差异提示风险等级。

卸载入口与安装位于同一处，卸载会删除该技能目录下的本地文件。

已安装的技能：设置 → 技能

设置 → 技能（Settings → Skills）列出本机所有可用技能，按来源分组：

• 用户（User）— 你安装的，位于~/.claude/skills/；
• 项目（Project）— 随仓库一起分发；
• 插件（Plugin）— 由某个插件打包携带；
• 内置（Built-in）— 应用自带。

每条记录显示其入口文件（entry file）、文件数量与预估 token 占用。点击进入后可在「文档模式（doc mode）」与「代码模式（code mode）」之间切换，直接阅读技能的正文（prose）与源码文件。

界面层对应 desktop/src/components/skills/SkillDetail.tsx，而类型层则由SkillDetail（含skillRoot、tree、files、可选的marketMeta）支撑；当技能来自技能市场时，marketMeta会记录其id、source、slug、version、fileCount等安装元数据，用于展示安装来源信息。

.agents/skills/跨客户端约定

除了~/.claude/skills/，桌面端还会读取~/.agents/skills/。这是一个开放标准目录，Codex、Cursor、Gemini CLI 等客户端共享同一份技能——安装一次，多个工具都能用。来自该目录的技能会在列表中带一个.agents标记。

项目自己的.agents/skills/同理：它随仓库分发，而不是你手动安装的。

:::warning 跨客户端目录意味着其他工具安装的技能在这里同样生效。请定期浏览一遍设置 → 技能的列表，确认里面没有你不认识的东西。 :::

该约定的类型支持同样能在源码中看到：desktop/src/types/skill.ts 定义了SkillRootFlavor = 'claude' | 'agents'，明确注释其含义是「技能所在的目录约定：本地的.claude/skills或与 Codex、Cursor、Gemini CLI 共享的跨客户端.agents/skills」。

深入机制：六种技能来源与加载优先级

官方文档指出，想了解技能的加载机制和文件格式，可阅读 Skills 系统原理。技能本质上是 Claude Code 的可扩展能力引擎，每种技能是一个带 YAML frontmatter 的 Markdown 文件，按优先级从高到低共有 6 种来源：

同名技能跨来源解析时的优先级（先匹配者胜）：内置技能 → 内置插件 → 技能目录（用户/项目） → 工作流命令 → 插件命令 → 插件技能 → 内置命令。

关于.agents/skills/还有几个关键行为：

• 两个目录同时生效，且SKILL.md格式完全相同，无需改写；
• 若同一层级同名，.claude/优先，.agents/条目被跳过（记录一条 warn 级日志）；跨层级（如用户级与项目级）同名则各自共存；
• 通过符号链接共享的同一个技能只识别为一份，不会被重复加载；
• 如需关闭，在settings.json中设置"disableAgentSkillsDirectory": true，或设置环境变量CLAUDE_CODE_DISABLE_AGENT_SKILLS_DIR=1（不影响.claude/skills/）；
• 写入操作（技能市场安装、/skillify）仍固定写入~/.claude/skills/。

SKILL.md 格式：如何编写一个技能

每个技能是一个包含SKILL.md文件的目录（文件名不区分大小写）：

skill-name/ └── SKILL.md

SKILL.md由 YAML frontmatter（元数据）与 Markdown 正文（Claude 看到的行为提示词）组成。以下是完整的 frontmatter 示例：

--- name: My Skill # 显示名（可选，默认取目录名） description: What this skill does # 描述（必填；缺失时从正文自动提取） when_to_use: When to use this skill # 使用场景描述（可选） version: 1.0.0 # 版本号（可选） # ── 调用控制 ── user-invocable: true # 是否允许用户通过 /技能名 调用（默认 true） disable-model-invocation: false # 是否禁止模型通过 Skill 工具调用（可选） argument-hint: "<file path>" # 参数提示（可选） # ── 执行配置 ── 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 模式；仅操作匹配文件时激活 # ── 生命周期钩子 ── hooks: PreToolUse: - matcher: "Bash" hooks: - command: "echo 'Before bash'" once: true # 只执行一次 --- # 技能正文 这是技能被调用时 Claude 看到的 Markdown 格式提示词。

正文中支持的特殊语法：${CLAUDE_SKILL_DIR}（展开为技能所在目录）、${CLAUDE_SESSION_ID}（当前会话 ID）、$ARGUMENTS/${ARG1}（参数替换）、!`shell command`（内联 shell 命令执行）。

Frontmatter 字段速查表

调用方式、执行上下文与权限控制

三种调用方式

1. 用户斜杠命令：在终端直接输入/skill-name，如/commit、/review-pr 123、/verify。前提：该技能的user-invocable为true。
2. 模型自动调用：对话中 Claude 识别到合适技能时，通过 SkillTool 自动调用（如用户请求评审代码时调用superpowers:code-reviewer）。前提：disable-model-invocation不为true。
3. 嵌套调用：一个技能在执行中触发另一个技能（如/verify内部调用/simplify），通过invocation_trigger: 'nested-skill'在遥测中跟踪。

Inline 与 Fork 两种执行上下文

• Inline（默认）：技能内容展开进当前对话，与父会话共享 token 预算、可访问完整对话历史；allowedTools限制当前回合可用工具，model可覆盖当前回合模型。
• Fork（子代理）：在隔离的子代理中运行，拥有独立的 token 预算与上下文；可指定不同代理类型（如Bash、general-purpose）；完成后将结果文本提取回父对话；支持进度回调（onProgress）。

条件激活（Conditional Activation）

通过pathsfrontmatter 实现按需激活：技能在启动时全部加载，带paths的技能存入conditionalSkillsMap（不暴露给模型）；当用户操作匹配文件（Read/Write/Edit）时，activateConditionalSkillsForPaths()使用 ignore 库匹配；命中后移入dynamicSkillsMap 对模型可见，且激活后在整个会话期间保持活跃。

此外还有运行时发现机制：discoverSkillDirsForPaths()从文件路径向上遍历查找.claude/skills/与.agents/skills/（不超过 cwd），跳过.gitignore忽略的目录，发现新目录即调用addSkillDirectories()加载注册。

权限控制

• 自动放行：技能只含「安全属性」（无allowedTools、无hooks、无fork）时自动批准执行，无需用户确认；
• 手动确认：含工具限制、钩子或 fork 执行的技能，首次调用会提示：

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

• 权限规则：

处理顺序：拒绝规则 → 允许规则 → 安全属性检查 → 询问用户。

MCP 技能因来源远程不可信，不允许执行内联 shell 命令，这是其与其余来源在能力矩阵上的唯一硬性差异。

快速参考：创建与常用操作

创建一个技能：

# 1. 创建目录 mkdir -p ~/.claude/skills/my-skill # 2. 创建 SKILL.md cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF' --- name: My Skill description: An example Skill user-invocable: true --- # Skill Content Hello, this is my custom Skill. EOF

技能能力矩阵

小结

技能市场把社区沉淀的「现成做法」直接变成 Claude 可执行的能力，但安装前务必用「读文件 → 让 Claude 先扫 → 确认必要性」三步把关。安装后，通过 设置 → 技能 统一管理用户、项目、插件与内置四类技能，并善用.agents/skills/实现跨客户端复用。若想进一步了解技能的加载机制、SKILL.md文件格式、六种来源的优先级、Inline/Fork 执行上下文与权限控制，请继续阅读 Skills 系统原理；中文读者也可对照 中文版技能文档 与 技能使用指南（中文） 查阅。

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