skill-forge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

skill-forge

The skill of skills, for skills. Builds new ones, refines existing ones, and mines chat transcripts for what to build next.

技能的元技能，专为技能而生。可创建新技能、优化现有技能，并从聊天记录中挖掘下一步应构建的技能方向。

When to invoke

何时调用

Three modes. Pick by what the user says.

Mode	Triggers	What it does
forge	"skill-forge a thing that does X", "forge a skill that ...", "build me a skill for ..."	Ask 2-3 clarifying questions, scaffold `~/.claude/skills/<name>/SKILL.md` from the template, open PR to `mphinance/alpha-skills` .
audit	"skill-forge audit", "skill audit", "/skill-forge", "what skills should I build"	Run the miner over `~/.claude/projects/*/.jsonl` , present `reports/latest.md` , ask which candidates to forge or refine.
refine	"refine my skills", "skill-forge refine <name>", "improve the <name> skill"	Propose additive-only changes (new trigger phrase, new example, new section) to an existing skill. Opens PR with diff.

三种模式，根据用户的指令选择。

模式	触发指令	功能说明
创建（forge）	"skill-forge a thing that does X"、"forge a skill that ..."、"build me a skill for ..."	提出2-3个澄清问题，基于模板生成 `~/.claude/skills/<name>/SKILL.md` 文件，并向 `mphinance/alpha-skills` 提交PR。
审核（audit）	"skill-forge audit"、"skill audit"、"/skill-forge"、"what skills should I build"	对 `~/.claude/projects/*/.jsonl` 文件运行挖掘工具，生成 `reports/latest.md` 报告并展示，询问用户要对哪些候选技能进行创建或优化。
优化（refine）	"refine my skills"、"skill-forge refine <name>"、"improve the <name> skill"	针对现有技能提出仅增量式的修改建议（如新触发短语、新示例、新章节），并提交包含差异的PR。

Flow

流程

forge mode

创建模式

Ask the user 2-3 questions max: skill name (kebab-case), one-sentence purpose, primary trigger phrase. Don't over-interview.

Run the scaffolder.

python scripts/forge_new.py --name <name> --brief "<one-sentence purpose>"

The scaffolder reads

templates/SKILL.md.tmpl

and substitutes

{{name}}

{{description}}

{{title}}

{{when_to_invoke}}

{{flow}}

{{hard_rules}}

Open the freshly written
```
~/.claude/skills/<name>/SKILL.md
```
. Review with the user. Tighten copy if needed.
Publish.
```
python scripts/publish.py <name>
```
This clones
```
mphinance/alpha-skills
```
into
```
~/.cache/skill-forge/alpha-skills
```
if missing, branches
```
skill-forge/<name>-<short-ts>
```
, commits, pushes, opens PR. Prints PR URL. Stop there. User reviews and merges.

最多向用户提出2-3个问题：技能名称（短横线分隔格式kebab-case）、一句话用途描述、主要触发短语。不要过度询问。

运行脚手架工具。

python scripts/forge_new.py --name <name> --brief "<one-sentence purpose>"

脚手架工具会读取

templates/SKILL.md.tmpl

模板，并替换其中的

{{name}}

、

{{description}}

、

{{title}}

、

{{when_to_invoke}}

、

{{flow}}

、

{{hard_rules}}

变量。

打开刚生成的
```
~/.claude/skills/<name>/SKILL.md
```
文件，与用户一起审核。如有需要，精简内容。
发布。
```
python scripts/publish.py <name>
```
该命令会将
```
mphinance/alpha-skills
```
仓库克隆到
```
~/.cache/skill-forge/alpha-skills
```
（如果尚未存在），创建分支
```
skill-forge/<name>-<short-ts>
```
，提交代码并推送，然后打开PR。打印PR链接。到此为止，由用户审核并合并。

audit mode

审核模式

Run the miner.
```
python scripts/mine_chats.py --days 30
```
Read
```
reports/latest.md
```
aloud (the markdown report) and
```
reports/latest.json
```
(structured candidates).
Present the three sections: new-skill candidates, refinement candidates, pain points. Ask which to act on.
For each chosen new-skill candidate, drop into forge mode with
```
publish.py --from-audit
```
so the PR body cites the mined evidence.
For each chosen refinement candidate, drop into refine mode.

运行挖掘工具。
```
python scripts/mine_chats.py --days 30
```
读取
```
reports/latest.md
```
（Markdown格式报告）和
```
reports/latest.json
```
（结构化候选技能数据）。
展示三个部分内容：潜在新技能、待优化技能、痛点问题。询问用户要处理哪些内容。
对于每个选中的潜在新技能，进入创建模式并使用
```
publish.py --from-audit
```
命令，使PR正文引用挖掘到的证据。
对于每个选中的待优化技能，进入优化模式。

refine mode

优化模式

