Back to Details

ub-quality

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

UB Quality

UB 质量

Critical Contract

关键契约

Apply the embedded baseline in this 
SKILL.md
immediately whenever 
ub-quality
is loaded.
For work that depends on deeper quality rules, load the relevant references by the trigger table in this skill before producing the output. Do not skip a triggered reference because the task looks small or the local style differs.
For every touched eligible vertical separator block, separators must align into one column. Use separator-column alignment (
key : value
), not value-column alignment (
key: value
).
This applies across code, configs, comments, docstrings, markup attributes, and documentation blocks when the structure is eligible.
Treat embedded language blocks such as 
<style>
and 
<script>
as native CSS and JavaScript formatting surfaces, not as generic HTML text.
Only syntax breakage or a verified tooling or runtime constraint may justify leaving an eligible touched block unaligned.
Compliant:
text
grid      : ''
solar     : ''
textMuted : ''
Non-compliant:
text
grid:      ''
solar:     ''
textMuted: ''
每当我们加载 
ub-quality
时，立即应用此 
SKILL.md
中嵌入的基线。
对于依赖更深层质量规则的工作，请根据此 skill 的触发表加载相关参考文档，然后再产出输出。不要因为任务看起来很小或本地风格不同而跳过已触发的参考文档。
对于每个已触及且符合条件的垂直分隔符块，分隔符必须对齐到同一列。使用分隔符列对齐（
key : value
），而不是值列对齐（
key: value
）。
当结构符合条件时，此规则适用于代码、配置、注释、docstring、markup 属性和文档块。
将 
<style>
和 
<script>
等嵌入式语言块视为原生 CSS 和 JavaScript 格式化界面，而不是通用 HTML 文本。
只有语法损坏或经验证的工具或运行时限制，才可以作为不对符合条件的已触及块进行对齐的理由。
符合要求：
text
grid      : ''
solar     : ''
textMuted : ''
不符合要求：
text
grid:      ''
solar:     ''
textMuted : ''

When To Use

何时使用

Use this skill alongside the primary implementation, review, or workflow skill for:
  • New code generation
  • Code edits and refactors
  • Code review responses
  • Repo scans, architecture explanations, and maintainability feedback
  • Documentation, config, comment, and formatting normalization in touched regions
  • User-facing responses that need clearer structure or comparison formatting
Apply this skill whenever you create, modify, review, refactor, or normalize code or documents and the task benefits from shared quality or readability rules.
在以下情况下，请将此 skill 与主要的实现、审查或工作流 skill 一并使用：
  • 生成新代码
  • 编辑代码和重构
  • 代码审查回复
  • 仓库扫描、架构说明和可维护性反馈
  • 对涉及修改的区域中的文档、配置、注释和格式进行规范化
  • 需要采用更清晰结构或对比格式的用户端回复
当你创建、修改、审查、重构或规范化代码或文档，且任务可受益于共享的质量或可读性规则时，应用此 skill。

Do Not Treat As Optional

不可视为可选

  • Do not treat formatting and alignment as optional cleanup.
  • If this skill is loaded, its formatting and alignment rules apply to all touched eligible blocks.
  • Do not skip alignment because nearby code is unaligned, because a shorter style looks more familiar, or because the block is in documentation rather than code.
  • Do not normalize unrelated blocks outside the touched logical scope unless broader normalization was explicitly requested.
  • 不要将格式和对齐视为可选的清理工作。
  • 如果加载了此 skill，其格式和对齐规则将适用于所有已触及且符合条件的块。
  • 不要因为附近代码未对齐、较短的样式看起来更熟悉，或因为该块位于文档而非代码中，就跳过对齐。
  • 除非明确要求更大范围的规范化，否则不要规范化触及逻辑范围之外的不相关块。

Reference Loading Contract

参考文档加载契约

