using-gabrielmoreira-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using Gabriel Moreira's Skills

使用Gabriel Moreira的Skills

Core principle. The other skills say how to do the work. This one says how I want it done, and it is the only file here that is allowed to be opinionated.

Nothing here is a recommendation. It is one person's configuration, named after him so nobody mistakes it for advice.
The skill that matched still owns its subject. This resolves what that skill left open, and never overrides it.
You opened this in the middle of something. This is how to do that work, not a replacement for it. Name what you were doing before you start, and return to it when this is done.

核心原则：其他skill定义工作的执行方式，而本文件定义我希望工作如何执行，它是此处唯一允许带有主观倾向的文件。

此处内容绝非建议。这是某个人的配置文件，以他的名字命名，避免被误认为通用建议。
匹配到的skill仍主导其负责的领域。本文件仅解决该skill未明确的问题，绝不会覆盖其内容。
你是在工作中途打开本文件的。这是当前工作的执行规则，而非替代原有工作。请先说明你之前正在进行的工作，完成本文件相关操作后再返回原工作。

Routing the work

工作路由

Match the work to a row and open that skill. Then come back here only for what the matched skill left open.

When the work is	Open
a change to judge before it lands: a branch, a pull request, a diff against a base point, or uncommitted work	`evidence-backed-review`
something failing, flaky, hanging, or newly slow, with the cause not yet established	`debugging-by-evidence`
a feature or bugfix about to be implemented, or a test written after the code	`test-first-by-evidence`
a tool, runtime, install, auth, or network failure that is not the change being made	`treat-blockers-as-incidents`
a git operation that refused, a state you cannot name, or work about to be deleted or cleaned up	`keep-git-work-recoverable`
written material to create, correct, place, or remove, including whether a decision is worth recording	`make-the-docs-trustworthy`
code that should stay simple and testable: boundaries, cohesion, layering, hidden effects, abstraction added too early	`maintainable-code`
TypeScript specifics: standards, boundaries, composition, config, async, errors, observability, security, testing	`typescript-skills`
an answer that is dense, buried, or hard to resume	`progressive-reading`
a skill to write, split, rename, or check, or one that never fires	`authoring-verifiable-skills`

Boundaries, so they do not fight. Review judges a change that already exists; debugging establishes a cause when there is no change yet; once a fix exists it becomes a change again.
```
maintainable-code
```
owns language-neutral structure and only material architecture work;
```
typescript-skills
```
owns the ecosystem and is the primary one when both apply. Docs inside a diff belong to review; docs on their own belong to
```
make-the-docs-trustworthy
```
.
Other skills may fire alongside these. On a procedure conflict, follow the one more adequate to the situation and say which one lost.

将工作与下表中的行匹配，然后打开对应的skill。仅当匹配到的skill存在未明确的问题时，才回到本文件查找答案。

工作场景	打开对应的skill
需要在落地前评估的变更：分支、拉取请求、与基准点的差异，或未提交的工作	`evidence-backed-review`
出现故障、不稳定、挂起或突然变慢的情况，且原因尚未明确	`debugging-by-evidence`
即将实现的功能或bug修复，或在代码完成后编写测试	`test-first-by-evidence`
工具、运行时、安装、认证或网络故障，且该故障与当前正在进行的变更无关	`treat-blockers-as-incidents`
Git操作失败、无法确定状态，或即将删除/清理的工作	`keep-git-work-recoverable`
需要创建、修正、放置或移除的书面材料，包括判断某项决策是否值得记录	`make-the-docs-trustworthy`
应保持简洁可测试的代码：边界、内聚性、分层、隐藏副作用、过早添加的抽象	`maintainable-code`
TypeScript相关细节：标准、边界、组合、配置、异步、错误、可观测性、安全、测试	`typescript-skills`
内容密集、难以查找或恢复的答案	`progressive-reading`
需要编写、拆分、重命名或检查的skill，或从未触发过的skill	`authoring-verifiable-skills`

边界划分，避免冲突：评审针对已存在的变更；调试在无变更时确定原因；一旦修复方案存在，它就再次成为变更。
```
maintainable-code
```
负责与语言无关的结构及重要架构工作；
```
typescript-skills
```
负责生态系统相关内容，当两者都适用时优先遵循前者。变更中的文档归评审处理；独立的文档归
```
make-the-docs-trustworthy
```
处理。
其他skill可能与上述skill同时触发。当流程发生冲突时，选择更适合当前场景的skill，并说明未选择的skill。

Where generated files go

生成文件的存放位置

What	Where	Committed
scratch, temps, generated plans, abandoned investigations	`.local/` at the repository root	never
a learning anyone cloning this repository would need	`docs/learnings/`	yes
a learning only this machine has	`~/.agents/learnings/`	never
anything a skill produces and does not place	ask, then record the answer here

.local/
is ignored, in
.gitignore
or in the exclude file. Set that up before writing to it.
One question decides between the two learnings directories. Would a colleague cloning this repository hit the same thing? Yes goes inside, no goes outside.
Report the path chosen and whether it is tracked, every time.

文件类型	存放位置	是否提交
草稿、临时文件、生成的计划、已放弃的调研内容	仓库根目录下的 `.local/`	绝不提交
任何克隆本仓库的人都需要了解的经验总结	`docs/learnings/`	是
仅当前机器需要的经验总结	`~/.agents/learnings/`	绝不提交
skill生成但未指定存放位置的内容	询问后，将答案记录在此处

.local/
会被忽略，已添加到
```
.gitignore
```
或排除文件中。在写入该目录前请确认已完成此设置。
一个问题区分两个经验总结目录：同事克隆本仓库后是否会遇到同样的问题？是则存放在仓库内，否则存放在仓库外。
每次都要报告选择的路径及其是否被追踪。

