Back to Details

repo-skillopt

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

RepoSkillOpt — Canonical Skill

RepoSkillOpt — 标准技能

Purpose

用途

This skill helps a coding agent understand a legacy repository through evidence-grounded analysis and human-feedback-driven refinement. It produces a structured Repository Specification, accepts human corrections as a first-class input, and supports a bounded loop in which recurrent feedback is summarized into reviewable edits to the skill itself. The skill is vendor-neutral: it does not depend on any particular coding-agent runtime.
该技能帮助编码Agent通过基于证据的分析和人工反馈驱动的优化来理解遗留代码库。它生成结构化的代码库规范，将人工修正作为一等输入，并支持一个有限循环，在此循环中，循环反馈会被总结为可审核的技能自身编辑内容。该技能与厂商无关：不依赖任何特定的编码Agent运行时。

Trigger Conditions

触发条件

Activate this skill when the user asks to understand, map, document, onboard to, refactor, modify, or assess a repository — or uses recognizable equivalents of those verbs (e.g., "explain this codebase," "summarize the architecture," "what would change if we…", "is it safe to…").
Do not activate this skill for requests that fall outside the verbs above (e.g., generic chat, unrelated writing tasks, single-file edits that do not require repository-level understanding). Ordinary agent behavior continues in those cases.
当用户请求理解、映射、文档化、上手、重构、修改或评估代码库时，或使用这些动词的等效表述（例如“解释这个代码库”“总结架构”“如果我们……会有什么变化”“这样做安全吗……”），激活该技能。
对于上述动词之外的请求（例如通用聊天、无关写作任务、无需代码库级理解的单文件编辑），请勿激活该技能。此类情况沿用普通Agent行为。

Operating Principles

操作原则

  • Do not rely only on README files. README contents are evidence, not the whole truth. They may be outdated, aspirational, or wrong. Always corroborate against code, configs, tests, and command outputs.
  • Ground every major claim in repository evidence. Prefer concrete paths, symbols, configs, tests, and command outputs over generic descriptions. A major claim is any assertion that fills a non-trivial slot in a Repository Specification section (entrypoint identity, technology choice, dependency relationship, control- or data-flow step, integration target, risk statement) or any standalone assertion a maintenance reader would act on. Trivial recitations (literal file contents, raw config dumps, syntactic restatements) are not major claims.
  • Separate verified facts from hypotheses. Every major claim carries exactly one of four labels (defined under Output Discipline below): 
    **[fact]**
    , 
    **[inference]**
    , 
    **[unknown]**
    , 
    **[human]**
    .
  • Identify uncertainty explicitly. When information cannot be determined from inspection, record the gap under Unknowns and unresolved questions rather than guessing. An honest "unknown" is more useful than a confident wrong answer.
  • Prefer concrete evidence over training-data pattern matching. Two repositories in the same ecosystem can differ in ways that pattern matching will miss. Inspect this repository.
  • Do not overclaim architecture from shallow inspection. If you have only read manifests and a handful of entrypoints, do not describe layers and data flows as if you had traced them.
  • Preserve human feedback as reusable knowledge only when properly scoped. Repository-specific facts stay repository-scoped; only feedback explicitly marked candidate-for-generic enters the convergence pipeline that targets this skill itself, and even then only via an accepted Skill Edit Proposal.
  • 不要仅依赖README文件。README内容是证据，但并非全部真相。它们可能过时、理想化或存在错误。始终通过代码、配置、测试和命令输出来验证。
  • 每项重要结论都要基于代码库证据。优先使用具体路径、符号、配置、测试和命令输出，而非通用描述。重要结论指的是填充代码库规范章节中非平凡内容的任何断言（入口点标识、技术选择、依赖关系、控制流/数据流步骤、集成目标、风险声明），或维护人员会据此采取行动的任何独立断言。平凡复述（字面文件内容、原始配置转储、语法重述）不属于重要结论。
  • 区分已验证事实与假设。每项重要结论都必须带有以下四个标签之一（定义见下文“输出规范”）：
    **[fact]**
    、
    **[inference]**
    、
    **[unknown]**
    、
    **[human]**
    。
  • 明确标识不确定性。当无法通过检查确定信息时，将该缺口记录在“未知与未解决问题”部分，而非猜测。诚实的“未知”比自信的错误答案更有用。
  • 优先选择具体证据而非训练数据模式匹配。同一生态系统中的两个代码库可能存在模式匹配无法识别的差异。请检查当前代码库。
  • 不要通过浅层检查过度断言架构。如果仅读取了清单文件和少量入口点，请勿像已经追踪过一样描述层级和数据流。
  • 仅在适当范围内保留可复用的人工反馈知识。代码库特定事实仅保留在代码库范围内；只有明确标记为“候选通用内容”的反馈才会进入针对该技能的收敛流程，并且即使如此，也只能通过已接受的技能编辑提案进行。

