Turn agent trial-and-error into reusable Claude Code skills — personalized for your OS, your shell, and your network.
把 agent 绕过的弯路锻造成可复用的 Claude Code skill——为你的系统、你的 shell、你的网络环境量身定制。
You ask Claude Code to do something. It tries approach A — fails. Tries B — also fails. Three dead ends later, it finally finds a path that works. Why? Because your Windows 11 (Chinese edition), Git Bash, and GFW-trapped network aren't what the agent expected. A week later, you ask the same thing — the agent has no memory, and walks straight back into the same dead ends.
你让 Claude Code 帮你做一件事。它试了 A 方案——失败了。换 B——又失败了。绕了三个弯路之后，终于找到一条能走通的路。为什么会绕路？因为你的 Windows 11 中文版、Git Bash、被墙的网络——这些都不是 agent 预期中的"标准环境"。一周后你再次提出同样的需求，agent 毫无记忆，再次走进同样的死胡同。
skill-forge captures the winning path after a winding task completes, and generates a personalized Claude Code skill from it. Next time the agent loads the skill, it skips the detours and goes straight to what works.
skill-forge 在 agent 绕完弯路终于成功之后，把那条最终走通的路记录下来，生成一个个性化的 Claude Code skill。下次 agent 加载这个 skill，就能跳过所有弯路，直奔正确答案。
The generated skill records / 生成的 skill 会记录：
- ✅ The exact commands that worked / 实际跑通的命令
- ❌ The dead ends that didn't — and why (environment-specific cause) / 失败的做法——以及环境层面的原因
- 🔧 Your environment / 你的运行环境（OS, shell, 网络, 工具版本）
- 🔍 How to verify success / 验证成功的方法
- 🎯 Pushy trigger descriptions that actually fire when needed / 精准触发的 skill 描述
bash scripts/install.shThis registers /skill-forge in Claude Code.
After a winding but successful task, say in Claude Code: 在一次绕了弯路但最终成功的任务之后，在 Claude Code 中说：
/skill-forge
I just managed to push my project to GitHub after several failed attempts.
我刚才终于把项目推上 GitHub 了，中间失败了好几次。
Claude will analyze the conversation, identify the dead ends, extract the winning path, validate the result, tune the description, and save the skill to ~/.claude/skills/.
Claude 会分析对话记录，识别弯路，提取成功路径，验证结果，调整触发描述，然后保存 skill 到 ~/.claude/skills/。
Next time you ask to push to GitHub, Claude already knows about your proxy config, SSH preference, and branch naming quirks — no detours needed. 下次你再让 Claude 推代码到 GitHub，它已经知道你的代理配置、SSH 偏好、分支命名惯例——不再绕路。
For scripting or CI use:
# Interactive mode
python scripts/generate.py
# From JSON
python scripts/generate.py examples/github-push-input.json
# Dry-run — print to stdout, don't save
python scripts/generate.py examples/github-push-input.json --dry-run
# Generate + auto-validate
python scripts/generate.py examples/github-push-input.json --validateCheck any skill file for common issues:
python scripts/quick_validate.py ~/.claude/skills/my-skill.md
python scripts/quick_validate.py ~/.claude/skills/my-skill.md --strictChecks: YAML validity, required fields, placeholder remnants, trigger phrase specificity, command concreteness, section completeness, and description "pushiness."
A real scenario from a Windows + China environment: 一个真实场景：Windows + 国内网络环境。
Scenario: Push a project to GitHub / 场景：推送项目到 GitHub（点击展开）
| Attempt | Approach / 方案 | Result / 结果 |
|---|---|---|
| 1 | git push origin master |
Timeout — GitHub blocked by GFW / 超时——GFW 阻断 |
| 2 | HTTPS remote + gh auth login |
Popup hell — Windows credential manager / 弹窗地狱 |
| 3 | SSH + per-repo proxy | ❌ 代理仅对单个仓库生效 |
| 4 ✓ | git config --global http.proxy + SSH remote + -u origin main |
Works reliably / 稳定可用 |
The generated skill captures all four attempts, so future sessions jump straight to step 4. 生成的 skill 记录了全部四次尝试，下次直接从第 4 步开始。
→ Full generated skill / 完整 skill → JSON input format / JSON 输入格式
绕弯路的对话记录
│
▼
┌─────────────┐
│ 1. GATHER │ 任务是什么？哪些失败了？为什么？（环境原因！）
│ 收集 │
└──────┬──────┘
│
▼
┌─────────────┐
│ 2. CONFIRM │ 向用户确认摘要 —— 错误的 skill 比没有更糟
│ 确认 │
└──────┬──────┘
│
▼
┌─────────────┐
│ 3. GENERATE │ 填入环境 + 踩坑记录 + 成功路径
│ 生成 │
└──────┬──────┘
│
▼
┌─────────────┐
│ 4. VALIDATE │ 自动检查占位符、缺失字段、弱触发词
│ 验证 │
└──────┬──────┘
│
▼
┌─────────────┐
│ 5. TUNE │ 优化 description 确保 skill 可靠触发
│ 调优 │
└──────┬──────┘
│
▼
┌─────────────┐
│ 6. INSTALL │ 保存到 ~/.claude/skills/{name}.md
│ 安装 │
└─────────────┘
Every skill generated by skill-forge includes / 每个 skill 包含：
| Section / 章节 | Purpose / 用途 |
|---|---|
| Environment / 环境 | OS, shell, network, tools — so the agent knows where it's running / 让 agent 知道自己在什么环境下运行 |
| When to use / 触发条件 | Natural trigger phrases that activate the skill / 触发 skill 的自然语言短语 |
| Quick start / 快速上手 | Minimal 2-3 command path for the most common case / 最常见场景的最简 2-3 条命令 |
| Proven approach / 可行方案 | Step-by-step commands + the why / 逐条命令 + 每一步的环境原因 |
| What this replaces / 替代了什么 | The failed discovery process this skill eliminates / 这个 skill 让 agent 不再需要重新踩坑 |
| Pitfalls / 避坑指南 | Failed attempts, their environment causes, and symptoms / 失败的做法、环境原因、具体表现 |
| Verification / 验证 | How to confirm success + expected output / 验证命令 + 预期输出 |
This project complements Anthropic's official skill-creator (193K+ installs).
| skill-forge | skill-creator (Anthropic) | |
|---|---|---|
| 入口 | 事后：刚完成一个绕了 N 次弯路才成功的任务 | 事前：想设计一个全新的 skill |
| 流程 | 从对话提取 → 一次性生成 | 草拟 → eval 跑分 → 迭代改进 |
| 重点 | 环境特化的踩坑记录 | 通用的 skill 设计方法 |
| 验证 | 用户确认 + quick_validate.py | 并行 subagent 对比 + 量化 benchmark + blind A/B |
skill-forge 和 skill-creator 互补不冲突。用 skill-forge 把踩坑经验固化为 skill，用 skill-creator 从零设计全新 skill 或做 eval 驱动的迭代优化。
skill-forge/
├── SKILL.md # 核心 skill 定义（被安装到 ~/.claude/skills/）
├── CLAUDE.md # 项目上下文（Claude Code 进入目录时加载）
├── templates/
│ └── skill-template.md # 生成 skill 用的模板（含前端验证指导）
├── scripts/
│ ├── install.sh # 一键安装脚本
│ ├── generate.py # 独立生成器（交互式 / JSON 输入 / dry-run / validate）
│ └── quick_validate.py # Skill 质量检查器（YAML / 占位符 / 触发词 / 描述）
├── examples/
│ ├── github-push.md # 示例：生成的 skill 长什么样
│ └── github-push-input.json # 示例：JSON 输入格式
└── LICENSE
Worth it / 值得：
- ✅ Proxy, mirrors, PATH quirks / 代理、镜像源、PATH 等环境问题
- ✅ Platform differences (Windows vs macOS vs Linux) / 平台差异
- ✅ Shell-specific syntax (Git Bash vs PowerShell vs zsh) / Shell 差异
- ✅ Toolchain bugs or version-specific behavior / 工具链 bug 或版本特有问题
- ✅ Permission, firewall, admin-rights / 权限、防火墙、管理员权限
Not worth it / 不值得：
- ❌ One-off tasks / 不会再做的一次性任务
- ❌ Generic solutions in official docs / 官方文档里已经写清楚的
- ❌ Tasks that worked first try with no dead ends / 一次就成功的任务（没什么好记录的）
Found a pattern that skill-forge doesn't handle well? Have an environment-specific example to share? PRs welcome — especially examples that help developers in similar setups. 发现了 skill-forge 没覆盖到的场景？有特定环境的踩坑经验？欢迎 PR——尤其欢迎能帮助同类环境开发者的示例。
MIT — see LICENSE.