github-skill-forge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub 技能锻造厂

GitHub Skill Forge

一个"制造技能的技能"。这个工具自动化了将 GitHub 仓库转换为标准化 Trae 技能的过程。

A 'skill for creating skills'. This tool automates the process of converting GitHub repositories into standardized Trae skills.

核心功能

Core Features

1. 自动化脚手架

1. Automated Scaffolding

一键克隆 GitHub 仓库
自动创建标准技能目录结构
自动生成上下文聚合文件

One-click GitHub repository cloning
Automatically creates standard skill directory structure
Automatically generates context aggregation files

2. Lite-RAG 上下文聚合

2. Lite-RAG Context Aggregation

自动提取项目文件树结构
自动解析 README 和文档
自动收集依赖项信息（requirements.txt, package.json, pyproject.toml）
生成单一上下文文件供 Agent 快速理解

Automatically extracts project file tree structure
Automatically parses README and documentation
Automatically collects dependency information (requirements.txt, package.json, pyproject.toml)
Generates a single context file for quick Agent understanding

3. 智能错误处理

3. Intelligent Error Handling

代理模式自动切换
目录存在性检测
Git 克隆失败自动重试

Automatic proxy mode switching
Directory existence detection
Automatic retry on Git clone failure

4. 标准化输出

4. Standardized Output

自动生成符合规范的技能结构
统一的目录布局（scripts/, references/, context_bundle.md）
预置 SKILL.md 模板

Automatically generates compliant skill structure
Unified directory layout (scripts/, references/, context_bundle.md)
Pre-configured SKILL.md template

快速开始

Quick Start

安装要求

Installation Requirements

bash

undefined

bash

undefined

基础依赖

Basic dependencies

Python 3.7+ Git

undefined

Python 3.7+ Git

undefined

基本使用

Basic Usage

bash

undefined

bash

undefined

语法: python scripts/forge.py <URL> [SKILL_NAME]

Syntax: python scripts/forge.py <URL> [SKILL_NAME]

python3 .trae/skills/github-skill-forge/scripts/forge.py "https://github.com/username/repo"

undefined

python3 .trae/skills/github-skill-forge/scripts/forge.py "https://github.com/username/repo"

undefined

使用场景

Use Cases

当你想使用在 GitHub 上找到的工具时
当用户发送 GitHub 链接并说"我想用这个"时
需要"安装"新功能到
```
.trae/skills
```
库时
需要快速集成开源工具到工作流时
需要标准化团队工具使用规范时

When you want to use a tool found on GitHub
When a user sends a GitHub link and says "I want to use this"
When you need to "install" new features into the
```
.trae/skills
```
library
When you need to quickly integrate open-source tools into workflows
When you need to standardize team tool usage specifications

工作流程

Workflow

步骤 1：锻造框架

Step 1: Forge Framework

运行脚手架脚本来克隆仓库、创建结构并生成上下文包。

bash

undefined

Run the scaffolding script to clone the repository, create the structure, and generate the context bundle.

bash

undefined

基础用法

Basic usage

python3 .trae/skills/github-skill-forge/scripts/forge.py "https://github.com/username/repo"

指定技能名称

Specify skill name

python3 .trae/skills/github-skill-forge/scripts/forge.py "https://github.com/username/repo" "my-custom-skill"

undefined

python3 .trae/skills/github-skill-forge/scripts/forge.py "https://github.com/username/repo" "my-custom-skill"

undefined

步骤 2：分析与定稿（AI 任务）

Step 2: Analysis and Finalization (AI Task)

脚本会在新的技能文件夹中生成

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 脚本

The script will generate

context_bundle.md

in the new skill folder. You (as an Agent) must:

Read Context Bundle: View
```
context_bundle.md
```
- This file contains the file tree, README, and dependencies
- No need to manually search for files
- It is recommended to limit reading to the first 500 lines
Update SKILL.md: Rewrite the draft in the new skill directory
- Description: Summarize the tool's functionality
- Prerequisites: List installation commands (e.g.,
```
pip install -r src/requirements.txt
```
  )
- Usage: Provide clear examples of running the tool using
```
src/...
```
Create Wrapper Scripts (Optional):
- If the tool requires complex parameters, write simplified Python/Shell scripts in
```
.trae/skills/<new_skill>/scripts/
```

步骤 3：验证

Step 3: Verification

运行工具的帮助命令以确保其正常工作。

bash

python3 .trae/skills/<new_skill>/src/<main_script>.py --help

Run the tool's help command to ensure it works properly.

bash

python3 .trae/skills/<new_skill>/src/<main_script>.py --help

使用示例

Usage Examples

示例 1：基础使用

Example 1: Basic Usage