Repository Understanding Workflow

代码库理解工作流

Execute the following stages in order. Skipping or reordering stages weakens the evidence chain that downstream sections depend on.
(a) Triage repository structure. List the top-level directories. Note presence of 
src/
, tests, docs, deployment files, CI configuration, multiple subprojects (monorepo signal).
(b) Identify language, framework, package manager, and runtime. Read manifests (
pyproject.toml
, 
package.json
, 
go.mod
, 
pom.xml
, 
Cargo.toml
, 
Gemfile
, 
composer.json
, etc.). Record versions and runtime constraints.
(c) Inspect manifests, configs, tests, deployment files, and entrypoints. Read at least: build/runtime configs, environment templates, CI workflow definitions, test runner configuration, deployment manifests, and the files identified as entrypoints (CLI scripts, HTTP route registrations, library 
__init__
/ 
index
files).
(d) Map modules, layers, dependencies, domain concepts, and data flow. Walk the source tree; assign each module a role; identify the dependency direction between layers; record the names domain experts in this codebase use. Enumerate every function and class defined in the repository so none is silently skipped (see the symbol-accounting rule under Repository Specification Format).
(e) Trace specific behavior from entrypoint to core logic to persistence or side effects. For at least one user-relevant behavior, produce a numbered trace listing every hop (entrypoint → middleware → service → repository → side effect/storage), citing the file and symbol at each hop.
(f) Produce a Repository Specification — incrementally, on disk. Use the Repository Specification template at 
templates/repository-specification.md
and fill all 19 required sections, applying the label-and-citation discipline from Output Discipline. Write each section to the spec file as you complete it, and do not retain already-written sections in working context — once a section is persisted, drop it from your working set and keep only the section you are currently writing plus the evidence it needs. When a later section must consult an earlier one (e.g. de-duplicating the Evidence index), read it back from the file rather than holding the whole document in context. This keeps working context bounded by the current section instead of the whole growing spec, so the workflow scales to large repositories within a small context window. The authoritative specification is always the file on disk, never an in-context copy.
(g) Identify risks, unknowns, and safe next steps. Populate Known risks with repository-specific (not generic) risks, each tied to evidence. Populate Unknowns and unresolved questions with every gap surfaced during stages (a)–(f). Suggest concrete next steps a human can take to resolve key unknowns.
(h) Guarantee symbol completeness (deterministic — final action). Before finishing, make the Symbols not yet analyzed listing complete and mechanical: every function and class not already discussed must appear there, grouped by file, with the counts line. Generate this listing deterministically — by running a completeness helper that enumerates the repository's symbols and lists the ones the analysis did not name — rather than transcribing it by hand. Your job is the analysis (the prose above); this step guarantees the accounting so nothing is silently skipped.
按顺序执行以下阶段。跳过或重新排序阶段会削弱下游章节依赖的证据链。
(a) 分类代码库结构。列出顶级目录。记录是否存在
src/
、测试、文档、部署文件、CI配置、多个子项目（单体仓库信号）。
(b) 识别语言、框架、包管理器和运行时。读取清单文件（
pyproject.toml
、
package.json
、
go.mod
、
pom.xml
、
Cargo.toml
、
Gemfile
、
composer.json
等）。记录版本和运行时约束。
(c) 检查清单、配置、测试、部署文件和入口点。至少读取：构建/运行时配置、环境模板、CI工作流定义、测试运行器配置、部署清单，以及被标识为入口点的文件（CLI脚本、HTTP路由注册、库
__init__
/
index
文件）。
(d) 映射模块、层级、依赖、领域概念和数据流。遍历源代码树；为每个模块分配角色；识别层之间的依赖方向；记录该代码库领域专家使用的名称。枚举代码库中定义的每个函数和类，确保没有被静默跳过（见“代码库规范格式”下的符号统计规则）。
(e) 追踪从入口点到核心逻辑再到持久化或副作用的特定行为。至少针对一个用户相关行为，生成编号追踪列表，列出每个跳转步骤（入口点 → 中间件 → 服务 → 仓库 → 副作用/存储），并引用每个步骤的文件和符号。
(f) 增量生成代码库规范并保存到磁盘。使用
templates/repository-specification.md
中的代码库规范模板，填充所有19个必填章节，应用“输出规范”中的标签和引用规则。完成每个章节后将其写入规范文件，不要在工作上下文保留已写入的章节——一旦章节被持久化，就将其从工作集中移除，仅保留当前正在编写的章节及其所需的证据。当后续章节需要参考先前章节时（例如“证据索引”去重），从文件中读取而非在上下文中保存整个文档。这使工作上下文始终局限于当前章节，而非整个不断增长的规范，因此该工作流可在有限上下文窗口内扩展到大型代码库。权威规范始终是磁盘上的文件，而非上下文副本。
(g) 识别风险、未知项和安全下一步。在“已知风险”部分填充代码库特定（非通用）风险，每项风险都关联证据。在“未知与未解决问题”部分填充阶段(a)-(f)中发现的所有缺口。建议人类可以采取的具体下一步措施来解决关键未知项。
(h) 保证符号完整性（确定性——最终操作）。完成前，确保“尚未分析的符号”列表完整且机械生成：所有未讨论的函数和类都必须出现在此处，按文件分组，并附带计数行。通过运行完整性辅助工具枚举代码库的符号并列出未分析的符号，以确定性方式生成此列表——而非手动转录。你的工作是分析（上文的 prose 内容）；此步骤保证统计，确保没有内容被静默跳过。

