gen-new-skill
生成具有正确 SKILL.md 格式的新 Claude Code 技能。当用户想要创建新技能、制作自定义技能、编写技能文档、自动化工作流、或提到"生成技能"、"新建技能"、"技能模板"、"skill"时使用。支持个人技能和项目技能的创建。
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- Updated: 2025-11-22
Download the latest version (v1.0.0) from this page.
SKILL.md
---
name: gen-new-skill
description: 生成具有正确 SKILL.md 格式的新 Claude Code 技能。当用户想要创建新技能、制作自定义技能、编写技能文档、自动化工作流、或提到"生成技能"、"新建技能"、"技能模板"、"skill"时使用。支持个人技能和项目技能的创建。
---
# 生成新技能
此技能帮助您创建具有正确结构和格式的新 Claude Code 技能。
## 技能类型
在开始之前，先确定技能类型：
- **项目技能** (`.claude/skills/`): 与团队共享的项目特定功能，通过 git 提交后团队成员自动获得
- **个人技能** (`~/.claude/skills/`): 个人工作流、实验性项目和跨项目使用的个人生产力工具
## 使用说明
创建新技能时，请遵循以下步骤：
### 1. 收集需求
- 询问用户该技能应该做什么
- **关键**: 确定技能应该何时触发 (什么关键词或场景) - 这对 Claude 自动发现技能至关重要
- 识别任何应该被限制或允许的工具
- 确定技能类型 (个人技能还是项目技能)
### 2. 创建技能目录结构
- 项目技能：在 `.claude/skills/` 下创建目录
- 个人技能：在 `~/.claude/skills/` 下创建目录
- 目录名仅使用小写字母、数字和连字符 (最多 64 个字符)
- 创建主 `SKILL.md` 文件
```
skill-name/
├── SKILL.md (必需)
├── reference.md (可选)
├── examples.md (可选)
├── scripts/ (可选)
└── templates/ (可选)
```
### 3. 编写包含必需字段的 SKILL.md
```yaml
---
name: skill-name
description: 具体描述此技能的作用、何时使用、包含触发关键词 (最多 1024 个字符)
---
```
**重要**: description 字段是 Claude 发现技能的关键。要具体、包含触发关键词和使用场景。
- ❌ 模糊: "帮助处理文档"
- ✅ 具体: "从 PDF 文件提取文本和表格、填写表单、合并文档。当处理 PDF、表单或文档提取时使用。"
### 4. 根据需要添加可选字段
- `allowed-tools`: 限制 Claude 可以使用的工具 (例如：`["Read", "Grep", "Glob"]`)
- 用于只读分析、安全敏感工作流或限制操作范围
### 5. 编写清晰的说明
- 提供分步指导
- 具体说明何时以及如何使用该技能
- 包含关于它解决的问题的上下文
- 使用标题、列表和代码块提高可读性
### 6. 添加示例
- 展示具体的使用示例
- 包括简单和复杂的场景
- 演示预期的输入和输出
- 显示典型的用户请求和预期的技能行为
### 7. 创建支持文件 (可选)
Claude 会逐步读取支持文件，高效使用上下文：
- `reference.md`: 额外的参考文档
- `examples.md`: 扩展示例
- `scripts/`: Shell 脚本或实用程序
- `templates/`: 文件模板或样板代码
### 8. 测试技能
- 技能是"模型调用"的 - Claude 根据请求上下文和技能描述自动决定使用
- 测试方法：提出与 description 匹配的问题，验证 Claude 是否自动激活技能
- 检查技能是否按预期工作
- 如果技能未被激活，改进 description 使其更具体
## 最佳实践
### 描述质量
具体且包含触发关键词的描述是关键：
- ❌ "帮助处理文档"
- ✅ "从 PDF 文件提取文本和表格、填写表单、合并文档。当处理 PDF、表单或文档提取时使用。"
### 专注与范围
单个技能应解决单一功能而非广泛功能：
- ✅ "PDF 表单填写"
- ❌ "文档处理"
### 工具权限
使用 `allowed-tools` 字段在技能激活时限制 Claude 的能力，适用于只读访问或安全敏感工作流。
### 文件组织
Claude 逐步读取支持文件，高效使用上下文。从 SKILL.md 使用 markdown 链接引用额外文件。
### 激活机制
技能是"模型调用"的 - Claude 根据请求上下文和技能描述自动决定使用，与用户调用的斜杠命令不同。
## 示例
### 示例 1: 带测试的 Git 提交
```yaml
---
name: commit-with-tests
description: 仅在成功运行测试后创建 git 提交。当提交需要测试验证的代码更改、或用户提到"测试后提交"、"验证提交"时使用。
---
# 带测试的提交
在创建 git 提交之前自动运行测试套件，确保所有测试通过后才提交代码。
## 使用说明
1. 识别项目的测试命令 (npm test、pytest、go test 等)
2. 运行完整的测试套件
3. 如果所有测试通过：
- 暂存相关更改
- 创建描述性提交消息
- 创建 git 提交
4. 如果测试失败：
- 报告失败的测试
- 不创建提交
- 建议用户修复失败的测试
## 示例
用户: "提交我的更改"
→ 首先运行测试套件，如果通过则提交
用户: "我完成了这个功能，提交它"
→ 验证测试通过，然后创建带有功能描述的提交
```
### 示例 2: 只读代码分析
```yaml
---
name: read-only-analysis
description: 在不进行任何更改的情况下分析代码。用于代码审查、理解现有代码、或用户要求"只读分析"、"分析代码"时使用。
allowed-tools: ["Read", "Grep", "Glob", "Bash"]
---
# 只读代码分析
对代码库进行全面分析，不做任何修改。适用于代码审查、理解架构或评估代码质量。
## 使用说明
1. 使用 Grep 和 Glob 搜索相关代码模式
2. 使用 Read 检查具体文件内容
3. 分析代码结构、模式和潜在问题
4. 提供详细的分析报告和建议
5. **绝不修改任何文件** - 仅提供建议
## 受限工具
此技能仅允许使用只读工具：
- Read: 查看文件内容
- Grep: 搜索代码模式
- Glob: 查找文件
- Bash: 运行只读命令 (如 git log)
## 示例
用户: "分析认证实现的安全性"
→ 搜索认证相关代码，分析安全实践，提供改进建议
用户: "这个项目的代码质量如何？"
→ 检查代码结构、测试覆盖率、文档，提供质量评估
```
### 示例 3: API 端点生成器
```yaml
---
name: api-endpoint-generator
description: 生成带有测试和文档的 REST API 端点。在创建新 API 路由、REST 端点、或用户提到"生成 API"、"新建端点"时使用。
---
# API 端点生成器
自动生成完整的 REST API 端点，包括处理程序、测试和文档。
## 使用说明
1. 向用户收集端点信息：
- HTTP 方法 (GET、POST、PUT、DELETE 等)
- 路径 (如 /api/users/:id)
- 请求/响应格式
- 认证需求
- 业务逻辑
2. 根据项目架构查找现有端点模式
3. 使用 `templates/endpoint.ts` 生成端点处理程序
4. 使用 `templates/endpoint.test.ts` 生成测试文件
5. 更新 API 路由配置
6. 更新 API 文档 (README 或 OpenAPI)
7. 参考 `examples.md` 了解常见模式
## 支持文件
- `templates/endpoint.ts`: 端点处理程序模板
- `templates/endpoint.test.ts`: 测试文件模板
- `examples.md`: 常见 API 模式和示例
- `reference.md`: API 设计最佳实践
## 示例
用户: "创建一个获取用户信息的 API"
→ 收集详细信息，生成 GET /api/users/:id 端点及测试
用户: "我需要一个用户注册端点"
→ 生成 POST /api/auth/register 端点，包括验证和测试
```
## 常见用例
- **工作流自动化**: 自动化重复性开发任务 (如测试后提交、构建后部署)
- **代码生成**: 使用特定模式生成样板代码 (如 API 端点、React 组件)
- **质量检查**: 在操作前强制执行代码质量标准 (如 lint、测试覆盖率)
- **项目特定任务**: 处理独特的项目需求 (如数据库迁移、配置同步)
- **工具编排**: 按特定顺序协调多个工具 (如构建、测试、部署流程)
- **只读分析**: 限制为只读工具进行安全的代码审查
## 常见问题排查
### 技能未被激活
- **问题**: Claude 没有自动使用技能
- **解决方案**:
- 改进 description 使其更具体
- 添加更多触发关键词
- 测试时使用与 description 匹配的措辞
### 技能未加载
- **问题**: 技能文件存在但不可用
- **解决方案**:
- 检查 YAML frontmatter 语法是否正确
- 验证文件路径：
- 个人技能：`~/.claude/skills/name/SKILL.md`
- 项目技能：`.claude/skills/name/SKILL.md`
- 确认 name 字段仅包含小写字母、数字和连字符
### 工具限制问题
- **问题**: 技能需要更多工具
- **解决方案**:
- 不使用 `allowed-tools` 字段 (默认允许所有工具)
- 或在 `allowed-tools` 列表中添加需要的工具
### 依赖问题
- **问题**: 技能依赖的工具或脚本不可用
- **解决方案**:
- 确保依赖已在用户环境中安装
- 在技能文档中说明依赖要求
- 添加依赖检查步骤
## 分享策略
### 团队共享 (推荐)
将项目技能提交到 git 仓库，团队成员拉取更新后自动获得：
```bash
git add .claude/skills/your-skill/
git commit -m "Add your-skill"
git push
```
### 插件分发
通过插件市场分发技能，实现更广泛的共享。
### 个人使用
个人技能存放在 `~/.claude/skills/`，仅在本地可用。
## 参考资料
- [Claude Code 技能文档](https://code.claude.com/docs/en/skills.md) - 官方技能创建指南
- [Claude Code 文档地图](https://code.claude.com/docs/en/claude_code_docs_map.md) - 完整文档索引
- [Claude Code 插件系统](https://code.claude.com/docs/en/plugins.md) - 学习如何创建可分发的插件