GitHub 技能锻造厂
一个"制造技能的技能"。这个工具自动化了将 GitHub 仓库转换为标准化 Trae 技能的过程。
核心功能
1. 自动化脚手架
- 一键克隆 GitHub 仓库
- 自动创建标准技能目录结构
- 自动生成上下文聚合文件
2. Lite-RAG 上下文聚合
- 自动提取项目文件树结构
- 自动解析 README 和文档
- 自动收集依赖项信息（requirements.txt, package.json, pyproject.toml）
- 生成单一上下文文件供 Agent 快速理解
3. 智能错误处理
- 代理模式自动切换
- 目录存在性检测
- Git 克隆失败自动重试
4. 标准化输出
- 自动生成符合规范的技能结构
- 统一的目录布局（scripts/, references/, context_bundle.md）
- 预置 SKILL.md 模板
快速开始
安装要求
# 基础依赖
Python 3.7+
Git
基本使用
# 语法: python scripts/forge.py <URL> [SKILL_NAME]
python3 .trae/skills/github-skill-forge/scripts/forge.py "https://github.com/username/repo"
使用场景
- 当你想使用在 GitHub 上找到的工具时
- 当用户发送 GitHub 链接并说"我想用这个"时
- 需要"安装"新功能到
.trae/skills 库时
- 需要快速集成开源工具到工作流时
- 需要标准化团队工具使用规范时
工作流程
步骤 1：锻造框架
运行脚手架脚本来克隆仓库、创建结构并生成上下文包。
# 基础用法
python3 .trae/skills/github-skill-forge/scripts/forge.py "https://github.com/username/repo"
# 指定技能名称
python3 .trae/skills/github-skill-forge/scripts/forge.py "https://github.com/username/repo" "my-custom-skill"
步骤 2：分析与定稿（AI 任务）
脚本会在新的技能文件夹中生成 context_bundle.md。你（作为 Agent）必须：
-
读取上下文包：查看 context_bundle.md
- 这个文件包含文件树、README 和依赖项
- 不需要手动搜索文件
- 建议限制读取前 500 行开始
-
更新 SKILL.md：重写新技能目录中的草稿
- 描述：总结工具的功能
- 先决条件：列出安装命令（如
pip install -r src/requirements.txt）
- 用法：提供使用
src/... 运行工具的清晰示例
-
创建包装脚本（可选）：
- 如果工具需要复杂参数，在
.trae/skills/<new_skill>/scripts/ 中编写简化的 Python/Shell 脚本
步骤 3：验证
运行工具的帮助命令以确保其正常工作。
python3 .trae/skills/<new_skill>/src/<main_script>.py --help
使用示例
示例 1：基础使用
用户："安装这个仓库：https://github.com/sqlmapproject/sqlmap"
Agent 操作：
- 运行锻造脚本
python3 .trae/skills/github-skill-forge/scripts/forge.py https://github.com/sqlmapproject/sqlmap
- Agent 读取上下文包
read .trae/skills/sqlmap/context_bundle.md
- Agent 编辑 SKILL.md
edit .trae/skills/sqlmap/SKILL.md
- Agent 运行验证
python3 .trae/skills/sqlmap/src/sqlmap.py --help
示例 2：指定技能名称
python3 .trae/skills/github-skill-forge/scripts/forge.py "https://github.com/requests/requests" "http-requests-lib"
这将创建一个名为 http-requests-lib 的技能目录。
示例 3：复杂项目
用户："我想用这个工具做数据可视化：https://github.com/mwaskom/seaborn"
Agent 操作：
- 运行锻造脚本
- 读取
context_bundle.md 了解 seaborn 的 API
- 识别依赖项（numpy, pandas, matplotlib）
- 编写简化的使用脚本到
scripts/ 目录
- 更新 SKILL.md 添加使用示例
示例 4：CLI 工具安装
用户："我想用 fzf 这样的模糊查找工具：https://github.com/junegunn/fzf"
Agent 操作：
-
运行锻造脚本
-
分析 fzf 的功能：
- 读取 context_bundle.md 了解核心功能
- 识别依赖（Go 环境）
- 了解安装方式（多平台支持）
-
创建简化的使用脚本：
scripts/fuzzy-search.py - 简化文件搜索scripts/history-search.py - 命令历史搜索
-
更新 SKILL.md：
## 使用方法
### 基本文件搜索
```bash
python3 scripts/fuzzy-search.py
命令历史搜索
python3 scripts/history-search.py
依赖项
- Go 1.22+（从源码编译）
- 或使用预编译二进制文件
安装命令
# macOS
brew install fzf
# Linux
sudo apt install fzf
# Windows
choco install fzf
示例 5：数据处理工具
用户："安装 jq 这样的 JSON 处理工具：https://github.com/jqlang/jq"
Agent 操作：
-
运行锻造脚本
-
读取 context_bundle.md
-
创建简化的包装脚本：
scripts/json-format.py - JSON 格式化scripts/json-query.py - JSON 查询工具
-
更新 SKILL.md：
## 使用示例
### 格式化 JSON
```bash
cat data.json | python3 scripts/json-format.py
查询 JSON 路径
python3 scripts/json-query.py "data.json" ".users[0].name"
高级用法
手动创建上下文包
如果需要重新生成上下文包：
from forge import create_context_bundle
create_context_bundle("./src", "./context_bundle.md")
自定义文件树限制
修改 forge.py 中的 limit 参数：
def get_file_tree(start_path, limit=100): # 增加限制到 100 个文件
...
批量安装多个技能
# 创建一个批量安装脚本
for url in "https://github.com/fzf" "https://github.com/jqlang/jq" "https://github.com/sharkdp/bat"; do
python3 .trae/skills/github-skill-forge/scripts/forge.py "$url"
done
自定义模板
你可以通过环境变量定制生成的内容：
# 自定义默认技能名
export SKILL_FORCE_NAME="custom-skill"
# 自定义文件限制
export SKILL_FILE_LIMIT=100
# 自定义文档截断大小
export SKILL_DOC_TRUNCATE=20000
故障排除
问题 1：克隆失败
症状：
❌ Git clone failed: fatal: Could not read from remote repository.
解决方案：
- 检查 URL 是否正确
- 确保网络连接正常
- 尝试使用代理模式（脚本自动处理）
- 验证 Git 认证（如果需要）
git config --global credential.helper store
问题 2：目录已存在
症状：
⚠️ Warning: Skill directory 'xxx' already exists.
❌ Aborting: Directory exists.
解决方案：
- 使用不同的技能名称
python3 forge.py <URL> new_skill_name
- 或手动删除已存在的目录后重试
rm -rf .trae/skills/xxx
问题 3：依赖项缺失
症状：
ModuleNotFoundError: No module named 'xxx'
解决方案：
- 在 SKILL.md 中明确列出依赖项
- 提供安装命令
- 创建 requirements.txt（如果原项目没有）
- 检查 Python 版本兼容性
问题 4：上下文包过大
症状：
生成的 context_bundle.md 超过预期大小
解决方案：
脚本已自动截断超过 10KB 的文档，如需更详细的上下文可手动查看源文件。
问题 5：权限错误
症状：
Permission denied: '.trae/skills/xxx'
解决方案：
- 检查目录权限
ls -la .trae/skills/
- 修复权限
chmod -R 755 .trae/skills/
问题 6：Git LFS 文件
症状：
Git LFS: (1 of 1 files) 0 B / 100.00 MB
解决方案：
- 安装 Git LFS
git lfs install
- 手动拉取 LFS 文件
git lfs pull
最佳实践
1. 技能命名规范
- 使用小写字母和连字符
- 长度控制在 3-50 个字符
- 避免使用保留字
2. SKILL.md 编写规范
- 保持简洁，只包含必要信息
- 详细内容放在
context_bundle.md
- 使用中文标题，英文命令
- 提供可执行的示例代码
3. 包装脚本创建
- 简化复杂命令行接口
- 提供默认参数
- 添加错误处理
- 支持
-h/--help 参数
4. 依赖项管理
- 明确列出所有依赖
- 指定版本范围
- 提供多平台安装方式
5. 验证测试
- 在发布前运行所有示例
- 测试不同操作系统
- 验证依赖安装正确性
技能结构规范
标准目录结构
.trae/skills/
└── <skill-name>/
├── SKILL.md # 技能说明文档
├── context_bundle.md # 上下文聚合（自动生成）
├── requirements.txt # 依赖项（可选）
├── src/ # 源代码
│ └── <main-script>
├── scripts/ # 包装脚本（可选）
│ └── <helper-scripts>
└── references/ # 参考文档（可选）
└── <documentation>
SKILL.md 模板
---
name: <skill-name>
description: <简短描述>
---
# <技能名称>
## 功能特性
- <特性1>
- <特性2>
## 使用要求
- <依赖项1>
- <依赖项2>
## 安装方法
```bash
<安装命令>
使用方法
基本用法
<基本命令>
高级用法
<高级功能>
<高级命令>
故障排除
问题
<解决方案>
更新日志
## 性能优化
### 1. 减少克隆深度
```bash
# 使用浅克隆
git clone --depth 1 <url>
2. 跳过不必要的文件
# 在 forge.py 中添加
SKIP_DIRS = ['.git', '.github', 'docs', 'test']
SKIP_FILES = ['*.md', '*.txt']
3. 并行处理
# 使用多线程处理多个任务
import concurrent.futures
with concurrent.futures.ThreadPoolExecutor() as executor:
executor.submit(process_file, file1)
executor.submit(process_file, file2)
安全性考虑
1. 验证仓库来源
- 检查仓库的 stars 和 forks 数量
- 查看最近的提交记录
- 检查维护者的活跃度
2. 依赖项安全
3. 代码执行安全
- 在隔离环境中测试
- 限制文件系统访问
- 记录所有操作日志
集成建议
1. CI/CD 集成
# .github/workflows/skill-test.yml
name: Test Skills
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install dependencies
run: pip install -r requirements.txt
- name: Test skill
run: python3 src/main.py --help
2. 自动化更新
# 定期更新技能脚本
0 0 * * 0 cd /path/to/skills && python3 github-skill-forge/scripts/forge.py <url>
相关资源
注意事项
- 脚本会删除克隆仓库中的
.git 文件夹以减小体积
- 代理模式使用 gitclone.com 作为代理服务
- 建议在运行前确认 URL 的正确性
- 大型仓库可能需要较长时间克隆
- 建议定期更新 github-skill-forge 本身
- 在生产环境使用前先进行测试