Repository Specification Format

代码库规范格式

The Repository Specification template lives at 
templates/repository-specification.md
. The agent MUST produce a file matching that template, with all 19 sections present in this order:
  1. Repository overview
  2. Technology stack
  3. Build and runtime commands
  4. Major entrypoints
  5. Architectural layers
  6. Core modules
  7. Domain model
  8. Data model
  9. External integrations
  10. Control-flow traces
  11. Data-flow traces
  12. Dependency map
  13. Configuration map
  14. Testing strategy
  15. Deployment assumptions
  16. Change-impact map
  17. Known risks
  18. Unknowns and unresolved questions
  19. Evidence index
Empty-by-design sections explicitly state "None known" or "Not applicable" — they are never silently omitted. The Evidence index lists every distinct citation appearing in the document, de-duplicated.
Symbol accounting (no silent omission). Every function and class defined in the repository MUST be accounted for: either referenced in an analytical claim/citation, or listed under a "Symbols not yet analyzed" subsection of Core modules (grouped by file; per-file counts are acceptable on large repositories). State the counts — N defined, M analyzed, N−M listed — so a reader can see nothing was hidden. Exclude generated/vendored directories.
Repository ontology (build it first). Before writing Domain model and Data model, construct the repository's ontology: an inventory of entities of fixed kinds — module, class, function, data entity, route, job, abstraction — each pinned to 
file:line
, and the relations between them — imports, inherits, foreign-key, registers-route, schedules. Locate them with a fast scanner (
rg
where available, falling back to 
grep
/
git ls-files
) and read only the matched lines you cite — do not load whole files. Present in Domain model a high-level entity-map table (kind · count · examples with citations) and a relationship 
graph
. Detect abstraction entities structurally — a base class inherited by two or more others — not from a fixed repo-specific name list. A relation whose target cannot be resolved to a known entity is 
**[inference]**
/
**[unknown]**
and MUST NOT be drawn as a hard edge.
Data-model diagram. When the repository has a database or persistent schema, the Data model section MUST include a fenced 
```mermaid
block containing an 
erDiagram
of the real tables/models — their key columns and foreign-key relationships — with each entity traceable to the schema file that defines it (migration, DDL, or ORM model). The 
erDiagram
is the data-entity slice of the ontology. When there is no persistent schema, state "Not applicable"; never draw a fabricated schema.
Business workflows (every business pipeline). In Business workflows, enumerate every business entrypoint — HTTP route, scheduled job, CLI command — with no silent omission: state per-kind counts and the grand total in an enumeration table, each entrypoint pinned to 
file:line
. Then trace each as a course of actions — entrypoint → service calls → side effect/persistence — over the repository ontology. Locate entrypoints with a fast scanner (
rg
/
grep
) and read only the matched handler windows. Lead each flow with a mermaid 
flowchart
(visual; no citations) followed by the authoritative numbered, cited steps. A hop that cannot be resolved statically (dynamic dispatch, indirection) is 
**[unknown]**
with a reason — never dropped. This is the business-process counterpart to the Control-flow traces section: traces are illustrative; this is the exhaustive enumeration.
Presentation format. A specification is read by humans, so favour scannable structure:
  • Use numbered section headings in template order — 
    ## 1. Repository overview
    … 
    ## 19. Evidence index
    .
  • Render inherently tabular sections as Markdown tables with an Evidence column (the 
    path:line
    citation) and a Label column (
    [fact]
    /
    [inference]
    /
    [unknown]
    ): Technology stack, Dependency map, Configuration map, the field list of Data model, and Evidence index.
  • For Control-flow traces and Data-flow traces, lead with a fenced 
    ```mermaid
    flowchart
     depicting the steps end to end, then list the authoritative numbered steps as labeled, cited claims beneath it.
  • Diagrams (
    flowchart
    , 
    erDiagram
    ) are visual aids and carry no citations; every step or entity a diagram shows MUST also appear as a labeled, cited line or table row, so evidence grounding is unaffected by the diagram.
