feat(zh): add Chinese translations in zh/ directory
Add Chinese (Simplified) translations for all documentation, organized under a dedicated zh/ directory that mirrors the English folder structure. Co-authored-by: tanqingkuang <tanqingkuang@users.noreply.github.com> Translations originally contributed by @tanqingkuang in #45. Restructured from *-CN.md suffix pattern into zh/ directory to prevent the EPUB builder (scripts/build_epub.py collect_folder_files) from picking up Chinese files via glob("*.md") inside module folders.
This commit is contained in:
Luong NGUYEN
271
zh/03-skills/README.md
Normal file
271
zh/03-skills/README.md
Normal file
@@ -0,0 +1,271 @@
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
|
||||
<img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
|
||||
</picture>
|
||||
|
||||
# Agent Skills 指南
|
||||
|
||||
## 概览
|
||||
|
||||
Skills 是可以复用、可自动触发的能力包。一个 skill 通常包含 `SKILL.md`、参考文件、脚本和模板。Claude 在合适的场景下会自动加载它。
|
||||
|
||||
### 主要好处
|
||||
|
||||
- 可复用
|
||||
- 可渐进加载
|
||||
- 可以把脚本、模板、说明放在一起
|
||||
- 适合标准化流程
|
||||
|
||||
## Skills 的工作方式：渐进式披露
|
||||
|
||||
Skills 不会一次性把所有内容都塞进上下文，而是按需加载。
|
||||
|
||||
### 三层加载
|
||||
|
||||
1. **只看描述**：先判断这个 skill 是否相关
|
||||
2. **加载 `SKILL.md`**：读取核心说明
|
||||
3. **按需加载支持文件**：脚本、模板、参考资料
|
||||
|
||||
## Skill 加载流程
|
||||
|
||||
1. Claude 扫描技能目录
|
||||
2. 根据描述判断是否匹配当前任务
|
||||
3. 读取 `SKILL.md`
|
||||
4. 如有需要，再加载脚本和辅助文件
|
||||
|
||||
## Skill 类型与位置
|
||||
|
||||
Skills 可以放在：
|
||||
|
||||
- 项目目录下的 `.claude/skills/`
|
||||
- 用户目录下的 `~/.claude/skills/`
|
||||
|
||||
### 自动发现
|
||||
|
||||
只要目录结构正确，Claude 就会自动发现这些 Skills。
|
||||
|
||||
## 创建自定义 Skills
|
||||
|
||||
### 基本目录结构
|
||||
|
||||
```text
|
||||
my-skill/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
### `SKILL.md` 格式
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: my-skill
|
||||
description: 这个 skill 的用途，以及什么时候触发
|
||||
---
|
||||
|
||||
# Your Skill Name
|
||||
|
||||
## Instructions
|
||||
|
||||
## Examples
|
||||
```
|
||||
|
||||
### 必填字段
|
||||
|
||||
- `name`
|
||||
- `description`
|
||||
|
||||
### 可选 frontmatter 字段
|
||||
|
||||
- `argument-hint`
|
||||
- `allowed-tools`
|
||||
- `model`
|
||||
- `disable-model-invocation`
|
||||
- `user-invocable`
|
||||
- `context`
|
||||
- `agent`
|
||||
- `hooks`
|
||||
|
||||
## Skill 内容类型
|
||||
|
||||
### 参考内容
|
||||
|
||||
适合放规则、标准、文档片段和示例。
|
||||
|
||||
### 任务内容
|
||||
|
||||
适合放具体步骤、执行流程和结果格式要求。
|
||||
|
||||
## 控制 Skill 的调用
|
||||
|
||||
你可以通过 `disable-model-invocation`、`user-invocable` 和工具白名单来控制 Claude 是否能自动调用这个 skill。
|
||||
|
||||
## 字符串替换
|
||||
|
||||
Skills 支持 `$ARGUMENTS`、`$0`、`$1` 等参数替换。
|
||||
|
||||
### 动态上下文注入
|
||||
|
||||
你可以在 prompt 里插入 shell 命令结果：
|
||||
|
||||
```md
|
||||
- 当前 git 状态：!`git status`
|
||||
- 当前 diff：!`git diff HEAD`
|
||||
- 当前分支：!`git branch --show-current`
|
||||
```
|
||||
|
||||
## 在 subagent 中运行 Skills
|
||||
|
||||
某些 skill 适合在隔离上下文中运行，这样可以降低对主会话的影响。
|
||||
|
||||
## 实战示例
|
||||
|
||||
### 示例 1：代码审查 Skill
|
||||
|
||||
一个典型的审查 skill 会包含：
|
||||
|
||||
- 审查模板
|
||||
- 风险等级
|
||||
- 输出格式
|
||||
- 需要关注的维度
|
||||
|
||||
### 示例 2：代码库可视化 Skill
|
||||
|
||||
可以把代码库结构、依赖关系和模块边界总结给 Claude，便于快速理解。
|
||||
|
||||
### 示例 3：部署 Skill（只允许用户触发）
|
||||
|
||||
适合带副作用的操作，比如生产环境部署。通常会配合 `disable-model-invocation: true`。
|
||||
|
||||
### 示例 4：品牌语气 Skill
|
||||
|
||||
用于检查输出是否符合品牌语气、语调和表达风格。
|
||||
|
||||
### 示例 5：`CLAUDE.md` 生成 Skill
|
||||
|
||||
可以从项目文档中生成或补充 `CLAUDE.md`。
|
||||
|
||||
### 示例 6：带脚本的重构 Skill
|
||||
|
||||
常见组合是：
|
||||
|
||||
- `SKILL.md`
|
||||
- `scripts/`
|
||||
- `templates/`
|
||||
- `references/`
|
||||
|
||||
## 管理 Skills
|
||||
|
||||
### 查看可用 Skills
|
||||
|
||||
```bash
|
||||
/skills
|
||||
```
|
||||
|
||||
### 测试一个 Skill
|
||||
|
||||
把它放到测试目录或者临时项目里，然后通过相应命令触发。
|
||||
|
||||
### 更新 Skill
|
||||
|
||||
修改 `SKILL.md` 或支持文件后，重新打开会话或重新加载即可。
|
||||
|
||||
### 限制 Claude 对 Skill 的访问
|
||||
|
||||
你可以通过权限配置，只允许 Claude 访问某些 skill。
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 描述要具体
|
||||
|
||||
让 `description` 明确说明这个 skill 在什么时候触发。
|
||||
|
||||
### 2. 保持聚焦
|
||||
|
||||
一个 skill 解决一个问题，不要什么都塞进去。
|
||||
|
||||
### 3. 包含触发词
|
||||
|
||||
在描述里加入相关关键词，帮助 Claude 更准确地选择它。
|
||||
|
||||
### 4. `SKILL.md` 不要太长
|
||||
|
||||
尽量控制在 500 行以内，超过就拆分支持文件。
|
||||
|
||||
### 5. 引用支持文件
|
||||
|
||||
把重复内容移到脚本或参考文件中，主文件只保留核心说明。
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 快速参考
|
||||
|
||||
- 检查目录结构是否正确
|
||||
- 检查 `SKILL.md` frontmatter 是否有效
|
||||
- 检查 skill 名称是否和调用名一致
|
||||
|
||||
### Skill 没有触发
|
||||
|
||||
- 检查描述是否足够具体
|
||||
- 检查目录是否在 Claude 可见范围内
|
||||
- 检查是否被更高优先级的 skill 覆盖
|
||||
|
||||
### Skill 触发太频繁
|
||||
|
||||
- 收紧描述
|
||||
- 增加约束条件
|
||||
- 用更具体的触发词
|
||||
|
||||
### Claude 看不到全部 Skills
|
||||
|
||||
- 检查路径
|
||||
- 检查权限
|
||||
- 重新加载会话
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
- 不要在 skill 中硬编码密钥
|
||||
- 对副作用操作保持用户触发
|
||||
- 给自动触发的 skill 设置清晰边界
|
||||
|
||||
## Skills vs 其他功能
|
||||
|
||||
| 功能 | 触发方式 | 适合场景 |
|
||||
|------|----------|----------|
|
||||
| Skills | 自动/半自动 | 复用能力、流程标准化 |
|
||||
| Slash Commands | 手动 | 快捷命令 |
|
||||
| Subagents | 自动委派 | 隔离任务 |
|
||||
| Hooks | 事件触发 | 自动化和验证 |
|
||||
|
||||
## 内置 Skills
|
||||
|
||||
Claude Code 自带一些 Skills，例如批处理、调试、简化和 Claude API 相关内容。
|
||||
|
||||
## 共享 Skills
|
||||
|
||||
### 项目 Skills（团队共享）
|
||||
|
||||
把 skill 放在项目目录里，团队成员都能用。
|
||||
|
||||
### 个人 Skills
|
||||
|
||||
```bash
|
||||
# 复制到个人目录
|
||||
mkdir -p ~/.claude/skills
|
||||
|
||||
# 让脚本可执行
|
||||
chmod +x ~/.claude/skills/*/scripts/*
|
||||
```
|
||||
|
||||
### Plugin 分发
|
||||
|
||||
你也可以把 Skills 作为插件的一部分发布出去。
|
||||
|
||||
## 继续深入
|
||||
|
||||
如果你要管理一整套 Skills，可以再做一个 skill collection 或 skill manager，用来统一发现、更新和分发。
|
||||
|
||||
## 更多资源
|
||||
|
||||
- [根目录中文指南](../README.md)
|
||||
- [Slash Commands 中文参考](../01-slash-commands/README.md)
|
||||
- [Memory 中文指南](../02-memory/README.md)
|
||||
- [Subagents 中文参考](../04-subagents/README.md)
|
||||
Reference in New Issue
Block a user