claudeskill/README.md

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