用户："安装这个仓库：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

User: "Install this repository: https://github.com/sqlmapproject/sqlmap"

Agent Actions:

Run the forge script

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

Agent reads the context bundle

read .trae/skills/sqlmap/context_bundle.md

Agent edits SKILL.md
```
edit .trae/skills/sqlmap/SKILL.md
```

Agent runs verification

python3 .trae/skills/sqlmap/src/sqlmap.py --help

示例 2：指定技能名称

Example 2: Specify Skill Name

bash

python3 .trae/skills/github-skill-forge/scripts/forge.py "https://github.com/requests/requests" "http-requests-lib"

这将创建一个名为

http-requests-lib

的技能目录。

bash

python3 .trae/skills/github-skill-forge/scripts/forge.py "https://github.com/requests/requests" "http-requests-lib"

This will create a skill directory named

http-requests-lib

示例 3：复杂项目

Example 3: Complex Project

用户："我想用这个工具做数据可视化：https://github.com/mwaskom/seaborn"

Agent 操作：

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

User: "I want to use this tool for data visualization: https://github.com/mwaskom/seaborn"

Agent Actions:

Run the forge script
Read
```
context_bundle.md
```
to understand seaborn's API
Identify dependencies (numpy, pandas, matplotlib)
Write simplified usage scripts to the
```
scripts/
```
directory
Update SKILL.md with usage examples

示例 4：CLI 工具安装

Example 4: CLI Tool Installation

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

Agent 操作：

运行锻造脚本
分析 fzf 的功能：
- 读取 context_bundle.md 了解核心功能
- 识别依赖（Go 环境）
- 了解安装方式（多平台支持）
创建简化的使用脚本：
- ```
scripts/fuzzy-search.py
```
  - 简化文件搜索
- ```
scripts/history-search.py
```
  - 命令历史搜索

更新 SKILL.md：

markdown

## 使用方法

### 基本文件搜索
```bash
python3 scripts/fuzzy-search.py

命令历史搜索

bash

python3 scripts/history-search.py

依赖项

Go 1.22+（从源码编译）
或使用预编译二进制文件

安装命令

bash

# macOS
brew install fzf

# Linux
sudo apt install fzf

# Windows
choco install fzf

undefined

User: "I want to use a fuzzy search tool like fzf: https://github.com/junegunn/fzf"

Agent Actions:

Run the forge script
Analyze fzf's functionality:
- Read context_bundle.md to understand core features
- Identify dependencies (Go environment)
- Understand installation methods (multi-platform support)
Create simplified usage scripts:
- ```
scripts/fuzzy-search.py
```
  - Simplified file search
- ```
scripts/history-search.py
```
  - Command history search

Update SKILL.md:

markdown

## Usage

### Basic File Search
```bash
python3 scripts/fuzzy-search.py

Command History Search

bash

python3 scripts/history-search.py

Dependencies

Go 1.22+ (compile from source)
Or use precompiled binaries

Installation Commands

bash

# macOS
brew install fzf

# Linux
sudo apt install fzf

# Windows
choco install fzf

undefined

示例 5：数据处理工具

Example 5: Data Processing Tool

用户："安装 jq 这样的 JSON 处理工具：https://github.com/jqlang/jq"

Agent 操作：

运行锻造脚本
读取 context_bundle.md
创建简化的包装脚本：
- ```
scripts/json-format.py
```
  - JSON 格式化
- ```
scripts/json-query.py
```
  - JSON 查询工具

更新 SKILL.md：

markdown

## 使用示例

### 格式化 JSON
```bash
cat data.json | python3 scripts/json-format.py

查询 JSON 路径

bash

python3 scripts/json-query.py "data.json" ".users[0].name"

undefined

User: "Install a JSON processing tool like jq: https://github.com/jqlang/jq"

Agent Actions:

Run the forge script
Read context_bundle.md
Create simplified wrapper scripts:
- ```
scripts/json-format.py
```
  - JSON formatting
- ```
scripts/json-query.py
```
  - JSON query tool

Update SKILL.md:

markdown

## Usage Examples

### Format JSON
```bash
cat data.json | python3 scripts/json-format.py

Query JSON Path

bash

python3 scripts/json-query.py "data.json" ".users[0].name"

undefined

高级用法

Advanced Usage

手动创建上下文包

Manually Create Context Bundle

如果需要重新生成上下文包：

python

from forge import create_context_bundle
create_context_bundle("./src", "./context_bundle.md")

If you need to regenerate the context bundle:

python

from forge import create_context_bundle
create_context_bundle("./src", "./context_bundle.md")

自定义文件树限制

Custom File Tree Limits

修改

forge.py

中的