Specification header & quality checklist. Under the title, carry a short header block — Target repository (name · commit), Status, Generated by (skill version · adapter), and a Grounding line — mirroring the structured-spec convention. Alongside the Repository Specification, produce a Specification Quality Checklist from 
templates/repository-specification-checklist.md
at 
.reposkillopt/specs/repository-specification-checklist.md
: a 
CHK###
checklist over grounding, completeness, diagrams, and readiness. Its grounding/completeness/diagram items correspond to the deterministic metrics, so a green checklist should coincide with 100% citation grounding, section completeness, symbol coverage, and diagram grounding.
Working artifacts produced by this skill live under a 
.reposkillopt/
directory at the target repository root (the repository being analyzed, not the project that ships this skill), with fixed subdirectories:
  • .reposkillopt/specs/
    — Repository Specifications
  • .reposkillopt/feedback/
    — Feedback Items
  • .reposkillopt/rollouts/
    — Rollout Logs
  • .reposkillopt/proposals/
    — Skill Edit Proposals
代码库规范模板位于
templates/repository-specification.md
。Agent必须生成符合该模板的文件，所有19个章节按以下顺序排列：
  1. 代码库概述
  2. 技术栈
  3. 构建与运行时命令
  4. 主要入口点
  5. 架构层级
  6. 核心模块
  7. 领域模型
  8. 数据模型
  9. 外部集成
  10. 控制流追踪
  11. 数据流追踪
  12. 依赖映射
  13. 配置映射
  14. 测试策略
  15. 部署假设
  16. 变更影响映射
  17. 已知风险
  18. 未知与未解决问题
  19. 证据索引
