skill-factory

Skill Factory

Convert any GitHub repository into a standardized Claude Skill with one click.

Core Features

Information Retrieval: via git ls-remote to get the commit hash, and via HTTP to get the README
Directory Generation: create a standardized Skill directory structure (SKILL.md, scripts/, references/, assets/)
Metadata Injection: automatically populate extended metadata fields (source_url, source_hash, version, etc.)
Placeholder Script: generate a wrapper.py template for later implementation

Use Cases

Trigger Methods:

/skill-factory <github_url>
"Package this repository into a Skill: "
"Create a Skill from GitHub: "
"Wrap this tool: "

Workflow

Step 1: Fetch Repository Information

Run scripts/fetch_github_info.py to get repository metadata:

python scripts/fetch_github_info.py <github_url>

Output in JSON format:

{
  "name": "repo-name",
  "owner": "owner",
  "url": "https://github.com/owner/repo",
  "latest_hash": "abc123...",
  "default_branch": "main",
  "description": "仓库描述",
  "readme": "README 内容..."
}

Step 2: Analyze the README

The Agent analyzes the README content to understand:

The tool's main functionality
Installation and usage methods
CLI parameters or API interfaces
Dependency requirements

Step 3: Create the Skill Directory

Run scripts/create_skill.py to generate the directory structure:

python scripts/create_skill.py <json_file_or_string> <output_dir>

Generated directory structure:

skill-name/
├── SKILL.md              # 主 Skill 文件（含扩展元数据）
├── scripts/
│   └── wrapper.py        # 占位脚本
├── references/
│   └── .gitkeep
└── assets/
    └── .gitkeep

Step 4: Refine the Skill

The Agent, based on the README analysis results:

Refines the description and usage instructions in SKILL.md
Implements the actual logic of wrapper.py
Adds necessary reference documentation

Step 5: Validation

Confirm:

SKILL.md's frontmatter format is correct
source_hash is correctly recorded
description includes trigger conditions
wrapper.py is executable (if implemented)

Generated Metadata Format

Every Skill created by skill-factory must include the following extended metadata:

---
name: skill-name
description: 详细描述，包含触发条件

# 生命周期管理字段（必需）
source_url: https://github.com/owner/repo
source_hash: abc123def456...
version: 0.1.0
created_at: 2026-01-23
updated_at: 2026-01-23
evolution_enabled: true

# 可选字段
entry_point: scripts/wrapper.py
dependencies:
  - dependency1
  - dependency2
---

Script Description

Script	Function
`scripts/fetch_github_info.py`	Fetch GitHub repository metadata (lightweight, no clone required)
`scripts/create_skill.py`	Create a standardized Skill directory structure
`scripts/import_github_skill.py`	Full import a GitHub repository as a local Skill (supports parallel downloads)

import_github_skill.py (recommended)

Efficiently download all files from a GitHub repository and create a local Skill.

Features:

Use the GitHub API to get the directory structure (single request)
Download all files in parallel (10 threads)
Automatically switch to the git clone fallback when the API is rate-limited
Support custom Skill names
Support removing source information (--no-source）

Usage:

# 基本用法
python scripts/import_github_skill.py <github_url> <output_dir>

# 自定义名称
python scripts/import_github_skill.py <github_url> <output_dir> --name my-skill

# 不保留源信息（作为全新本地 Skill）
python scripts/import_github_skill.py <github_url> <output_dir> --no-source

# 组合使用
python scripts/import_github_skill.py https://github.com/user/repo ./skills --name my-skill --no-source

Example:

# 导入并重命名
python scripts/import_github_skill.py https://github.com/PenglongHuang/chinese-novelist-skill ./skills --name chinese-novelist --no-source

Best Practices

Progressive Disclosure: Do not cram the entire repository content into the Skill; include only the necessary wrapper code
Dependency Isolation: The generated Skill should explicitly declare its dependencies; using venv or uv for management is recommended
Idempotency: source_hash field allows skill-manager to check for updates later
Complete description: The description must include "what it does" and "when to use it"

Examples

Example 1: Wrapping yt-dlp

用户: /skill-factory https://github.com/yt-dlp/yt-dlp

Agent:
1. 运行 fetch_github_info.py 获取仓库信息
2. 分析 README，了解 yt-dlp 是视频下载工具
3. 运行 create_skill.py 创建目录
4. 完善 SKILL.md，添加常用命令示例
5. 实现 wrapper.py，封装下载功能

Example 2: Wrapping ffmpeg-python

用户: 把 https://github.com/kkroening/ffmpeg-python 打包成 Skill

Agent:
1. 获取仓库信息
2. 分析 README，了解这是 FFmpeg 的 Python 绑定
3. 创建 Skill 目录
4. 完善文档，添加常用转换示例
5. 实现 wrapper.py，封装常用操作

Collaboration with other Skills

skill-manager: Use source_url and source_hash to check for updates
skill-evolution: Use evolution_enabled to control whether user experience is recorded
skill-creator: Follow the same directory structure and metadata conventions