From 85f788a8ff522c11c2c2a9d73aa523823d3ceeda Mon Sep 17 00:00:00 2001 From: Misaka Company Date: Tue, 27 Jan 2026 13:02:40 +0800 Subject: [PATCH] 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 --- README.md | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..38b600b --- /dev/null +++ b/README.md @@ -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 --path skills +``` + +这会创建： +- `skills//SKILL.md` - Skill 文档模板 +- `skills//scripts/` - 脚本目录 +- `skills//references/` - 参考文档目录 +- `skills//assets/` - 资源文件目录 + +### 2. 开发 Skill + +1. 将相关脚本复制到 `skills//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` 文件（实际上是 zip 格式），包含所有 Skill 文件。 + +### 5. 提交代码 + +```bash +git add . +git commit -m "Add new skill: " +``` + +## 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 的使用条款。