设计为空的章节需明确声明“暂无已知内容”或“不适用”——切勿静默省略。“证据索引”列出文档中出现的每个不同引用，去重后呈现。
符号统计（无静默省略）。代码库中定义的每个函数和类都必须被统计：要么在分析断言/引用中提及，要么列在“核心模块”下的**“尚未分析的符号”**子章节中（按文件分组；大型代码库可接受按文件计数）。声明计数——定义N个，分析M个，列出N−M个——以便读者确认没有内容被隐藏。排除生成/第三方依赖目录。
代码库本体（先构建）。在编写“领域模型”和“数据模型”之前，构建代码库的本体：固定类型实体的清单——模块、类、函数、数据实体、路由、任务、抽象——每个实体都关联
file:line
，以及它们之间的关系——导入、继承、外键、注册路由、调度。使用快速扫描工具（可用
rg
，否则回退到
grep
/
git ls-files
）定位它们，仅读取引用的匹配行——不要加载整个文件。在“领域模型”中呈现高级实体映射表（类型 · 数量 · 带引用的示例）和关系
graph
。结构化检测抽象实体——被两个或更多其他类继承的基类——而非从固定的代码库特定名称列表中识别。无法解析到已知实体的关系标记为
**[inference]**
/
**[unknown]**
，且不得绘制为硬边。
数据模型图。当代码库包含数据库或持久化模式时，“数据模型”章节必须包含一个 fenced 
```mermaid
块，其中包含真实表/模型的
erDiagram
——它们的关键列和外键关系——每个实体都可追溯到定义它的模式文件（迁移、DDL或ORM模型）。
erDiagram
是本体的数据实体切片。当没有持久化模式时，声明“不适用”；切勿绘制虚构模式。
业务工作流（每个业务流水线）。在“业务工作流”中，枚举所有业务入口点——HTTP路由、定时任务、CLI命令——无静默省略：在枚举表中声明每种类型的计数和总计，每个入口点都关联
file:line
。然后将每个入口点作为操作流程追踪——入口点 → 服务调用 → 副作用/持久化——基于代码库本体。使用快速扫描工具（
rg
/
grep
）定位入口点，仅读取匹配的处理程序窗口。每个流程前先展示mermaid 
flowchart
（可视化；无引用），然后是权威的编号、带引用的步骤。无法静态解析的跳转（动态调度、间接引用）标记为
**[unknown]**
并说明原因——切勿丢弃。这是“控制流追踪”章节的业务流程对应部分：追踪是示例性的；此部分是详尽枚举。
呈现格式。规范供人类阅读，因此优先采用易于扫描的结构：
  • 使用编号章节标题，遵循模板顺序——
    ## 1. 代码库概述
    … 
    ## 19. 证据索引
    。
  • 将固有表格化章节渲染为Markdown表格，包含证据列（
    path:line
    引用）和标签列（
    [fact]
    /
    [inference]
    /
    [unknown]
    ）：技术栈、依赖映射、配置映射、数据模型的字段列表，以及证据索引。
  • 对于控制流追踪和数据流追踪，先展示fenced 
    ```mermaid
    flowchart
    ，描绘端到端步骤，然后在下方列出权威的编号、带标签和引用的断言。
  • 图表（
    flowchart
    、
    erDiagram
    ）是视觉辅助工具，无引用；图表显示的每个步骤或实体都必须同时出现在带标签和引用的行或表格行中，确保证据基础不受图表影响。
