Add project README documentation
Add comprehensive README.md documenting the project structure, workflow, and best practices for creating Claude Skills. Includes step-by-step guide for skill development, packaging, and testing. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Misaka Company
186
README.md
Normal file
186
README.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# Claude Skill Creator
|
||||
|
||||
专门用于创建和管理 Claude Skills 的项目。
|
||||
|
||||
## 项目概述
|
||||
|
||||
这个项目提供了一个完整的开发和测试环境，用于创建 Claude Code Skills。Skills 是模块化的、自包含的包，通过提供专门的知识、工作流程和工具来扩展 Claude 的能力。
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
claudeskill/
|
||||
├── .claude/ # Claude 配置目录
|
||||
│ └── skills/ # Skill 创建器引用
|
||||
│ └── skill-creator/ # Skill 创建指南和工具
|
||||
├── scripts/ # 独立脚本目录
|
||||
│ └── excel_to_markdown.py # Excel 转 Markdown 转换器
|
||||
├── skills/ # 创建的 Skills
|
||||
│ └── excel-to-markdown/ # Excel 转 Markdown Skill
|
||||
│ ├── SKILL.md # Skill 文档
|
||||
│ └── scripts/ # Skill 附带脚本
|
||||
├── .venv/ # Python 虚拟环境
|
||||
└── README.md # 本文档
|
||||
```
|
||||
|
||||
## 目录说明
|
||||
|
||||
### `scripts/`
|
||||
存放可独立使用的脚本文件，这些脚本可以被 Skills 引用。
|
||||
|
||||
**当前脚本：**
|
||||
- `excel_to_markdown.py` - 将 Excel 文件转换为 Markdown 表格格式
|
||||
|
||||
### `skills/`
|
||||
存放已创建的 Skills，每个 Skill 都是一个独立的功能模块。
|
||||
|
||||
**当前 Skills：**
|
||||
|
||||
#### excel-to-markdown
|
||||
将 Excel (.xlsx, .xls) 文件转换为 Markdown 表格格式的 Skill。
|
||||
|
||||
**功能：**
|
||||
- 自动检测数据范围
|
||||
- 支持指定行/列范围
|
||||
- 显示行号和列号
|
||||
- 处理单元格特殊字符
|
||||
- 支持部分数据提取
|
||||
|
||||
**使用场景：**
|
||||
- 转换 Excel 文档为 Markdown 用于展示或文档
|
||||
- 提取和分析 Excel 数据
|
||||
- 生成带行/列编号的 Markdown 表格
|
||||
- 处理大型电子表格的部分转换
|
||||
|
||||
## 工作流程
|
||||
|
||||
### 1. 创建新 Skill
|
||||
|
||||
使用 skill-creator 工具初始化新 Skill：
|
||||
|
||||
```bash
|
||||
python3 .claude/skills/skill-creator/scripts/init_skill.py <skill-name> --path skills
|
||||
```
|
||||
|
||||
这会创建：
|
||||
- `skills/<skill-name>/SKILL.md` - Skill 文档模板
|
||||
- `skills/<skill-name>/scripts/` - 脚本目录
|
||||
- `skills/<skill-name>/references/` - 参考文档目录
|
||||
- `skills/<skill-name>/assets/` - 资源文件目录
|
||||
|
||||
### 2. 开发 Skill
|
||||
|
||||
1. 将相关脚本复制到 `skills/<skill-name>/scripts/`
|
||||
2. 编辑 `SKILL.md` 文件，添加：
|
||||
- YAML frontmatter（name 和 description）
|
||||
- 使用说明
|
||||
- 示例代码
|
||||
- 触发条件
|
||||
|
||||
### 3. 测试 Skill
|
||||
|
||||
在开发过程中测试脚本功能：
|
||||
|
||||
```bash
|
||||
# 测试 Excel 转 Markdown
|
||||
python3 scripts/excel_to_markdown.py demo.xlsx -o demo.md --show-rows --show-cols
|
||||
```
|
||||
|
||||
### 4. 打包 Skill(当用户主动要求才打包)
|
||||
|
||||
使用 skill-creator 工具打包 Skill：
|
||||
|
||||
```bash
|
||||
python3 .claude/skills/skill-creator/scripts/package_skill.py skills/<skill-name>
|
||||
```
|
||||
|
||||
这会创建一个 `.skill` 文件（实际上是 zip 格式），包含所有 Skill 文件。
|
||||
|
||||
### 5. 提交代码
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Add new skill: <skill-name>"
|
||||
```
|
||||
|
||||
## Skill 创建最佳实践
|
||||
|
||||
### 1. 简洁优先
|
||||
- 默认假设 Claude 已经很聪明，只添加 Claude 不知道的信息
|
||||
- 挑战每个信息："Claude 真的需要这个解释吗？"
|
||||
- 优先使用简洁的示例而非冗长的解释
|
||||
|
||||
### 2. 适当的自由度
|
||||
- **高自由度**（基于文本的指令）：多种方法都有效时
|
||||
- **中等自由度**（伪代码或带参数的脚本）：存在首选模式时
|
||||
- **低自由度**（特定脚本，少参数）：操作脆弱且容易出错时
|
||||
|
||||
### 3. 渐进式披露
|
||||
- **Metadata**（name + description）- 始终在上下文中（~100 词）
|
||||
- **SKILL.md body** - 当 Skill 触发时（<5k 词）
|
||||
- **Bundled resources** - 按 Claude 需要
|
||||
|
||||
### 4. 组织资源
|
||||
- **scripts/** - 可执行代码（Python/Bash 等）
|
||||
- **references/** - 需要加载到上下文的文档
|
||||
- **assets/** - 输出中使用的文件（模板、图标等）
|
||||
|
||||
## 环境要求
|
||||
|
||||
- Python 3.10+
|
||||
- 虚拟环境：`.venv/`
|
||||
- 依赖包：`openpyxl`（用于 Excel 处理）
|
||||
|
||||
## 安装依赖
|
||||
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
pip install openpyxl
|
||||
```
|
||||
|
||||
## 示例：创建 Excel 转 Markdown Skill
|
||||
|
||||
### 步骤 1：初始化 Skill
|
||||
```bash
|
||||
python3 .claude/skills/skill-creator/scripts/init_skill.py excel-to-markdown --path skills
|
||||
```
|
||||
|
||||
### 步骤 2：添加脚本
|
||||
```bash
|
||||
cp excel_to_markdown.py skills/excel-to-markdown/scripts/
|
||||
```
|
||||
|
||||
### 步骤 3：编写 SKILL.md
|
||||
编辑 `skills/excel-to-markdown/SKILL.md`，添加：
|
||||
- 触发条件和使用场景
|
||||
- 快速开始指南
|
||||
- 命令行选项说明
|
||||
- 常见用例示例
|
||||
|
||||
### 步骤 4：测试功能
|
||||
```bash
|
||||
python3 skills/excel-to-markdown/scripts/excel_to_markdown.py demo.xlsx -o output.md
|
||||
```
|
||||
|
||||
### 步骤 5：打包 Skill
|
||||
```bash
|
||||
python3 .claude/skills/skill-creator/scripts/package_skill.py skills/excel-to-markdown
|
||||
```
|
||||
|
||||
## 参考资源
|
||||
|
||||
- Skill 创建指南：`.claude/skills/skill-creator/`
|
||||
- 工作流程参考：`.claude/skills/skill-creator/references/workflows.md`
|
||||
- 输出模式参考：`.claude/skills/skill-creator/references/output-patterns.md`
|
||||
|
||||
## 贡献指南
|
||||
|
||||
1. 在 `scripts/` 中开发新脚本
|
||||
2. 使用 skill-creator 工具创建对应的 Skill
|
||||
3. 充分测试功能
|
||||
4. 更新文档
|
||||
5. 提交到版本控制
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目用于创建和管理 Claude Skills，遵循 Claude Code 的使用条款。
|
||||
Reference in New Issue
Block a user