mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-07-31 16:33:34 +08:00
c2cd615824
The site had drifted from the product. Every screenshot predated the v0.5.0 UI redesign, the reading experience shipped no search and no syntax highlighting, and a third of the pages were internal process artefacts — migration task lists addressed to agentic workers, a release runbook, a proposal marked "historical". Reorganise around the only two people who read this: someone getting the desktop app running for the first time, and someone reading the source. Five sections replace nine — start / desktop / im / cli / internals — and the pages that served neither reader are gone. Site rewrite: - Palette lifted from the desktop app's 「纸·墨·印」 themes, so the site and the product read as one thing. Light mirrors 纯白, dark mirrors 墨夜, and dark mode exists at all now. - Fonts are self-hosted. The old @import from Google Fonts is unreachable from mainland China, which left every heading in a fallback serif; it also only requested weight 600 while the CSS asked for 900, so Latin and CJK in the same heading disagreed. - Docs were shipped as one 968KB manifest downloaded on every page view. Split into a 32KB index plus one lazily imported chunk per page; the entry bundle is now 101KB gzipped. - Add search, syntax highlighting, per-route meta with canonical and hreflang, a sitemap, and an error boundary. Replace the 44vh mobile sidebar with a drawer. - Image dimensions are read at build time and written into the tag, so lazy images reserve their space instead of collapsing. Screenshots are recaptured from a real v0.5.0 build against a clean demo project, with tokens, QR codes and paired accounts redacted. The previous set is deleted rather than kept alongside. Routes follow file paths, so the restructure would have broken every inbound link; 37 old paths redirect, in both languages. The PR policy gate and CODEOWNERS also hardcoded docs/guide/contributing.md. Verified: check:docs 78 pages / 323 links / 0 problems, check:policy 127 pass. Walked every route at 1440 and 390 in both themes for overflow, contrast, keyboard reachability and focus management.
404 lines
13 KiB
Markdown
404 lines
13 KiB
Markdown
---
|
||
title: Skills 使用指南
|
||
nav_title: Skills 使用
|
||
description: Skill 的六种来源、定义格式、调用方式、执行上下文与权限控制。
|
||
order: 7
|
||
---
|
||
|
||
# Skills 使用指南
|
||
|
||
Skills 是 Claude Code 的扩展能力引擎，让你用 Markdown 文件定义专属的自动化工作流。
|
||
|
||
|
||
|
||
## 什么是 Skills？
|
||
|
||
Skills 是 Claude Code 的**可扩展能力插件系统**。每个 Skill 是一个 Markdown 文件（含 YAML frontmatter），定义了一段专门的提示词和行为配置，让 Claude 在特定场景下执行专业化的工作流。
|
||
|
||
核心能力：
|
||
|
||
| 能力 | 说明 |
|
||
|------|------|
|
||
| 专业化工作流 | 定义代码审查、TDD、调试等标准流程 |
|
||
| 工具权限控制 | 限制 Skill 只能使用指定的工具 |
|
||
| 模型切换 | 为不同 Skill 指定不同的模型 |
|
||
| 执行隔离 | Fork 模式在子 Agent 中独立运行 |
|
||
| 条件激活 | 只在操作特定文件时才激活 |
|
||
| Hook 注入 | Skill 调用时自动注册生命周期钩子 |
|
||
|
||
## 六种 Skill 来源
|
||
|
||
|
||
|
||
Claude Code 从 6 个不同来源加载 Skills，按优先级从高到低：
|
||
|
||
### 1. Bundled（内置 Skills）
|
||
|
||
编译到 CLI 二进制中，所有用户可用。以 TypeScript 定义，通过 `registerBundledSkill()` 注册。
|
||
|
||
**当前内置 Skills：**
|
||
|
||
| Skill | 说明 | 特殊条件 |
|
||
|-------|------|----------|
|
||
| `/verify` | 验证代码变更 | — |
|
||
| `/debug` | 调试助手 | — |
|
||
| `/simplify` | 代码简化审查 | — |
|
||
| `/remember` | 记忆管理 | 需启用 auto-memory |
|
||
| `/batch` | 批量处理 | — |
|
||
| `/stuck` | 卡住时求助 | — |
|
||
| `/skillify` | 创建新 Skill | — |
|
||
| `/keybindings` | 自定义快捷键 | — |
|
||
| `/loop` | 定时循环任务 | AGENT_TRIGGERS 特性门控 |
|
||
| `/schedule` | 远程代理调度 | AGENT_TRIGGERS_REMOTE 特性门控 |
|
||
| `/claude-api` | Claude API 集成 | BUILDING_CLAUDE_APPS 特性门控 |
|
||
| `/dream` | 自动记忆整理 | KAIROS 特性门控 |
|
||
|
||
### 2. Managed（策略管理 Skills）
|
||
|
||
由组织策略控制，存放在 `<managed-path>/.claude/skills/`，适用于企业部署。
|
||
|
||
### 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
|
||
```
|
||
|
||
### 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
|
||
```
|
||
|
||
### 关于 `.agents/skills/`（Agent Skills 开放标准）
|
||
|
||
`.agents/skills/` 是 [agentskills.io](https://agentskills.io) 规范推荐的跨客户端共享目录，
|
||
OpenAI Codex、Cursor、Gemini CLI、opencode 等工具都会扫描它。放在这里的技能不必再往每个
|
||
工具的私有目录里复制一份。
|
||
|
||
- 两种目录**同时生效**，`SKILL.md` 格式完全一致，无需改写。
|
||
- 同一层级下若出现同名技能，`.claude/` 优先，`.agents/` 中的同名项被忽略（会记录一条 warn 日志）。
|
||
不同层级（如用户级与项目级）同名仍按原有规则各自保留。
|
||
- 通过软链接共享同一份技能时会自动识别为同一个，不会重复加载。
|
||
- 如需关闭，在 `settings.json` 中设置 `"disableAgentSkillsDirectory": true`，
|
||
或设置环境变量 `CLAUDE_CODE_DISABLE_AGENT_SKILLS_DIR=1`。关闭后 `.claude/skills/` 不受影响。
|
||
- 技能市场安装、`/skillify` 创建等写入操作仍然写到 `~/.claude/skills/`。
|
||
|
||
### 5. Plugin（插件 Skills）
|
||
|
||
由已安装的插件提供。插件通过 manifest 的 `skillsPath` / `skillsPaths` 声明 Skills 目录。
|
||
|
||
命名格式：`{pluginName}:{skillName}`
|
||
|
||
```
|
||
例如：superpowers:code-reviewer
|
||
superpowers:brainstorming
|
||
```
|
||
|
||
### 6. MCP（MCP 服务器 Skills）
|
||
|
||
由连接的 MCP 服务器提供，命名格式：`mcp__server-name__prompt-name`。
|
||
|
||
**安全限制**：MCP Skills 为远程不受信来源，**禁止执行** `!`...`` 内联 shell 命令。
|
||
|
||
## Skill 定义格式
|
||
|
||
### 目录结构
|
||
|
||
每个 Skill 是一个目录，包含一个 `SKILL.md` 文件：
|
||
|
||
```
|
||
skill-name/
|
||
└── SKILL.md ← 文件名必须是 SKILL.md（大小写不敏感）
|
||
```
|
||
|
||
### Frontmatter 完整字段
|
||
|
||
```yaml
|
||
---
|
||
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 命令执行
|
||
```
|
||
|
||
### Frontmatter 字段速查表
|
||
|
||
| 字段 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `name` | string | 目录名 | 显示名称覆盖 |
|
||
| `description` | string | 自动提取 | Skill 简述 |
|
||
| `when_to_use` | string | — | 使用场景描述 |
|
||
| `user-invocable` | boolean | true | 用户能否输入 /name 调用 |
|
||
| `disable-model-invocation` | boolean | false | 禁止模型调用 |
|
||
| `context` | `inline` \| `fork` | inline | 执行上下文 |
|
||
| `agent` | string | general-purpose | fork 时代理类型 |
|
||
| `model` | string | 继承 | 模型覆盖（haiku/sonnet/opus） |
|
||
| `effort` | string \| int | — | 思考力度 |
|
||
| `allowed-tools` | string \| list | 全部 | 允许工具白名单 |
|
||
| `paths` | string \| list | — | 条件激活 Glob 模式 |
|
||
| `shell` | `bash` \| `powershell` | bash | Shell 命令类型 |
|
||
| `hooks` | object | — | 生命周期 Hook 配置 |
|
||
| `argument-hint` | string | — | 参数提示文本 |
|
||
| `version` | string | — | 版本号 |
|
||
|
||
## 调用方式
|
||
|
||
|
||
|
||
### 方式一：用户斜杠命令
|
||
|
||
直接在终端输入 `/skill-name`：
|
||
|
||
```
|
||
> /commit
|
||
> /review-pr 123
|
||
> /verify
|
||
```
|
||
|
||
**前提**：Skill 的 `user-invocable` 必须为 `true`。
|
||
|
||
### 方式二：模型自动调用
|
||
|
||
Claude 在对话中识别到合适的 Skill 时，通过 SkillTool 自动调用：
|
||
|
||
```
|
||
用户：帮我审查一下这段代码
|
||
Claude：[通过 SkillTool 调用 superpowers:code-reviewer]
|
||
```
|
||
|
||
**前提**：Skill 的 `disable-model-invocation` 不能为 `true`。
|
||
|
||
### 方式三：嵌套调用
|
||
|
||
一个 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（内建命令） ← 最低优先级
|
||
```
|
||
|
||
## 执行上下文
|
||
|
||
### Inline 模式（默认）
|
||
|
||
Skill 内容**展开到当前对话**中，Claude 直接看到提示词并在同一上下文中执行。
|
||
|
||
```yaml
|
||
context: inline # 默认值，可省略
|
||
```
|
||
|
||
**特点：**
|
||
- 共享父对话的 token 预算
|
||
- 可以访问对话历史上下文
|
||
- `allowedTools` 限制当前轮次可用工具
|
||
- `model` 覆盖当前轮次使用的模型
|
||
|
||
### Fork 模式（子 Agent）
|
||
|
||
Skill 在**隔离的子 Agent**中运行，拥有独立的 token 预算和上下文。
|
||
|
||
```yaml
|
||
context: fork
|
||
agent: general-purpose # 可选，指定代理类型
|
||
```
|
||
|
||
**特点：**
|
||
- 独立的 token 预算，不消耗父对话额度
|
||
- 隔离的对话上下文
|
||
- 可指定不同的 agent 类型（如 `Bash`、`general-purpose`）
|
||
- 执行完成后提取结果返回父对话
|
||
- 支持进度汇报（`onProgress` 回调）
|
||
|
||
### 两种模式对比
|
||
|
||
| 特性 | Inline | Fork |
|
||
|------|--------|------|
|
||
| Token 预算 | 共享父对话 | 独立预算 |
|
||
| 上下文访问 | 完整对话历史 | 仅 Skill 提示词 |
|
||
| 结果返回 | 直接在对话中 | 提取文本嵌入 tool_result |
|
||
| 适用场景 | 简短指导、扩展上下文 | 长任务、独立运算 |
|
||
| 工具限制 | contextModifier 修改 | modifiedGetAppState |
|
||
|
||
## 条件激活
|
||
|
||
Skill 可以通过 `paths` frontmatter 实现**按需激活**，只在操作匹配文件时才对模型可见。
|
||
|
||
### 配置方式
|
||
|
||
```yaml
|
||
---
|
||
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. 一旦激活，在会话内持续有效
|
||
```
|
||
|
||
### 动态发现
|
||
|
||
除了条件激活，Skills 还支持**运行时发现**：
|
||
|
||
```
|
||
1. 用户操作某个深层目录中的文件
|
||
2. discoverSkillDirsForPaths() 从文件路径向上遍历
|
||
3. 寻找 .claude/skills/ 与 .agents/skills/ 目录（不超过 cwd）
|
||
4. 跳过 .gitignore 忽略的目录
|
||
5. 发现新目录 → addSkillDirectories() → 加载并注册
|
||
```
|
||
|
||
## 权限控制
|
||
|
||
### 自动允许
|
||
|
||
如果 Skill 只包含"安全属性"（无 `allowedTools`、无 `hooks`、无 `fork`），将**自动获准**执行，无需用户确认。
|
||
|
||
### 手动确认
|
||
|
||
包含工具限制、Hook 或 fork 执行的 Skill，首次调用时会提示用户：
|
||
|
||
```
|
||
Execute skill: my-custom-skill
|
||
Allow? (y)es / (n)o / (a)lways allow / (d)eny
|
||
```
|
||
|
||
### 权限规则
|
||
|
||
| 规则类型 | 格式 | 说明 |
|
||
|----------|------|------|
|
||
| 精确允许 | `Skill:commit` | 允许执行 commit Skill |
|
||
| 前缀允许 | `Skill:review:*` | 允许所有 review: 前缀的 Skill |
|
||
| 精确拒绝 | `Skill:dangerous` 设为 deny | 拒绝执行 |
|
||
| 前缀拒绝 | `Skill:untrusted:*` 设为 deny | 拒绝所有 untrusted: 前缀 |
|
||
|
||
**处理顺序：** deny 规则 → allow 规则 → 安全属性检查 → 询问用户
|
||
|
||
## 快速参考
|
||
|
||
### 创建一个 Skill
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
### 常用操作
|
||
|
||
| 操作 | 方法 |
|
||
|------|------|
|
||
| 创建 Skill | `~/.claude/skills/<name>/SKILL.md` |
|
||
| 项目级 Skill | `.claude/skills/<name>/SKILL.md` |
|
||
| 跨工具共享 Skill | `~/.agents/skills/<name>/SKILL.md`（Codex / Cursor / Gemini CLI 同样可见） |
|
||
| 调用 Skill | 终端输入 `/skill-name` |
|
||
| 查看可用 Skills | 终端输入 `/skills` |
|
||
| 用 AI 创建 Skill | `/skillify` |
|
||
| 限制工具 | frontmatter 添加 `allowed-tools` |
|
||
| Fork 执行 | frontmatter 添加 `context: fork` |
|
||
| 条件激活 | frontmatter 添加 `paths: "src/**"` |
|
||
|
||
### Skill 可用性矩阵
|
||
|
||
| 来源 | 用户可调用 | 模型可调用 | 支持 Fork | 支持 Hook |
|
||
|------|-----------|-----------|----------|----------|
|
||
| Bundled | 依定义 | 依定义 | 是 | 是 |
|
||
| Managed | 是 | 是 | 是 | 是 |
|
||
| User | 是（默认） | 是 | 是 | 是 |
|
||
| Project | 是（默认） | 是 | 是 | 是 |
|
||
| Plugin | 依配置 | 依配置 | 是 | 是 |
|
||
| MCP | 依配置 | 依配置 | 是 | 否（安全限制） |
|