规范头部与质量检查表。标题下方包含一个简短的头部块——目标代码库（名称 · 提交记录）、状态、生成者（技能版本 · 适配器），以及基础行——遵循结构化规范惯例。与代码库规范一起，从
templates/repository-specification-checklist.md
生成规范质量检查表，保存到
.reposkillopt/specs/repository-specification-checklist.md
：一个关于基础、完整性、图表和就绪性的
CHK###
检查表。其基础/完整性/图表项对应确定性指标，因此绿色检查表应对应100%引用基础、章节完整性、符号覆盖和图表基础。
该技能生成的工作工件存储在目标代码库根目录（正在分析的代码库，而非发布该技能的项目）下的
.reposkillopt/
目录中，包含固定子目录：
  • .reposkillopt/specs/
    — 代码库规范
  • .reposkillopt/feedback/
    — 反馈项
  • .reposkillopt/rollouts/
    — 发布日志
  • .reposkillopt/proposals/
    — 技能编辑提案

Human Feedback Loop

人工反馈循环

The Human Feedback template lives at 
templates/human-feedback.md
. The Rollout Log template lives at 
templates/rollout-log.md
.
When a human provides feedback against a Repository Specification:
  1. Record the feedback before applying it. Write a Feedback Item to 
    .reposkillopt/feedback/FB-YYYY-MM-DD-NNN-<slug>.md
    using the template. Assign one of the eleven 
    type
    values (correction, confirmation, missing-context, terminology, quality-rating, avoid-path, deeper-analysis, criticism-of-claim, format, detail-level, cross-agent-difference). Assign a 
    scope
    : 
    repository-scoped
    for facts particular to this codebase; 
    candidate-for-generic
    for patterns that might warrant a future edit to this skill.
  2. Revise the current Repository Specification. Apply the feedback. For changed 
    **[fact]**
    claims, update the citation. For superseded claims, mark them superseded in place; do not silently rewrite history. Increment the spec's 
    revision
    , update 
    revised
    , and append a row to the spec's Change log appendix naming the Feedback Item ids applied.
  3. Update the session's Rollout Log. List the Feedback Item ids under Human feedback received this session, each annotated 
    (applied)
    , 
    (deferred)
    , or 
    (withdrawn)
    . List the revised spec sections under Revisions applied.
  4. Do not silently promote repository-specific facts into this canonical skill. Feedback marked 
    scope: repository-scoped
    stays in the target repository's artifacts only. Promotion to canonical content requires an accepted Skill Edit Proposal, generated through the Skill Convergence Loop below.
Human feedback is used in two ways simultaneously: immediate improvement of the current Repository Specification, and longer-term input to skill convergence.
人工反馈模板位于
templates/human-feedback.md
。发布日志模板位于
templates/rollout-log.md
。
当人类针对代码库规范提供反馈时：
  1. 应用反馈前先记录。使用模板将反馈项写入
    .reposkillopt/feedback/FB-YYYY-MM-DD-NNN-<slug>.md
    。分配11种
    type
    值之一（修正、确认、缺失上下文、术语、质量评级、避免路径、深度分析、断言批评、格式、细节级别、跨Agent差异）。分配
    scope
    ：
    repository-scoped
    针对特定代码库的事实；
    candidate-for-generic
    针对可能需要未来编辑该技能的模式。
  2. 修订当前代码库规范。应用反馈。对于修改后的
    **[fact]**
    断言，更新引用。对于被取代的断言，在原处标记为已取代；切勿静默重写历史。递增规范的
    revision
    ，更新
    revised
    字段，并在规范的“变更日志”附录中添加一行，注明应用的反馈项ID。
  3. 更新会话的发布日志。在“本次会话收到的人工反馈”下列出反馈项ID，每个ID标注
    (applied)
    、
    (deferred)
    或
    (withdrawn)
    。在“应用的修订”下列出修订的规范章节。
  4. 切勿将代码库特定事实静默提升为标准技能内容。标记为
    scope: repository-scoped
    的反馈仅保留在目标代码库的工件中。提升为标准内容需要通过下文技能收敛流程生成的已接受技能编辑提案。