Read the target skill's existing SKILL.md in full. You are not allowed to remove or restructure anything.
Propose additions only: new trigger phrase in the frontmatter description, new example, new "When NOT to use" bullet, new flow step.
Write the proposed change to
```
proposals/<skill-name>/CHANGES.diff
```
first. Confirm with the user.
Apply the additive edit to
```
~/.claude/skills/<skill-name>/SKILL.md
```
.
Publish.
```
python scripts/publish.py <skill-name>
```
Commit message starts with "Refine <name> skill: <one-line summary>". PR body explains the addition and links the mined evidence.

完整读取目标技能现有的SKILL.md文件。禁止删除或重构任何内容。
仅提出增量式修改建议：在前置描述中添加新触发短语、新增示例、新增“何时不应使用”项目符号、新增流程步骤。
先将建议的修改写入
```
proposals/<skill-name>/CHANGES.diff
```
文件，与用户确认。
将增量修改应用到
```
~/.claude/skills/<skill-name>/SKILL.md
```
文件。
发布。
```
python scripts/publish.py <skill-name>
```
提交信息以"Refine <name> skill: <one-line summary>"开头。PR正文说明新增内容并链接挖掘到的证据。

Hard rules

硬性规则

Never auto-merge PRs.
```
publish.py
```
opens the PR. User merges. No
```
gh pr merge
```
ever.
Never restructure existing skills in refine mode. Additive-only. If a skill needs a rewrite, that's a new forge, not a refine.
Refinements are additive-only. No removed lines beyond pure whitespace.
```
publish.py
```
enforces this in refine mode.
Never mine recursively on skill-forge's own sessions. The miner already filters self-references. Don't disable it.
Skip SSH transcripts. Project paths starting with
```
ssh-
```
or cwd under
```
/home/
```
are remote work and not mined.
No em dashes. Use en dash with spaces or commas. No emojis in forged skills.
stdlib only. Forged skills and skill-forge scripts use Python stdlib, no pip installs.
Always go through PR. Never edit files in
```
~/.cache/skill-forge/alpha-skills/skills/
```
directly.

绝不自动合并PR。
```
publish.py
```
仅打开PR，由用户进行合并。绝对不能使用
```
gh pr merge
```
命令。
优化模式下绝不重构现有技能。仅允许增量修改。如果技能需要重写，应创建新技能而非优化现有技能。
优化仅允许增量修改。除纯空白字符外，禁止删除任何行。
```
publish.py
```
在优化模式下会强制执行此规则。
绝不挖掘skill-forge自身会话的记录。挖掘工具已自动过滤自身引用，请勿禁用此功能。
跳过SSH会话记录。以
```
ssh-
```
开头的项目路径或当前工作目录位于
```
/home/
```
下的属于远程工作内容，不进行挖掘。
禁止使用长破折号（em dashes）。使用带空格的短破折号（en dash）或逗号。创建的技能中禁止使用表情符号。
仅使用标准库。创建的技能和skill-forge脚本仅使用Python标准库，无需通过pip安装依赖。
始终通过PR操作。绝不直接编辑
```
~/.cache/skill-forge/alpha-skills/skills/
```
目录下的文件。

Scheduling

调度设置

The audit is the part you want on a cron. Two options:

Preferred – use the
/schedule
skill.
```
/schedule weekly /skill-forge audit
```
Runs the audit weekly, writes
```
reports/latest.md
```
, notifies you next session.
Free-tier alternative for the miner alone. Wire Windows Task Scheduler to run
```
python C:\Users\mphan\.claude\skills\skill-forge\scripts\mine_chats.py --days 7
```
on a weekly trigger. Zero tokens spent. You read
```
reports/latest.md
```
when you feel like it, then invoke
```
skill-forge audit
```
interactively to act on candidates.

Forge and refine modes are interactive by design. Don't schedule those.

审核功能适合设置定时任务。有两种选择：

推荐方式 – 使用
/schedule
技能。
```
/schedule weekly /skill-forge audit
```
每周运行一次审核，生成
```
reports/latest.md
```
报告，并在下次会话时通知你。
免费替代方案（仅运行挖掘工具）。通过Windows任务计划程序设置每周触发运行
```
python C:\Users\mphan\.claude\skills\skill-forge\scripts\mine_chats.py --days 7
```
。无需消耗令牌。你可以在方便时查看
```
reports/latest.md
```
，然后交互式调用
```
skill-forge audit
```
来处理候选技能。

创建和优化模式为交互式设计，请勿设置定时任务。

Out of scope

超出范围的内容

Auto-merging PRs. User merges, always.
In-place edits to skills in
```
~/.claude/skills/
```
during refine mode. Always go through PR against
```
mphinance/alpha-skills
```
.
Mining transcripts from machines other than this one.
Forging non-markdown skills (binary plugins, MCP servers, anything that isn't a SKILL.md plus optional scripts).
Rewriting or restructuring existing skills. Refinements are additive-only.

自动合并PR。始终由用户进行合并。
优化模式下直接编辑
```
~/.claude/skills/
```
目录下的技能文件。始终通过向
```
mphinance/alpha-skills
```
提交PR来操作。
挖掘其他机器上的会话记录。
创建非Markdown格式的技能（如二进制插件、MCP服务器等非SKILL.md加可选脚本的内容）。
重写或重构现有技能。优化仅允许增量修改。