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：

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

在开发过程中测试脚本功能：

# 测试 Excel 转 Markdown
python3 scripts/excel_to_markdown.py demo.xlsx -o demo.md --show-rows --show-cols

4. 打包 Skill(当用户主动要求才打包)

使用 skill-creator 工具打包 Skill：

python3 .claude/skills/skill-creator/scripts/package_skill.py skills/<skill-name>

这会创建一个 .skill 文件（实际上是 zip 格式），包含所有 Skill 文件。

5. 提交代码

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 处理）

安装依赖

source .venv/bin/activate
pip install openpyxl

示例：创建 Excel 转 Markdown Skill

步骤 1：初始化 Skill

python3 .claude/skills/skill-creator/scripts/init_skill.py excel-to-markdown --path skills

步骤 2：添加脚本

cp excel_to_markdown.py skills/excel-to-markdown/scripts/

步骤 3：编写 SKILL.md

编辑 skills/excel-to-markdown/SKILL.md，添加：

• 触发条件和使用场景
• 快速开始指南
• 命令行选项说明
• 常见用例示例

步骤 4：测试功能

python3 skills/excel-to-markdown/scripts/excel_to_markdown.py demo.xlsx -o output.md

步骤 5：打包 Skill

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