Which skill wins

优先选择的skill

Only genuinely ambiguous pairs belong here. Everything else is settled by the skills themselves.

Situation	Open	Not
a command failed for a reason that is not the change being made	`treat-blockers-as-incidents`	`debugging-by-evidence`
a test fails because the behaviour is missing	`test-first-by-evidence`	`treat-blockers-as-incidents`
a defect in the code being changed	`debugging-by-evidence`	`treat-blockers-as-incidents`
where a test goes for behaviour being added	`test-first-by-evidence`	`debugging-by-evidence`
where a test goes to pin a defect	`debugging-by-evidence`	`test-first-by-evidence`
judging work that already exists as commits	`evidence-backed-review`	`maintainable-code`
designing work that does not exist yet	`maintainable-code`	`evidence-backed-review`

Two or more matching is normal. Process comes before implementation, and the narrower one wins where they overlap.
Not finding a match is an answer. Do not stretch one to fit.
My own skills come first, ahead of any borrowed collection, because they are being validated against real work.

仅真正模糊的场景需要在此处明确。其他场景均由skill自身解决。

场景	优先打开的skill	不选择的skill
命令执行失败，且原因与当前变更无关	`treat-blockers-as-incidents`	`debugging-by-evidence`
测试失败是因为缺少对应功能	`test-first-by-evidence`	`treat-blockers-as-incidents`
当前变更的代码中存在缺陷	`debugging-by-evidence`	`treat-blockers-as-incidents`
为新增功能选择测试存放位置	`test-first-by-evidence`	`debugging-by-evidence`
为定位缺陷选择测试存放位置	`debugging-by-evidence`	`test-first-by-evidence`
评估已提交为commit的工作	`evidence-backed-review`	`maintainable-code`
设计尚未存在的工作	`maintainable-code`	`evidence-backed-review`

多个skill匹配是正常情况。流程优先于实现，重叠部分优先遵循更具体的skill。
未找到匹配项也是一种结果。不要强行套用某个skill。
优先使用我自己的skill，而非任何外部引入的集合，因为它们已经过实际工作验证。

Discussion is not authorization

讨论不代表授权

Analysis, alternatives, proposals and plans do not authorize anything. Change code, configuration, infrastructure or external state only after I say to implement, apply, change, or select.
After a compaction, a model change, a resume, or a handoff, every prior proposal is pending again unless the authorization is still visible in the active context.
Where authorization is unclear, ask one specific question before touching anything.

分析、替代方案、提议和计划不构成任何授权。只有在我明确指示“实现”“应用”“变更”或“选择”后，才能修改代码、配置、基础设施或外部状态。
在compaction、模型变更、恢复或交接后，所有先前的提议都需重新确认，除非授权仍在当前上下文可见。
当授权不明确时，在进行任何操作前先提出一个明确的问题。

What I do not want

我不希望出现的情况

No ceremony on a one-line change whose failure mode is visible on reading it.
No workaround reported as a fix. Say the tool is broken and let me decide.
No review that closes on local test and lint output. Numbers are not a judgment.
No skill's procedure replacing the thing I asked for. Answer what I asked, then say what else you found.
No em dash anywhere, in any file, in any message.

对于单行变更，若其失败模式一目了然，则无需繁琐流程。
不要将临时解决方案报告为修复方案。说明工具存在问题，由我决定后续处理。
不要仅依据本地测试和lint输出就完成评审。数字不能作为判断依据。
不要用skill的流程替代我的需求。先回答我的问题，再说明你发现的其他内容。
任何文件、任何消息中都禁止使用破折号（em dash）。

Defaults the portable skills leave open

可移植skill未明确的默认规则

The primary agent is omp. Others are secondary, and a procedure that only works in one of them is not finished.
Skills are not proven until a run shows it. A green structural suite says the files are well formed and nothing about behaviour.
A number without its interval invites reading noise as movement. Report both.
Where a measurement and my opinion disagree, the measurement wins, and the opinion gets rewritten here.

主Agent为omp。其他Agent为次要选择，仅能在单个Agent中运行的流程不算完成。
skill需经过实际运行验证才算可靠。结构测试套件通过仅说明文件格式规范，不代表行为正确。
不带区间的数值容易误将噪音视为变化。需同时报告数值和区间。
当测量结果与我的意见不一致时，以测量结果为准，我的意见将在此处更新。

Hooks, when they exist

钩子（若存在）

Nothing here installs itself. No configuration is written, and no session tool is registered without being asked.
Where the harness offers a way to re-read this between turns, propose it and let me decide. An instruction that only lives in the system prompt is read once and forgotten by some models.
Until then, name the procedure you are following in your first line of work, so a lapse is visible to me rather than silent.

本文件不会自动安装。未经询问，不得写入任何配置或注册任何会话工具。
若工具提供了在会话轮次间重新读取本文件的方式，请提出建议并由我决定。某些模型只会读取一次系统提示中的指令，之后会遗忘。
在此之前，请在工作的第一行说明你遵循的流程，以便我能发现任何疏漏，而非让其隐藏。

Routing

路由补充

This file resolves; it does not instruct. The matched skill owns its subject.
Where this file has no answer, say so rather than inventing one, and the gap gets filled here.
A direct instruction from me outranks anything here.

本文件用于解决分歧，而非下达指令。匹配到的skill仍主导其负责的领域。
若本文件未给出答案，请直接说明，不要自行编造，遗漏的内容将在此处补充。
我的直接指令优先级高于本文件中的任何内容。