skill-factory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Factory

Skill Factory turns a request into a working agent skill: a directory with SKILL.md, scripts, tests, a task graph, CI, and evals that all pass their checks before the work counts as done. It also validates and evaluates skills that already exist.

Skill Factory 可将需求转化为可用的Agent Skill：一个包含SKILL.md、脚本、测试、任务图、CI和评估用例的目录，所有内容需通过检查后才算完成工作。它还可验证和评估已有的Skill。

Which commands does this skill accept?

该技能支持哪些命令？

Interpret the user's request as one of these commands.

Command	What it does
help	Show this table and a one line summary per command.
new <prompt>	Build a skill that fulfills the prompt. Main path below.
validate <path>	Run the structure, writing, and code checks on a skill.
eval <path>	Check a skill's eval files, then run its cases.
doctor	Run scripts/doctor.py and report readiness.

--help

on any bundled script prints its flags, exit codes, and an example. Suppose the request matches no command, or a needed fact is missing and cannot be inferred. In this case stop, report exactly what is missing, and wait. Do not guess.

将用户的请求解读为以下命令之一。

命令	功能
help	显示此表格及每个命令的单行摘要。
new <prompt>	构建一个满足prompt需求的Skill。以下是主要流程。
validate <path>	对指定路径下的Skill运行结构、文档和代码检查。
eval <path>	检查Skill的评估文件，然后运行评估用例。
doctor	运行scripts/doctor.py并报告就绪状态。

任何内置脚本后添加

--help

都会打印其参数、退出码及示例。若请求不匹配任何命令，或缺少必要信息且无法推断，则停止操作，准确报告缺失内容并等待，切勿猜测。

How do I build a new skill?

如何构建新Skill？

This is the full plan. After each step, run the named check; when it fails, fix the cause and rerun that check before moving on.

Run
```
python3 scripts/doctor.py
```
. Proceed only when it prints "ready": true. Otherwise report the failing check and stop.
Read references/generation-contract.md in full. Every file you write must meet it.
Check the registry per references/registry.md. When an installed skill already covers the request, defer to it and say so instead of duplicating it.
Derive a name matching
```
^[a-z0-9][a-z0-9._-]*$
```
and a description that contains "Use when". One unresolvable fact: ask one question. Anything smaller: state the assumption and continue.
Create a progress log named <name>-build-log.md next to the new skill. Append one line after each following step.
Scaffold:
```
python3 scripts/scaffold_skill.py --name <name> --description "<description>" --dest <skills directory>
```
. Verify it prints "created". Exit code 2 means the name or the description broke a rule; the message says which. Fix and rerun.
Author in TDD order, replacing scaffold seeds where the request needs more: mise.toml tasks first, then CI contract tests, then script tests, then scripts, then docs, then evals. Read references/code-rules.md before writing code, references/writing-rules.md before writing markdown, and references/eval-authoring.md before writing evals.
Run
```
mise run ci
```
inside the new skill. Exit 0 required. A failing job names the file and reason; fix it and rerun until green.
Run
```
python3 scripts/validate_skill.py <path>
```
and confirm the last line starts with PASS.
Report the tree, each file's purpose, and the check output. Claims about passing checks quote the fresh run, never memory.

以下是完整流程。每一步完成后运行指定检查；若检查失败，修复问题后重新运行该检查，再进行下一步。

运行
```
python3 scripts/doctor.py
```
。仅当输出显示"ready": true时才可继续。否则报告失败检查项并停止。
完整阅读references/generation-contract.md。你编写的每个文件都必须符合其中规定。
根据references/registry.md检查注册表。若已安装的Skill已覆盖当前需求，则直接使用该Skill并告知用户，避免重复构建。
生成符合
```
^[a-z0-9][a-z0-9._-]*$
```
格式的名称，以及包含"Use when"的描述。若存在无法解决的信息缺失：提出一个问题。若信息缺失较小：说明假设并继续。
在新Skill旁创建名为<name>-build-log.md的进度日志。后续每完成一步就追加一行记录。
搭建脚手架：
```
python3 scripts/scaffold_skill.py --name <name> --description "<description>" --dest <skills directory>
```
。验证输出显示"created"。退出码2表示名称或描述违反规则，错误信息会说明具体原因。修复后重新运行。
按TDD顺序编写内容，根据需求替换脚手架生成的初始内容：先编写mise.toml任务，再编写CI契约测试，接着是脚本测试、脚本、文档，最后是评估用例。编写代码前阅读references/code-rules.md，编写markdown前阅读references/writing-rules.md，编写评估用例前阅读references/eval-authoring.md。
在新Skill目录内运行
```
mise run ci
```
。需确保退出码为0。若任务失败，会显示对应的文件及原因；修复后重新运行直至全部通过。
运行
```
python3 scripts/validate_skill.py <path>
```
并确认最后一行以PASS开头。
报告目录结构、每个文件的用途及检查输出。关于检查通过的声明需引用最新运行结果，而非记忆内容。

How do I validate or evaluate an existing skill?

如何验证或评估现有Skill？