limit

参数：

python

def get_file_tree(start_path, limit=100):  # 增加限制到 100 个文件
    ...

Modify the

limit

parameter in

forge.py

python

def get_file_tree(start_path, limit=100):  # Increase limit to 100 files
    ...

批量安装多个技能

Batch Install Multiple Skills

bash

undefined

bash

undefined

创建一个批量安装脚本

Create a batch installation script

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

undefined

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

undefined

自定义模板

Custom Templates

你可以通过环境变量定制生成的内容：

bash

undefined

You can customize generated content via environment variables:

bash

undefined

自定义默认技能名

Custom default skill name

export SKILL_FORCE_NAME="custom-skill"

自定义文件限制

Custom file limit

export SKILL_FILE_LIMIT=100

自定义文档截断大小

Custom document truncation size

export SKILL_DOC_TRUNCATE=20000

undefined

export SKILL_DOC_TRUNCATE=20000

undefined

故障排除

Troubleshooting

问题 1：克隆失败

Issue 1: Clone Failure

症状：

❌ Git clone failed: fatal: Could not read from remote repository.

解决方案：

检查 URL 是否正确
确保网络连接正常
尝试使用代理模式（脚本自动处理）

验证 Git 认证（如果需要）

bash

git config --global credential.helper store

Symptoms:

❌ Git clone failed: fatal: Could not read from remote repository.

Solutions:

Check if the URL is correct
Ensure network connectivity is normal
Try using proxy mode (handled automatically by the script)

Verify Git authentication (if required)

bash

git config --global credential.helper store

问题 2：目录已存在

Issue 2: Directory Already Exists

症状：

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

解决方案：

使用不同的技能名称
bash
```
python3 forge.py <URL> new_skill_name
```
或手动删除已存在的目录后重试
bash
```
rm -rf .trae/skills/xxx
```

Symptoms:

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

Solutions:

Use a different skill name
bash
```
python3 forge.py <URL> new_skill_name
```
Or manually delete the existing directory and retry
bash
```
rm -rf .trae/skills/xxx
```

问题 3：依赖项缺失

Issue 3: Missing Dependencies

症状：

ModuleNotFoundError: No module named 'xxx'

解决方案：

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

Symptoms:

ModuleNotFoundError: No module named 'xxx'

Solutions:

Clearly list dependencies in SKILL.md
Provide installation commands
Create requirements.txt (if not present in the original project)
Check Python version compatibility

问题 4：上下文包过大

Issue 4: Oversized Context Bundle

症状：生成的

context_bundle.md

超过预期大小

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

Symptoms: The generated

context_bundle.md

is larger than expected

Solutions: The script automatically truncates documents exceeding 10KB. For more detailed context, manually view the source files.

问题 5：权限错误

Issue 5: Permission Error

症状：

Permission denied: '.trae/skills/xxx'

解决方案：

检查目录权限
bash
```
ls -la .trae/skills/
```
修复权限
bash
```
chmod -R 755 .trae/skills/
```

Symptoms:

Permission denied: '.trae/skills/xxx'

Solutions:

Check directory permissions
bash
```
ls -la .trae/skills/
```
Fix permissions
bash
```
chmod -R 755 .trae/skills/
```

问题 6：Git LFS 文件

Issue 6: Git LFS Files

症状：

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

解决方案：

安装 Git LFS
bash
```
git lfs install
```
手动拉取 LFS 文件
bash
```
git lfs pull
```

Symptoms:

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

Solutions:

Install Git LFS
bash
```
git lfs install
```
Manually pull LFS files
bash
```
git lfs pull
```

最佳实践

Best Practices

1. 技能命名规范

1. Skill Naming Conventions

使用小写字母和连字符
长度控制在 3-50 个字符
避免使用保留字

Use lowercase letters and hyphens
Keep length between 3-50 characters
Avoid reserved words

2. SKILL.md 编写规范

2. SKILL.md Writing Guidelines

保持简洁，只包含必要信息
详细内容放在
```
context_bundle.md
```
使用中文标题，英文命令
提供可执行的示例代码

Keep it concise, only include necessary information
Place detailed content in
```
context_bundle.md
```
Use Chinese titles and English commands
Provide executable example code

3. 包装脚本创建

3. Wrapper Script Creation

简化复杂命令行接口
提供默认参数
添加错误处理
支持
```
-h/--help
```
参数

Simplify complex command-line interfaces
Provide default parameters
Add error handling
Support
```
-h/--help
```
parameters

4. 依赖项管理

4. Dependency Management

明确列出所有依赖
指定版本范围
提供多平台安装方式

Clearly list all dependencies
Specify version ranges
Provide multi-platform installation methods

