skill_flywheel

一套“可组合”的 AI Skills，用来把 Skill 的创建、更新检查、升级、经验沉淀与质量校验串成一个可重复执行的飞轮。

适合谁

• 你在维护一批基于 GitHub 的 skills（SKILL.md + scripts/），希望能自动检查是否有更新、升级后自动把经验合并回文档。
• 你想把一个 GitHub 仓库快速打包成一个可用的 skill，并纳入后续的生命周期管理。

项目包含的 Skills

Skill	作用
github-to-skills/	把 GitHub 仓库“打包”成 skill（生成结构 + 拉取 README/commit 信息）
skill-manager/	扫描 skills、检查是否落后于远程、列出/删除
skill-upgrader/	升级 GitHub 打包的 skills（更新 github_hash + 重新 stitch）
skill-evolution-manager/	合并 evolution.json 并把经验 stitch 回 SKILL.md
skill-validator/	校验 skills（frontmatter/脚本可编译/单测等）
skill-installer-local/	把本仓库内的 skills 安装/复制到本机的 skills 目录
skill_flywheel/	统一入口：把上述能力编排成一条可重复跑的“飞轮”

快速开始

1) 克隆

git clone https://github.com/AlataChan/skill_flywheel.git
cd skill_flywheel

2) 安装依赖

本仓库脚本使用 Python 标准库为主，建议至少安装：

python3 -m pip install pyyaml

如果你在 macOS（Homebrew Python）遇到 externally-managed-environment，建议使用虚拟环境：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install pyyaml

（可选）如果你要跑测试：

python3 -m pip install pytest

3) 直接在仓库内使用（推荐）

统一入口在 skill_flywheel/scripts/flywheel.py：

python3 skill_flywheel/scripts/flywheel.py list --format table
python3 skill_flywheel/scripts/flywheel.py create --url <github_url>
python3 skill_flywheel/scripts/flywheel.py check --format table
python3 skill_flywheel/scripts/flywheel.py validate --format table

4) 安装到本机 Skills 目录（可选）

你可以把这些 skill 复制到 Codex/Claude 的 skills 目录中：

# 预览（dry-run，不会写入）
python3 skill-installer-local/scripts/install.py --skills-root .

# 实际安装（会复制文件）
python3 skill-installer-local/scripts/install.py --skills-root . --yes --overwrite

安装目标目录的选择逻辑：

1. $CODEX_HOME/skills（如果设置了 CODEX_HOME）
2. ~/.codex/skills（默认）
3. ~/.claude/skills（如果存在）

常用命令（Flywheel）

以下都在仓库根目录执行：

# 拉取 GitHub 信息（可输出到文件）
python3 skill_flywheel/scripts/flywheel.py fetch --url <github_url>

# 从 GitHub 创建一个新 skill（默认输出到 skills_root，也就是本仓库根目录）
python3 skill_flywheel/scripts/flywheel.py create --url <github_url>

# 扫描并检查更新
python3 skill_flywheel/scripts/flywheel.py check --format table

# 升级某个 skill（需要 --yes 才会写入；可先加 --dry-run）
python3 skill_flywheel/scripts/flywheel.py upgrade --name <skill_name> --dry-run
python3 skill_flywheel/scripts/flywheel.py upgrade --name <skill_name> --yes

# 把经验 JSON 合并并 stitch 回 SKILL.md（支持 --stdin）
python3 skill_flywheel/scripts/flywheel.py evolve --name <skill_name> --json-file <path/to/evolution.json>

# 批量重新 stitch（对所有存在 evolution.json 的 skill）
python3 skill_flywheel/scripts/flywheel.py align

# 校验（可用 --no-tests 跳过测试）
python3 skill_flywheel/scripts/flywheel.py validate --format table

# 一键跑“飞轮”（会升级，因此必须加 --yes）
python3 skill_flywheel/scripts/flywheel.py cycle --yes

开发与测试

python3 -m compileall -q .
python3 -m pytest -q

注：运行测试需要安装依赖（至少 pyyaml、pytest）。

致谢

感谢 Khazix-Skills 原项目的贡献与启发，为本项目提供了重要的思路与基础实现。