ub-quality
itself remains the always-loaded baseline. Deeper references are not optional; they are loaded by trigger so the right contract is applied at the right time without treating every task as if every quality subdomain is active.
MUST load and apply:
  • references/design-patterns.md
    when making architecture, implementation, refactoring, abstraction, dependency, or maintainability decisions.
  • references/formatting-alignment.md
    before creating or modifying code, configs, examples, comments, docstrings, markup attributes, documentation tables, or any other touched content with eligible separator blocks.
  • references/documentation-structure-refactoring.md
    before creating, editing, reviewing, reorganizing, or refactoring documentation, comments, file structure, public call surfaces, or large source files.
  • references/important-tags-and-doc-generation.md
    before creating or modifying generated documents, comment tags, TODO-like markers, or any content that may contain special preservation tags.
  • references/response-readability.md
    before substantial user-facing plans, reviews, explanations, comparisons, or any answer where structure materially affects scanability.
  • references/freshness-portability.md
    when deciding whether guidance is repository policy, a strong house default, advisory freshness guidance, or a portability concern.
If more than one trigger applies, load every relevant reference before producing the dependent output.
ub-quality
本身始终作为已加载的基线。更深层的参考文档并非可选；它们会根据触发条件加载，从而在恰当的时间应用恰当的契约，而不必将每项任务都视为同时涉及所有质量子领域。
必须加载并应用：
  • 在进行架构、实现、重构、抽象、依赖或可维护性决策时，加载 
    references/design-patterns.md
    。
  • 在创建或修改代码、配置、示例、注释、docstring、markup 属性、文档表格，或任何其他包含符合条件分隔符块的已触及内容之前，加载 
    references/formatting-alignment.md
    。
  • 在创建、编辑、审查、重组或重构文档、注释、文件结构、公共调用界面或大型源文件之前，加载 
    references/documentation-structure-refactoring.md
    。
  • 在创建或修改生成文档、注释标签、TODO 类标记，或任何可能包含特殊保留标签的内容之前，加载 
    references/important-tags-and-doc-generation.md
    。
  • 在编写内容充实的用户端计划、审查、说明、对比，或结构会显著影响可扫描性的任何回复之前，加载 
    references/response-readability.md
    。
  • 在判断某项指导属于仓库政策、强烈的内部默认规范、建议性的时效指导还是可移植性问题时，加载 
    references/freshness-portability.md
    。
如果同时触发多个条件，请在产出相关输出之前加载每个适用的参考文档。

Non-Compliance

不符合要求的情况

The following are non-compliant when a touched block is eligible for alignment:
  • An eligible vertical separator block whose separators do not form one column.
  • Value-column alignment in an eligible block.
  • Leaving embedded CSS/JS blocks unformatted as native language blocks when the touched content is eligible for alignment.
  • Skipping alignment because of convenience, omission, or surrounding local style.
  • Normalizing unrelated blocks outside the touched logical scope.
当已触及的块符合对齐条件时，以下情况不符合要求：
  • 分隔符未对齐到同一列的合格垂直分隔符块。
  • 在符合条件的块中使用值列对齐。
  • 当触及内容符合条件时，未将嵌入式 CSS/JS 块作为原生语言块进行格式化。
  • 因为便利、省略或周围的局部风格而跳过对齐。
  • 规范化触及逻辑范围之外的不相关块。

Decision Analysis Baseline

决策分析基线

For planning, design, architecture, implementation direction, and other choice-bearing guidance:
  • Surface 
    2+
    plausible approaches by default.
  • Prefer a curated set of 
    2-4
    options instead of exhaustive enumeration.
  • Include concise pros/cons for each option and identify the recommended path.
  • If only one path is materially meaningful, say that explicitly and explain why the alternatives are not meaningfully different instead of fabricating a fake option set.
  • Leave sibling skills free to add domain-specific tradeoff dimensions when they add real value.
对于规划、设计、架构、实现方向及其他需要权衡选择的指导：
  • 默认列出至少 2 种可行方案。
  • 优先选择经过筛选的 2-4 种方案，而不是穷举所有可能性。
  • 为每种方案提供简洁的优缺点，并指出推荐路径。
  • 如果只有一条路径具有实质意义，请明确说明，并解释其他方案为何没有实质差异，而不是虚构一套虚假选项。
  • 当同级 skill 能增加真正的价值时，允许其补充特定领域的权衡维度。

