claudeskill/README.md

# Claude Skill Creator

专门用于创建和管理 Claude Skills 的项目。

## 项目概述

这个项目提供了一个完整的开发和测试环境，用于创建 Claude Code Skills。Skills 是模块化的、自包含的包，通过提供专门的知识、工作流程和工具来扩展 Claude 的能力。

## 项目结构

```
claudeskill/
├── .claude/                 # Claude 配置目录（已安装的 Skills）
│   └── skills/              # Skills 创建器引用
│       ├── skill-creator/   # Skill 创建指南和工具
│       ├── excel-to-markdown/   # Excel 转 Markdown Skill
│       ├── excel-report-converter/  # Excel 报表转换 Skill
│       └── minio-upload/    # MinIO 文件上传 Skill
├── demo_scripts/            # 演示脚本目录
│   └── excel_to_markdown.py # Excel 转 Markdown 转换器
├── skills/                  # 开发中的 Skills（用于测试和版本控制）
│   ├── excel-to-markdown/   # Excel 转 Markdown Skill
│   ├── excel-report-converter/  # Excel 报表转换 Skill
│   └── minio-upload/        # MinIO 文件上传 Skill
├── temp/                    # 临时文件目录
├── .venv/                   # Python 虚拟环境
├── CLAUDE.md                # Claude Code 项目指南
└── README.md                # 本文档
```

**说明：**
- `.claude/skills/` - 已安装的 Skills，由 Claude Code 自动加载（被 gitignore）
- `skills/` - Skills 的开发版本，用于版本控制和协作
- `demo_scripts/` - 可独立运行的脚本文件

## 目录说明

### `demo_scripts/`
存放可独立使用的脚本文件，这些脚本可以被 Skills 引用。

**当前脚本：**
- `excel_to_markdown.py` - 将 Excel 文件转换为 Markdown 表格格式

### `skills/`
存放已创建的 Skills，每个 Skill 都是一个独立的功能模块。

**当前 Skills：**

#### excel-to-markdown
将 Excel (.xlsx, .xls) 文件转换为 Markdown 表格格式的 Skill。

**功能：**
- 自动检测数据范围
- 支持指定行/列范围
- 显示行号和列号
- 处理单元格特殊字符
- 支持部分数据提取

**使用场景：**
- 转换 Excel 文档为 Markdown 用于展示或文档
- 提取和分析 Excel 数据
- 生成带行/列编号的 Markdown 表格
- 处理大型电子表格的部分转换

#### excel-report-converter
生成 Python 脚本将报表格式的 Excel 文件转换为数据库记录格式的 Skill。

**功能：**
- 自动分析 Excel 报表结构（表头、明细、表尾）
- 识别多个垂直排列的相同格式报表
- 生成专用的转换脚本
- 将层级报表数据转换为扁平的数据库记录

**使用场景：**
- 将包含多个报表的 Excel 文件转换为数据库表格式
- 分析报表格式的 Excel 文档结构
- 创建自定义的 Excel 报表转换脚本
- 将层级报表数据（表头 + 明细行 + 表尾）转换为规范化数据库记录

#### minio-upload
上传文件到 MinIO obsidian 桶的 Skill，支持灵活的路径配置。

**功能：**
- 上传任意文件到 MinIO 的 obsidian 桶
- 支持自定义子路径（如 `notes/2024`, `archive/projects`）
- 默认上传到 `main` 路径
- 自动处理路径规范化和文件名附加
- 完善的错误处理和验证

**使用场景：**
- 快速上传 Markdown 文档到云存储
- 按年份/分类组织文件
- 备份文件到 MinIO
- 批量上传文件到指定路径

**示例：**
```bash
# 上传到默认 main 路径
.claude/skills/minio-upload/scripts/upload_to_obsidian.sh file.md

# 上传到自定义子路径
.claude/skills/minio-upload/scripts/upload_to_obsidian.sh file.md "notes/2024"
```

## 工作流程

### 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 demo_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 demo_scripts/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 的使用条款。