For validate <path>, run scripts/validate_skill.py, scripts/lint_writing.py, and scripts/check_code_rules.py on the path. Report every FAIL line with file and reason, then propose the fix for each. For eval <path>, run scripts/check_evals.py first; when it exits 0, run the cases per references/eval-authoring.md and grade each assertion against quoted evidence.

对于validate <path>命令，在指定路径下运行scripts/validate_skill.py、scripts/lint_writing.py和scripts/check_code_rules.py。报告所有包含FAIL的行，包括文件及原因，然后针对每个问题提出修复方案。对于eval <path>命令，先运行scripts/check_evals.py；当退出码为0时，根据references/eval-authoring.md运行评估用例，并对照引用的证据对每个断言进行评分。

What loads when?

各类资源何时加载？

references/generation-contract.md: read before generating any file of a new skill. It is the recursive contract generated skills carry.
references/writing-rules.md: read before writing or editing any markdown file.
references/code-rules.md: read before writing any script or test.
references/eval-authoring.md: read when authoring or grading evals.
references/registry.md: read before any build, to reuse instead of rebuild.
assets/: templates the scaffolder fills. Read assets/skill-template.md when you need to see what a generated SKILL.md contains.
scripts/: the executable commands. Run them; read their source only when a check message stays unclear after one rerun.
scripts/tests/: run through
```
mise run test
```
after changing any script.
evals/: this skill's own cases and trigger queries, plus the registry eval artifact set described in references/eval-authoring.md. Read when measuring the factory itself.

references/generation-contract.md：生成新Skill的任何文件前需阅读。这是生成型Skill需遵循的递归契约。
references/writing-rules.md：编写或编辑任何markdown文件前需阅读。
references/code-rules.md：编写任何脚本或测试前需阅读。
references/eval-authoring.md：编写或评估评估用例时需阅读。
references/registry.md：任何构建操作前需阅读，以便复用现有Skill而非重新构建。
assets/：脚手架工具使用的模板。若需查看生成的SKILL.md包含内容，可阅读assets/skill-template.md。
scripts/：可执行命令。直接运行即可；仅当重新运行后检查信息仍不清晰时，才阅读其源代码。
scripts/tests/：修改任何脚本后，通过
```
mise run test
```
运行测试。
evals/：本技能自身的用例和触发查询，以及references/eval-authoring.md中描述的注册表评估工件集。评估Factory自身时需阅读。

Which task runs which job?

哪些任务对应哪些作业？

Every job has one command.

mise run ci

runs the whole pipeline and is the only entry point CI uses. The pieces: test-ci, test, validate, lint-writing, lint-code, evals, doctor, and new. Remote CI comes from assets/ci/ci.yml; copy that file to .github/workflows/ci.yml in the hosting repository.

每个作业对应一个命令。

mise run ci

会运行整个流水线，是CI使用的唯一入口点。具体包含：test-ci、test、validate、lint-writing、lint-code、evals、doctor和new。远程CI配置来自assets/ci/ci.yml；将该文件复制到托管仓库的.github/workflows/ci.yml即可。

Gotchas

注意事项

The scaffolder refuses descriptions without "Use when" and names with capitals. That is the contract working, never a bug.
The writing lint bans em dashes plus a word list kept inside scripts/lint_writing.py. Rewrite flagged sentences; a close synonym of a banned word usually trips another rule.
The writing lint also enforces the one line layout: every paragraph or list item is one physical line with no hard breaks and no maximum length. See references/writing-rules.md.
Generated skills carry their own copies of the checker scripts, so they verify themselves with
```
mise run ci
```
and keep no path back to this directory.
No file in any skill may name an agent product or a model. The test suite scans generated output for such names and fails on a hit.
A new skill may reach the executor's index only on the next session. The files land immediately even when the index lags.

脚手架工具会拒绝不含"Use when"的描述以及包含大写字母的名称。这是契约要求，并非bug。
文档检查会禁用破折号，并禁止scripts/lint_writing.py中维护的词汇表内的词汇。重写被标记的句子；禁用词汇的近义词通常也会触发其他规则。
文档检查还强制执行单行布局：每个段落或列表项为单行，无硬换行且无长度限制。详情请查看references/writing-rules.md。
生成的Skill会自带检查脚本的副本，因此它们可通过
```
mise run ci
```
自行验证，且无需依赖本目录的路径。
任何Skill中的文件不得提及Agent产品或模型。测试套件会扫描生成的输出，若发现此类名称则会失败。
新Skill可能要到下一个会话才能进入执行器的索引。即使索引延迟，文件也会立即生成。

When is the work done?

工作完成的标准是什么？

Done means all of these from fresh runs inside the new skill:

mise run ci

exits 0, validate_skill.py prints PASS, the writing lint reports 0 problems, evals hold at least four cases with both trigger labels, and the build log records every step.

完成意味着在新Skill目录内的最新运行中满足以下所有条件：

mise run ci

退出码为0，validate_skill.py输出PASS，文档检查报告0个问题，评估用例至少包含4个带有两种触发标签的用例，且构建日志记录了每一步操作。