Github Skill Forge

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）必须：

1. 读取上下文包：查看 context_bundle.md

   • 这个文件包含文件树、README 和依赖项
   • 不需要手动搜索文件
   • 建议限制读取前 500 行开始

2. 更新 SKILL.md：重写新技能目录中的草稿

   • 描述：总结工具的功能
   • 先决条件：列出安装命令（如 pip install -r src/requirements.txt）
   • 用法：提供使用 src/... 运行工具的清晰示例

3. 创建包装脚本（可选）：

   • 如果工具需要复杂参数，在 .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 操作：

1. 运行锻造脚本

   python3 .trae/skills/github-skill-forge/scripts/forge.py https://github.com/sqlmapproject/sqlmap
   

2. Agent 读取上下文包

   read .trae/skills/sqlmap/context_bundle.md
   

3. Agent 编辑 SKILL.md

   edit .trae/skills/sqlmap/SKILL.md
   

4. 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 操作：

1. 运行锻造脚本
2. 读取 context_bundle.md 了解 seaborn 的 API
3. 识别依赖项（numpy, pandas, matplotlib）
4. 编写简化的使用脚本到 scripts/ 目录
5. 更新 SKILL.md 添加使用示例

示例 4：CLI 工具安装

用户："我想用 fzf 这样的模糊查找工具：https://github.com/junegunn/fzf"

Agent 操作：

1. 运行锻造脚本

2. 分析 fzf 的功能：

   • 读取 context_bundle.md 了解核心功能
   • 识别依赖（Go 环境）
   • 了解安装方式（多平台支持）

3. 创建简化的使用脚本：

   • scripts/fuzzy-search.py - 简化文件搜索
   • scripts/history-search.py - 命令历史搜索

4. 更新 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 操作：

1. 运行锻造脚本

2. 读取 context_bundle.md

3. 创建简化的包装脚本：

   • scripts/json-format.py - JSON 格式化
   • scripts/json-query.py - JSON 查询工具

4. 更新 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.

解决方案：

1. 检查 URL 是否正确
2. 确保网络连接正常
3. 尝试使用代理模式（脚本自动处理）
4. 验证 Git 认证（如果需要）

   git config --global credential.helper store
   

问题 2：目录已存在

症状：

⚠️  Warning: Skill directory 'xxx' already exists.
❌ Aborting: Directory exists.

解决方案：

1. 使用不同的技能名称

   python3 forge.py <URL> new_skill_name
   

2. 或手动删除已存在的目录后重试

   rm -rf .trae/skills/xxx
   

问题 3：依赖项缺失

症状：

ModuleNotFoundError: No module named 'xxx'

解决方案：

1. 在 SKILL.md 中明确列出依赖项
2. 提供安装命令
3. 创建 requirements.txt（如果原项目没有）
4. 检查 Python 版本兼容性

问题 4：上下文包过大

症状： 生成的 context_bundle.md 超过预期大小

解决方案： 脚本已自动截断超过 10KB 的文档，如需更详细的上下文可手动查看源文件。

问题 5：权限错误

症状：

Permission denied: '.trae/skills/xxx'

解决方案：

1. 检查目录权限

   ls -la .trae/skills/
   

2. 修复权限

   chmod -R 755 .trae/skills/
   

问题 6：Git LFS 文件

症状：

Git LFS: (1 of 1 files) 0 B / 100.00 MB

解决方案：

1. 安装 Git LFS

   git lfs install
   

2. 手动拉取 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>

相关资源

• fzf - 命令行模糊查找器
• awesome-cli-apps - CLI 应用精选
• GitHub CLI 官方文档

注意事项

• 脚本会删除克隆仓库中的 .git 文件夹以减小体积
• 代理模式使用 gitclone.com 作为代理服务
• 建议在运行前确认 URL 的正确性
• 大型仓库可能需要较长时间克隆
• 建议定期更新 github-skill-forge 本身
• 在生产环境使用前先进行测试