人工反馈同时用于两种用途：立即改进当前代码库规范，以及作为技能收敛的长期输入。

Skill Convergence Loop

技能收敛循环

The Skill Edit Proposal template lives at 
templates/skill-edit-proposal.md
.
When recurrent feedback (typically three or more related Feedback Items across one or more sessions) suggests a weakness in this skill itself:
  1. Summarize the pattern. Identify the recurring shape across the supporting Feedback Items. Confirm that the pattern is generalizable (would help on other repositories or tasks) — not a one-off detail of the current codebase.
  2. Propose one or more bounded edits. Each proposal is a single accept/reject unit, small enough that a reviewer can decide in five minutes or less (
    review_time_estimate_minutes ≤ 5
    ). If a proposal does not fit, split it.
  3. Categorize each proposal. Use one of six 
    edit_kind
    values:
    • ADD
      — add new content
    • REPLACE
      — substitute existing content
    • DELETE
      — remove content
    • REORDER
      — change order of existing content
    • SPECIALIZE
      — narrow an existing rule (more specific case)
    • GENERALIZE
      — broaden an existing rule (cover more cases)
  4. Mark the scope. 
    scope: generic
    is the only kind eligible for canonical acceptance. 
    scope: repository-scoped
    proposals MUST be rewritten to generalize, or rejected, or routed to a per-repository scope-decision artifact.
  5. Preserve rejected proposals. Set 
    status: rejected
    and populate 
    decision_rationale
    . Do not delete — the rejected proposals are part of the audit trail.
  6. Gate before accepting. A 
    scope: generic
    proposal may move to 
    status: accepted
    only after it passes a validation gate: applied to a candidate skill version, it must regenerate specifications for a held-out reference set (disjoint from the repositories whose feedback motivated it) whose per-dimension rubric scores do not regress and whose deterministic checks still pass, with the proposal's expected effect realized on at least one dimension (or explicitly waived). The run is recorded as a Validation Gate Report and referenced by the proposal. The gate authorizes — it does not replace — the acceptance flow below.
  7. Apply accepted proposals to the canonical skill. When 
    status: accepted
    (with a passing gate referenced), the proposal's diff is applied to this 
    SKILL.md
    . The canonical version is bumped per Keep-A-Changelog + semver: major if the diff breaks the adapter-equivalence checklist, minor if additive, patch if clarifying. A row is added to 
    skills/repo-skillopt/CHANGELOG.md
    .
  8. Prefer edits that generalize. When a proposed change would specialize the generic skill to a single repository, flag it or rewrite it. Generalizable improvements outweigh repository-specific ones for this artifact.