5. 验证测试

5. Verification Testing

在发布前运行所有示例
测试不同操作系统
验证依赖安装正确性

Run all examples before release
Test on different operating systems
Verify dependency installation correctness

技能结构规范

Skill Structure Specifications

标准目录结构

Standard Directory Structure

.trae/skills/
└── <skill-name>/
    ├── SKILL.md           # 技能说明文档
    ├── context_bundle.md  # 上下文聚合（自动生成）
    ├── requirements.txt   # 依赖项（可选）
    ├── src/              # 源代码
    │   └── <main-script>
    ├── scripts/          # 包装脚本（可选）
    │   └── <helper-scripts>
    └── references/       # 参考文档（可选）
        └── <documentation>

.trae/skills/
└── <skill-name>/
    ├── SKILL.md           # Skill documentation
    ├── context_bundle.md  # Context aggregation (auto-generated)
    ├── requirements.txt   # Dependencies (optional)
    ├── src/              # Source code
    │   └── <main-script>
    ├── scripts/          # Wrapper scripts (optional)
    │   └── <helper-scripts>
    └── references/       # Reference documents (optional)
        └── <documentation>

SKILL.md 模板

SKILL.md Template

markdown

---
name: <skill-name>
description: <简短描述>
---

markdown

---
name: <skill-name>
description: <brief description>
---

<技能名称>

<Skill Name>

功能特性

Features

<特性1>
<特性2>

<Feature 1>
<Feature 2>

使用要求

Requirements

<依赖项1>
<依赖项2>

<Dependency 1>
<Dependency 2>

安装方法

Installation

bash

<安装命令>

bash

<installation command>

使用方法

Usage

基本用法

Basic Usage

bash

<基本命令>

bash

<basic command>

高级用法

Advanced Usage

<高级功能>

<Advanced Feature>

bash

<高级命令>

bash

<advanced command>

故障排除

Troubleshooting

问题

Issue

<解决方案>

更新日志

Changelog

<版本>：<更新内容>

undefined

<Version>: <Update Content>

undefined

性能优化

Performance Optimization

1. 减少克隆深度

1. Reduce Clone Depth

bash

undefined

bash

undefined

使用浅克隆

Use shallow clone

git clone --depth 1 <url>

undefined

git clone --depth 1 <url>

undefined

2. 跳过不必要的文件

2. Skip Unnecessary Files

python

undefined

python

undefined

在 forge.py 中添加

Add in forge.py

SKIP_DIRS = ['.git', '.github', 'docs', 'test'] SKIP_FILES = ['.md', '.txt']

undefined

SKIP_DIRS = ['.git', '.github', 'docs', 'test'] SKIP_FILES = ['.md', '.txt']

undefined

3. 并行处理

3. Parallel Processing

python

undefined

python

undefined

使用多线程处理多个任务

Use multi-threading for multiple tasks

import concurrent.futures

with concurrent.futures.ThreadPoolExecutor() as executor: executor.submit(process_file, file1) executor.submit(process_file, file2)

undefined

import concurrent.futures

with concurrent.futures.ThreadPoolExecutor() as executor: executor.submit(process_file, file1) executor.submit(process_file, file2)

undefined

安全性考虑

Security Considerations

1. 验证仓库来源

1. Verify Repository Source

检查仓库的 stars 和 forks 数量
查看最近的提交记录
检查维护者的活跃度

Check the number of stars and forks of the repository
View recent commit records
Check maintainer activity

2. 依赖项安全

2. Dependency Security

检查已知漏洞
使用依赖扫描工具
定期更新依赖

Check for known vulnerabilities
Use dependency scanning tools
Update dependencies regularly

3. 代码执行安全

3. Code Execution Security

在隔离环境中测试
限制文件系统访问
记录所有操作日志

Test in an isolated environment
Restrict file system access
Log all operations

集成建议

Integration Recommendations

1. CI/CD 集成

1. CI/CD Integration

yaml

undefined

yaml

undefined

.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

undefined

undefined

2. 自动化更新

2. Automated Updates

bash

undefined

bash

undefined

定期更新技能脚本

Regularly update skill scripts

0 0 * * 0 cd /path/to/skills && python3 github-skill-forge/scripts/forge.py <url>

undefined

0 0 * * 0 cd /path/to/skills && python3 github-skill-forge/scripts/forge.py <url>

undefined

Related Resources

注意事项

Notes

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

The script will delete the
```
.git
```
folder in the cloned repository to reduce size
Proxy mode uses gitclone.com as the proxy service
It is recommended to confirm the correctness of the URL before running
Large repositories may take longer to clone
It is recommended to update github-skill-forge itself regularly
Test before using in a production environment