Readability Baseline

可读性基线

For user-facing responses across chat, planning, reviews, specs, and explanations:
  • Lead with the answer, recommendation, or key point.
  • Use informative headings for substantial responses.
  • Keep paragraphs short and visually separated.
  • Use bullets for collections and numbered steps for sequence.
  • Keep list items parallel in grammar and intent.
  • Use tables only for true multi-attribute comparisons that stay compact.
  • Avoid dense text blocks when structure would improve scanning.
  • Keep short answers compact and avoid ceremonial formatting.
Table rule:
  • Prefer compact tables only when they materially improve side-by-side comparison.
  • Usually keep tables to 
    2-4
    columns with short headers and brief cells.
  • Do not force sentence-length prose into table cells.
  • When a table becomes too wide, dense, or renderer-fragile, convert it to a safer fallback structure instead of trying to preserve the grid.
对于聊天、规划、审查、规格和说明等用户端回复：
  • 开头直接给出答案、建议或关键要点。
  • 对于内容充实的回复，使用信息明确的标题。
  • 保持段落简短，并在视觉上分隔开。
  • 集合使用项目符号，顺序流程使用编号步骤。
  • 保持列表各项在语法和意图上的一致性。
  • 仅对真正需要多属性对比且内容紧凑的信息使用表格。
  • 当结构化呈现有助于扫描时，避免使用密集文本块。
  • 简短回复应保持紧凑，避免不必要的繁复格式。
表格规则：
  • 仅当紧凑表格能实质改善并排比较时，才优先使用表格。
  • 通常将表格控制在 2-4 列，并使用简短表头和简洁单元格内容。
  • 不要将句子长度的散文强行放入表格单元格。
  • 当表格过宽、过于密集或容易因渲染器而出现问题时，改用更安全的回退结构，而不是尝试保留网格布局。

Core Workflow

核心工作流

  1. Inspect the task scope and touched files.
  2. Apply the embedded baseline immediately.
  3. Load and apply every reference triggered by the task before producing dependent output.
  4. Apply the decision-analysis baseline for planning, design, architecture, implementation direction, and other choice-bearing guidance.
  5. Apply the readability baseline for user-facing responses and choose tables versus safer fallback structures accordingly.
  6. Choose the simplest approach that preserves behavior and constraints.
  7. Apply formatting, documentation, and structure rules only in touched logical blocks.
  8. Validate behavior and explain any intentional exceptions allowed by the triggered references.
  1. 检查任务范围和涉及的文件。
  2. 立即应用嵌入的基线。
  3. 在产出相关输出之前，加载并应用任务触发的每个参考文档。
  4. 对规划、设计、架构、实现方向及其他需要权衡选择的指导应用决策分析基线。
  5. 对用户端回复应用可读性基线，并根据信息形态选择表格或更安全的回退结构。
  6. 选择能够保留行为和约束的最简单方案。
  7. 仅在触及的逻辑块中应用格式、文档和结构规则。
  8. 验证行为，并说明触发参考文档允许的任何有意例外。

Skill Coordination

Skill 协调

  • Apply this skill together with the most relevant language/framework skill when available.
  • Treat this skill as a companion baseline, not as a replacement for the primary implementation or workflow skill.
  • Treat syntax, runtime, and framework correctness as primary constraints.
  • Do not treat formatter preference or familiar house style as a valid reason to violate the alignment contract.
  • Prefer code and naming to carry mechanics, then use docs and comments for contract, rationale, and non-obvious constraints.
  • 如果有适用的语言或框架 skill，请与此 skill 一并应用。
  • 将此 skill 视为配套基线，而不是主要实现或工作流 skill 的替代品。
  • 将语法、运行时和框架正确性视为首要约束。
  • 不要将格式化工具偏好或熟悉的内部风格作为违反对齐契约的正当理由。
  • 优先让代码和命名承载实现机制，再使用文档和注释说明契约、原因及不明显的约束。

Policy Versus Defaults