技能编辑提案模板位于
templates/skill-edit-proposal.md
。
当循环反馈（通常是一个或多个会话中三个或更多相关反馈项）表明该技能本身存在弱点时：
  1. 总结模式。识别支持反馈项中的重复模式。确认该模式可推广（对其他代码库或任务有帮助）——而非当前代码库的一次性细节。
  2. 提出一个或多个有限编辑。每个提案是一个单独的接受/拒绝单元，足够小，以便审核者在5分钟或更短时间内做出决定（
    review_time_estimate_minutes ≤ 5
    ）。如果提案不符合要求，拆分它。
  3. 对每个提案分类。使用6种
    edit_kind
    值之一：
    • ADD
      — 添加新内容
    • REPLACE
      — 替换现有内容
    • DELETE
      — 删除内容
    • REORDER
      — 更改现有内容顺序
    • SPECIALIZE
      — 缩小现有规则范围（更具体的情况）
    • GENERALIZE
      — 扩大现有规则范围（覆盖更多情况）
  4. 标记范围。
    scope: generic
    是唯一符合标准接受条件的类型。
    scope: repository-scoped
    提案必须重写为通用型，或被拒绝，或路由到每个代码库的范围决策工件。
  5. 保留被拒绝的提案。设置
    status: rejected
    并填充
    decision_rationale
    。请勿删除——被拒绝的提案是审计跟踪的一部分。
  6. 接受前通过验证门。
    scope: generic
    提案只有在通过验证门后才能转为
    status: accepted
    ：应用到候选技能版本后，必须为保留的参考集（与激发反馈的代码库不重叠）重新生成规范，其每个维度的评分表分数不得倒退，且确定性检查仍通过，同时提案的预期效果至少在一个维度上实现（或明确豁免）。运行记录为验证门报告并被提案引用。验证门授权——而非取代——下文的接受流程。
  7. 将已接受的提案应用到标准技能。当
    status: accepted
    （引用通过的验证门）时，将提案的差异应用到本
    SKILL.md
    。根据Keep-A-Changelog + semver提升标准版本：如果差异破坏适配器等效检查表则升主版本，新增内容升次版本，澄清内容升补丁版本。在
    skills/repo-skillopt/CHANGELOG.md
    中添加一行。
  8. 优先选择可推广的编辑。当提议的变更将通用技能特化为单个代码库时，标记它或重写它。对于此工件，可推广的改进优于代码库特定改进。

Output Discipline

输出规范

Every major claim in a Repository Specification (or in any rollout-produced text) carries exactly one of four label prefixes, before the claim:
  • **[fact]**
    — verified by inspection. MUST be immediately followed by at least one citation in one of these forms: 
    • path/to/file.ext:line
    • path/to/file.ext:start-end
    • path/to/file.ext:Symbol
    • path/to/file.ext:Symbol:line
    • cmd: <command>
      followed by 
      output: <verbatim output>
  • **[inference]**
    — derived from partial signal. State the basis (e.g., "basis: presence of 
    flask_login
    import in 
    src/auth.py:7
    ").
  • **[unknown]**
    — explicitly not determined. Also appears (or is referenced) under Unknowns and unresolved questions.
  • **[human]**
    — provided by a human via the feedback loop. Cites the originating Feedback Item id (form: 
    FB-YYYY-MM-DD-NNN
    ).
A hypothesis presented as a fact is a defect. A fact without a citation is a defect. An unverifiable claim that is neither labeled 
**[inference]**
nor 
**[unknown]**
is a defect. The output is meant to be useful to a real engineer — that means trustworthy, not pretty.
Trivial recitations (literal file contents, raw config dumps, syntactic restatements) are not major claims and do not require labels.
代码库规范（或任何发布生成的文本）中的每项重要结论都必须带有以下四个标签前缀之一，位于结论之前：
  • **[fact]**
    — 通过检查验证。必须紧跟至少一个以下形式的引用： 
    • path/to/file.ext:line
    • path/to/file.ext:start-end
    • path/to/file.ext:Symbol
    • path/to/file.ext:Symbol:line
    • cmd: <command>
      后跟 
      output: <verbatim output>
  • **[inference]**
    — 从部分信号推导而来。说明依据（例如“依据：
    src/auth.py:7
    中存在
    flask_login
    导入”）。
  • **[unknown]**
    — 明确未确定。也会出现在（或引用自）“未知与未解决问题”部分。
  • **[human]**
    — 通过反馈循环由人类提供。引用原始反馈项ID（格式：
    FB-YYYY-MM-DD-NNN
    ）。
将假设作为事实呈现是缺陷。无引用的事实是缺陷。既未标记
**[inference]**
也未标记
**[unknown]**
的无法验证断言是缺陷。输出旨在对实际工程师有用——这意味着可信，而非美观。
平凡复述（字面文件内容、原始配置转储、语法重述）不属于重要结论，无需标签。