政策与默认规范

  • In this repository, the alignment contract and triggered-reference workflow are repository policy when 
    ub-quality
    is loaded.
  • Many language/framework recommendations coordinated through sibling skills are strong defaults, not universal portability requirements.
  • Treat volatile setup recipes as freshness-review candidates first, not as automatic blockers, unless the repository explicitly promotes them to policy.
  • 在此仓库中，加载 
    ub-quality
    后，对齐契约和参考文档触发工作流均属于仓库政策。
  • 通过同级 skill 协调的许多语言和框架建议属于强默认规范，而非通用的可移植性要求。
  • 首先将易变的配置方法视为时效性审查候选项，而非自动阻断项，除非仓库明确将其提升为政策。

Output Requirements

输出要求

When generating or modifying code:
  1. Include concise pros/cons and a recommendation for meaningful implementation choices.
  2. Keep solutions simple and avoid overengineering.
  3. Preserve existing behavior unless change is explicitly requested.
  4. Call out any intentionally retained technical debt or deferred cleanup.
  5. Favor high-signal documentation over broad narration, especially in shared guidance and heavily reused code.
  6. Make user-facing explanations easy to scan before deep reading.
  7. Match the structure to the information shape instead of defaulting to dense prose or oversized tables.
在生成或修改代码时：
  1. 对有意义的实现选择提供简洁的优缺点和推荐方案。
  2. 保持方案简单，避免过度设计。
  3. 除非明确要求更改，否则保留现有行为。
  4. 指出任何有意保留的技术债或延后清理事项。
  5. 优先提供高信息量的文档，而非大篇幅叙述，尤其是在共享指导和被大量复用的代码中。
  6. 让用户端说明易于扫描，然后再深入阅读。
  7. 根据信息形态调整结构，不要默认使用密集散文或过大的表格。

Completion Gate

完成检查

Before finalizing:
  • Check every touched eligible separator block.
  • Treat touched 
    <style>
    and 
    <script>
    content as native CSS and JavaScript surfaces.
  • Expand dense multiline-capable structures (for example literals, argument lists, and config/data blocks) into one-item-per-line form when required by 
    references/formatting-alignment.md
    , then align eligible entries.
  • Align separators into one column using the longest-left-token rule from 
    references/formatting-alignment.md
    .
  • Confirm no unrelated blocks were normalized.
  • If any eligible block remains unaligned, the edit is incomplete unless a named exception from 
    references/formatting-alignment.md
    applies.
  • Ensure special comment tags and 
    AGENT_TODO
    handling policy are respected.
  • Expose the answer or recommendation early in user-facing responses.
  • Use headings, bullets, steps, tables, or fallback blocks only when they improve scanability for the information shape.
  • Confirm list items stay parallel and concise.
  • Confirm any table adds clarity rather than width or density problems.
  • If a comparison table became too wide or text-heavy, convert it to a stacked fallback structure instead of forcing the grid.
  • Keep brief answers brief.
在最终定稿之前：
  • 检查每个已触及且符合条件的分隔符块。
  • 将已触及的 
    <style>
    和 
    <script>
    内容视为原生 CSS 和 JavaScript 界面。
  • 根据 
    references/formatting-alignment.md
    的要求，将密集且可拆为多行的结构（例如字面量、参数列表以及配置或数据块）展开为每行一项，然后对齐符合条件的条目。
  • 使用 
    references/formatting-alignment.md
    中的最长左侧 token 规则，将分隔符对齐到同一列。
  • 确认未规范化任何不相关块。
  • 如果任何符合条件的块仍未对齐，则编辑尚未完成，除非适用 
    references/formatting-alignment.md
    中明确命名的例外。
  • 确保遵守特殊注释标签和 
    AGENT_TODO
    处理政策。
  • 在用户端回复中尽早给出答案或建议。
  • 仅在标题、项目符号、步骤、表格或回退块有助于根据信息形态提高可扫描性时使用它们。
  • 确认列表各项保持简洁且结构一致。
  • 确认任何表格都能提升清晰度，而不是造成宽度或密度问题。
  • 如果对比表格过宽或文本过重，请改用堆叠式回退结构，而不是强行保留网格布局。
  • 保持简短回复简洁。