project-settings

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/project-settings — view or change project config

/project-settings — 查看或更改项目配置

Manages
project.yaml
(team-wide config, committed) and
project.local.yaml
(per-developer overrides, gitignored). Use this skill to inspect current settings or change them without manually editing YAML.
Automation mode: Resolve
modes.automation
(
project.local.yaml
→
project.yaml
→ default
collaborative
). The approval gates in Phase 4 and Phase 5 follow the pattern in
.claude/docs/automation-modes.md
. Note: writing to
project.yaml
is a
schema_changes
decision (a default
automation_always_ask
category), so
/project-settings
confirms config writes even in
autonomous
mode unless the user has removed
schema_changes
from their always-ask list.
管理
project.yaml
(团队级配置,已提交到版本控制)和
project.local.yaml
(单个开发者的覆盖配置,被 gitignore)。使用此 skill 检查当前设置或直接更改设置,无需手动编辑 YAML。
自动化模式:解析
modes.automation
(
project.local.yaml
→
project.yaml
→ 默认值
collaborative
)。第 4 阶段和第 5 阶段中的审批门控遵循
.claude/docs/automation-modes.md
中的模式。注意:写入
project.yaml
是一项
schema_changes
决策(默认属于
automation_always_ask
类别),因此即使处于
autonomous
模式,
/project-settings
也会在写入配置前请求确认,除非用户已从其 always-ask 列表中移除
schema_changes
。

Phase 0: Parse Arguments

阶段 0:解析参数

Determine which of the four forms the user invoked:
FormMode
/project-settings
(no args)
View-all (Phase 2)
/project-settings <key>
(single arg, no
=
)
View-one (Phase 3)
/project-settings <key>=<value>
(single arg with
=
)
Set-yaml (Phase 4)
/project-settings --local <key>=<value>
(
--local
prefix)
Set-local (Phase 5)
For Set-yaml and Set-local,
<key>
is a dotted YAML path (e.g.
modes.review_mode
,
testing.strict.logic
) and
<value>
is the new value.
Empty-operand validation: After splitting the
key=value
operand on
=
, if either
<key>
or
<value>
is empty, this is malformed — route to Phase 6 (usage) rather than attempting the write. The rule applies in both Set-yaml and Set-local routing: for
--local
, strip the
--local
token first, then check the remaining operand the same way (so
/project-settings --local =foo
and
/project-settings --local key=
both go to Phase 6).
Anything else that doesn't match the four forms above → Phase 6 (usage).
确定用户使用的是以下四种形式中的哪一种:
形式模式
/project-settings
(无参数)
查看全部(阶段 2)
/project-settings <key>
(单个参数,不含
=
)
查看单项(阶段 3)
/project-settings <key>=<value>
(单个参数且包含
=
)
设置 YAML(阶段 4)
/project-settings --local <key>=<value>
(带
--local
前缀)
设置本地配置(阶段 5)
对于设置 YAML 和设置本地配置模式,
<key>
是点分 YAML 路径(例如
modes.review_mode
、
testing.strict.logic
),
<value>
是新值。
空操作数校验:按
=
拆分
key=value
操作数后,如果
<key>
或
<value>
为空,则格式错误——应进入阶段 6(用法),而不是尝试写入。此规则同时适用于设置 YAML 和设置本地配置模式:对于
--local
,先移除
--local
标记,然后以相同方式检查剩余操作数(因此
/project-settings --local =foo
和
/project-settings --local key=
都应进入阶段 6)。
任何不符合上述四种形式的内容 → 阶段 6(用法)。

Phase 1: Load Helper

阶段 1:加载 Helper

All four subcommands need
yaml-helper.sh
. Run each helper call as its own plain command:
bash
bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" <helper call>
<helper call>
is the function each phase below names, for example
resolve_setting modes.review_mode
or
validate_yaml_enum project.yaml
. The helper moves to the project root itself, so those
project.yaml
and
project.local.yaml
arguments resolve when the session was started in a subfolder, and it keeps the function's exit status.
is_locally_overridable
also prints its
0
or
1
. Run the call exactly as shown: do not
source
the file, wrap it in
cd ... &&
or append
; echo $?
. This skill pre-approves the plain form only, and a compound command asks the user every time.
If
.claude/hooks/yaml-helper.sh
is missing, this is not a Claude Code Game Studios project. Report the error and exit.
所有四个子命令都需要
yaml-helper.sh
。每次 helper 调用都应作为独立的普通命令运行:
bash
bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" <helper call>
<helper call>
是下文各阶段所指定的函数调用,例如
resolve_setting modes.review_mode
或
validate_yaml_enum project.yaml
。helper 会自行切换到项目根目录,因此即使会话是从子目录启动,传入的
project.yaml
和
project.local.yaml
参数也能正确解析,并且它会保留函数的退出状态。
is_locally_overridable
还会打印
0
或
1
。严格按所示方式运行调用:不要
source
该文件,不要用
cd ... &&
包裹,也不要追加
; echo $?
。此 skill 仅预先批准普通形式;复合命令每次都会询问用户。
如果
.claude/hooks/yaml-helper.sh
不存在,则当前目录不是 Claude Code Game Studios 项目。报告该错误并退出。

Phase 1b: Reserved-setting detection

阶段 1b:检测保留设置

Some settings are fully documented and settable, and no skill or hook reads them — setting one changes nothing. This skill must say so. Returning an ordinary success lets a user reasonably believe the behaviour the setting describes is now enforced — an accessibility tier being the case that motivates this. (The key is not named here on purpose; see the note below.) The banner exists only in
.claude/docs/effects-map.md
, which someone configuring their project will never open. A setting that does nothing must never look exactly like one that works —
.claude/rules/skill-authoring.md
obligation 3.
Derive the set; do not hardcode it (obligation 5):
bash
grep -B14 '^> ### RESERVED' .claude/docs/effects-map.md | grep -E '^## '
Match the banner HEADING (
> ### RESERVED
), never the bare word "RESERVED".
platform.cert_tier
's section mentions the banner in prose, to record that it carried one and later became a live setting. A looser match re-reports a working setting as dead — the direction that understates what the framework does, and why the dead-settings gate asserts both directions.
A heading may name two keys joined by " and " — split on that separator so both are captured, or the second one silently escapes the set. Let
RESERVED_SET
be the result.
Deliberately phrased without naming those keys. The dead-settings gate asserts that a setting on the allowlist has no readers, and it counts any skill file that spells the key. Naming them here to illustrate the split would make
/project-settings
register as a reader of two settings nothing reads, and the gate would fail — correctly. Spelling a dead path out while explaining why not to use it trips the same wire. Reword instead of adding an exemption: the strictness is the point, so do not re-introduce the literal names to make an example clearer.
Never refuse a write to a reserved key. Storing the value a user intends is legitimate; storing it silently is the defect.
有些设置已有完整文档且可以设置,但没有任何 skill 或 hook 读取它们——设置这些项不会产生任何变化。此 skill 必须明确说明这一点。 返回普通的成功结果会让用户合理地以为该设置所描述的行为现已生效——无障碍等级正是促成此要求的情形。(这里故意不写出该键名;请参阅下方说明。)该横幅仅存在于
.claude/docs/effects-map.md
中,而配置项目的人永远不会打开它。无效的设置绝不能看起来与有效的设置完全一样——这是
.claude/rules/skill-authoring.md
义务 3 的要求。
应派生该集合,不要将其硬编码(义务 5):
bash
grep -B14 '^> ### RESERVED' .claude/docs/effects-map.md | grep -E '^## '
务必匹配横幅标题(
> ### RESERVED
),绝不能只匹配裸词“RESERVED”。
platform.cert_tier
所在章节在正文中提到了该横幅,用于记录它曾经拥有横幅、后来成为有效设置的情况。过于宽松的匹配会再次将有效设置报告为无效设置——这种方向会低估框架实际提供的能力,而失效设置门控正是要同时断言两个方向。
一个标题可能会命名两个以“ and ”连接的键——应按该分隔符拆分,以同时捕获两者,否则第二个键会悄然逃出集合。令结果为
RESERVED_SET
。
特意采用不包含这些键名的表述。失效设置门控会断言允许列表中的设置没有读取方,并统计任何明确拼写出该键的 skill 文件。如果在这里为说明拆分方式而命名这些键,
/project-settings
就会被登记为两个无人读取的设置的读取方,门控也会因此失败——这是正确行为。在解释原因时写出一个无效路径,同样会触发这条规则。应当改写措辞,而不是添加例外:严格性正是目的所在,因此不要为了让示例更清晰而重新引入字面键名。
绝不要拒绝写入保留键。存储用户想要的值是合理行为;静默存储才是缺陷。

Phase 2: View-all Mode

阶段 2:查看全部模式

(when no arguments)
  1. Confirm
    project.yaml
    exists. If missing, report:
    "No
    project.yaml
    found — run
    /start
    to create one." And exit.
  2. Check if
    project.local.yaml
    exists.
  3. Run
    validate_yaml_enum project.yaml
    and capture any errors. If
    project.local.yaml
    exists, also run
    validate_yaml_enum project.local.yaml
    . Tag each error with its source file so the user can tell them apart.
  4. Enumerate leaves. Read both YAML files as text. Walk through each file's structure and collect every leaf key into a deduplicated list of dotted paths. A leaf is a
    key: value
    line whose value is non-empty (a scalar or inline-array) — NOT a parent block that introduces a nested map. Maintain insertion order per file; merge by appending leaves from
    project.local.yaml
    that aren't already present from
    project.yaml
    . The resulting list is the set of leaves to display.
    Then append the rigor family —
    modes.rigor
    ,
    modes.workflow
    ,
    docs.density
    ,
    qa.level
    ,
    modes.story_granularity
    ,
    modes.review_mode
    ,
    team.size
    — for any of the seven the merged list does not already contain. These are normally leaves of neither file:
    modes.rigor
    has a terminal default and the other six are supplied by the rigor expansion (
    modes.review_mode
    and
    team.size
    may also appear as file leaves when set locally, but must still be appended so their derived value shows). Enumerating only file leaves would hide exactly the settings a user just chose, in the one view meant to show them.
  5. For each leaf, perform three reads and one check:
    • resolve_setting <path>
      →
      <value>
      , TAB,
      <source>
      . This walks the whole chain (
      project.local.yaml
      →
      project.yaml
      → legacy file →
      rigor
      expansion → default), so it is the only read that can report a derived value or name what supplied it.
    • get_yaml_key project.yaml <path>
      → yaml-only value (needed only to show what a local override is shadowing)
    • is_locally_overridable <path>
      → 0 (overridable) or 1 (locked)
    Compute the source annotation from
    <source>
    :
    <source>
    Annotation
    project.local.yaml
    , yaml-only value non-empty
    (LOCAL OVERRIDE — yaml has: <yamlvalue>)
    project.local.yaml
    , yaml-only value empty
    (project.local.yaml)
    project.yaml
    (project.yaml)
    a legacy file path (e.g.
    production/review-mode.txt
    )
    (<path>, legacy)
    rigor:<level>
    (derived from rigor: <level>)
    default
    (default)
    unset
    skip the leaf (don't print unset keys)
    Append
    , locked
    to the annotation when
    is_locally_overridable
    returned 1.
    Append
    , reserved
    when the leaf is in
    RESERVED_SET
    (Phase 1b)
    , and print this line with the legend below the block:
    reserved = stored, but nothing reads it. Setting it changes
    no behaviour today.
    All four phases must carry the reserved marking — view-one, view-all, and both write paths. Marking view-one and the writes while leaving view-all — the most-used form of this skill — unmarked means a user who set a reserved key sees it listed beside working settings with an ordinary
    (project.yaml)
    annotation, in the view most people actually run. Guard all four: view-one and view-all are twins in exactly the way the two write paths are.
  6. Print, grouped by top-level section (
    framework
    ,
    modes
    ,
    engine
    , etc.) in the order leaves first appeared. The grouping is determined by the dotted path, not by which file the leaf came from — e.g.
    modes.automation
    groups under
    modes:
    even if only
    project.local.yaml
    defines it. Within each section, indent leaves by 2 spaces; nest further for sub-blocks (e.g.
    testing.strict.*
    ). Example output:
project.yaml: present
project.local.yaml: present

Schema validation: ok

Effective config:

framework:
  version: 1.3.0            (project.yaml, locked)

modes:
  review_mode: lean         (project.yaml)
  automation: autonomous    (LOCAL OVERRIDE — yaml has: collaborative)
  rigor: full               (project.yaml, locked)
  workflow: full            (derived from rigor: full, locked)
  story_granularity: fine   (derived from rigor: full, locked)

docs:
  density: terse            (project.yaml, locked)

qa:
  level: full               (derived from rigor: full, locked)

engine:
  name: Godot               (project.yaml, locked)
  version: 4.7              (project.yaml, locked)

testing:
  strict:
    logic: false            (LOCAL OVERRIDE — yaml has: true)
    integration: true       (project.yaml)

locked = cannot be overridden in project.local.yaml (project-wide setting).
It does NOT mean fixed: a derived value can still be set explicitly with
/project-settings <key>=<value>, and an explicit value wins over rigor.
Print that two-line legend after the config block whenever any rendered line carries
locked
. Without it users read
locked
as "immutable" and conclude a rigor-derived knob cannot be changed — the opposite of what Phase 3's view-one tells them for the same knob ("an explicit value wins over rigor"). The two views must not leave contradictory impressions of the same knob's mutability.
The
docs.density
line above is the precedence rule made visible: an explicit
project.yaml
value keeps winning over the level
rigor
would otherwise derive, so "comprehensive but compact" stays expressible.
If schema errors exist, print them in this form before the effective config block:
Schema validation: ERRORS
  [project.yaml] modes.review_mode: 'chaotic' is not a valid value (expected: full|lean|solo)
  [project.local.yaml] engine.name: 'Pygame' is not a valid value (expected: Godot|Unity|Unreal|Web)
(无参数时)
  1. 确认
    project.yaml
    存在。如果不存在,报告:
    “No
    project.yaml
    found — run
    /start
    to create one.” 然后退出。
  2. 检查
    project.local.yaml
    是否存在。
  3. 运行
    validate_yaml_enum project.yaml
    并捕获所有错误。如果
    project.local.yaml
    存在,也运行
    validate_yaml_enum project.local.yaml
    。为每个错误标记其来源文件,以便用户区分。
  4. 枚举叶节点。 将两个 YAML 文件作为文本读取。遍历每个文件的结构,将每个叶节点键收集到去重后的点分路径列表中。叶节点是值非空(标量或内联数组)的
    key: value
    行,而不是引入嵌套映射的父级块。按文件维护插入顺序;合并时,追加
    project.local.yaml
    中尚未出现在
    project.yaml
    中的叶节点。最终列表即待显示的叶节点集合。
    然后追加 rigor 系列——
    modes.rigor
    、
    modes.workflow
    、
    docs.density
    、
    qa.level
    、
    modes.story_granularity
    、
    modes.review_mode
    、
    team.size
    ——即使用合并列表中尚未包含这七项中的任何一项,也必须追加。它们通常不是两个文件中的叶节点:
    modes.rigor
    具有终端默认值,其他六项由 rigor 扩展提供(当在本地设置时,
    modes.review_mode
    和
    team.size
    也可能作为文件叶节点出现,但仍必须追加,以显示其派生值)。如果只枚举文件叶节点,就会恰好隐藏用户刚刚选择的设置,而这个视图本应专门用于展示它们。
  5. 对每个叶节点执行三次读取和一次检查:
    • resolve_setting <path>
      →
      <value>
      、TAB、
      <source>
      。这会遍历整个链条(
      project.local.yaml
      →
      project.yaml
      → 旧版文件 →
      rigor
      扩展 → 默认值),因此这是唯一能够报告派生值或指出其来源的读取方式。
    • get_yaml_key project.yaml <path>
      → 仅 YAML 中的值(仅用于显示本地覆盖所遮蔽的值)。
    • is_locally_overridable <path>
      → 0(允许覆盖)或 1(已锁定)。
    根据
    <source>
    计算来源标注:
    <source>
    标注
    project.local.yaml
    ,仅 YAML 的值非空
    (LOCAL OVERRIDE — yaml has: <yamlvalue>)
    project.local.yaml
    ,仅 YAML 的值为空
    (project.local.yaml)
    project.yaml
    (project.yaml)
    旧版文件路径(例如
    production/review-mode.txt
    )
    (<path>, legacy)
    rigor:<level>
    (derived from rigor: <level>)
    default
    (default)
    unset
    跳过该叶节点(不要打印未设置的键)
    当
    is_locally_overridable
    返回 1 时,在标注后追加
    , locked
    。
    当叶节点位于
    RESERVED_SET
    中时(阶段 1b),追加
    , reserved
    ,并在配置块下方使用以下图例:
    reserved = stored, but nothing reads it. Setting it changes
    no behaviour today.
    所有四个阶段都必须带有保留标记——查看单项、查看全部以及两条写入路径。 如果只标记查看单项和写入,却不标记查看全部——这个 skill 最常用的形式——用户就会看到自己设置的保留键与有效设置并列显示,并带有普通的
    (project.yaml)
    标注。请保护全部四条路径:查看单项和查看全部在写入路径完全相同的方式上互为对应。
  6. 打印,按顶层分区(
    framework
    、
    modes
    、
    engine
    等)分组,顺序采用叶节点首次出现的顺序。分组依据是点分路径,而不是叶节点来自哪个文件——例如,即使只有
    project.local.yaml
    定义了
    modes.automation
    ,它仍会归入
    modes:
    。在每个分区内,叶节点缩进 2 个空格;更深层级的子块继续嵌套(例如
    testing.strict.*
    )。输出示例:
project.yaml: present
project.local.yaml: present

Schema validation: ok

Effective config:

framework:
  version: 1.3.0            (project.yaml, locked)

modes:
  review_mode: lean         (project.yaml)
  automation: autonomous    (LOCAL OVERRIDE — yaml has: collaborative)
  rigor: full               (project.yaml, locked)
  workflow: full            (derived from rigor: full, locked)
  story_granularity: fine   (derived from rigor: full, locked)

docs:
  density: terse            (project.yaml, locked)

qa:
  level: full               (derived from rigor: full, locked)

engine:
  name: Godot               (project.yaml, locked)
  version: 4.7              (project.yaml, locked)

testing:
  strict:
    logic: false            (LOCAL OVERRIDE — yaml has: true)
    integration: true       (project.yaml)

locked = cannot be overridden in project.local.yaml (project-wide setting).
It does NOT mean fixed: a derived value can still be set explicitly with
/project-settings <key>=<value>, and an explicit value wins over rigor.
只要任何渲染行带有
locked
,就在配置块后打印这两行图例。否则,用户会把
locked
理解为“不可变”,进而认为 rigor 派生的选项无法更改——这与阶段 3 的查看单项结果恰好相反,后者会说明同一个选项可以修改(“显式值优先于 rigor”)。两个视图不得对同一选项的可修改性留下相互矛盾的印象。
上面的
docs.density
行直观展示了优先级规则:
project.yaml
中的显式值继续优先于
rigor
本来会派生的级别,因此“内容全面但紧凑”仍然可以表达。
如果存在 schema 错误,请在有效配置块之前按以下形式打印:
Schema validation: ERRORS
  [project.yaml] modes.review_mode: 'chaotic' is not a valid value (expected: full|lean|solo)
  [project.local.yaml] engine.name: 'Pygame' is not a valid value (expected: Godot|Unity|Unreal|Web)

Phase 3: View-one Mode

阶段 3:查看单项模式

(when single arg, no
=
)
If
<key>
is in
RESERVED_SET
, print this BEFORE the value block
— above, not below. A caveat under a value reads as a footnote on a working setting:
<key>
is RESERVED — nothing reads it.
The value below is stored; it changes no behaviour today.
Let
<key>
be the argument. Perform four reads:
  1. resolve_setting <key>
    →
    <value>
    , TAB,
    <source>
    (effective value + provenance)
  2. get_yaml_key project.yaml <key>
    → yaml-only value
  3. get_yaml_key project.local.yaml <key>
    → local-only value (skip if file absent)
  4. is_locally_overridable <key>
    → 0 (overridable) or 1 (locked)
Determine the source from
<source>
(same table as Phase 2 step 5) and the Locally overridden status:
  • yes
    if the local-only value is non-empty
  • no
    otherwise
Print:
<key>

  Effective value: <effective-value or "(not set)" if <source> is unset>
  Source: <project.yaml | project.local.yaml | project.local.yaml (overrides project.yaml) | derived from rigor: <level> | default>
  Locally overridden: <yes | no>
  Whitelist: <"can be locally overridden" if is_locally_overridable returned 0, else "locked — project-wide">
When both files set the key (the LOCAL OVERRIDE case), add two more lines under Source:
  project.yaml value: <yamlvalue>
  project.local.yaml value: <localvalue>
When
<source>
is
rigor:<level>
, add one line under Source so the user knows the value is settable and how:
  Set explicitly with: /project-settings <key>=<value>   (an explicit value wins over rigor)
When the effective value is empty (key not set anywhere), print just:
<key>

  Effective value: (not set)
  Locally overridden: no
  Whitelist: <"can be locally overridden" | "locked — project-wide">
(单个参数且不含
=
时)
如果
<key>
位于
RESERVED_SET
中,请在值块之前打印以下内容
——必须放在上方,而不是下方。位于值下方的警告会被理解为有效设置的脚注:
<key>
is RESERVED — nothing reads it.
The value below is stored; it changes no behaviour today.
令
<key>
为传入参数。执行四次读取:
  1. resolve_setting <key>
    →
    <value>
    、TAB、
    <source>
    (有效值及来源)
  2. get_yaml_key project.yaml <key>
    → 仅 YAML 中的值
  3. get_yaml_key project.local.yaml <key>
    → 仅本地文件中的值(文件不存在时跳过)
  4. is_locally_overridable <key>
    → 0(允许覆盖)或 1(已锁定)
根据
<source>
确定来源(与阶段 2 第 5 步的表相同),并确定本地覆盖状态:
  • 仅本地文件中的值非空时为
    yes
  • 否则为
    no
打印:
<key>

  Effective value: <effective-value or "(not set)" if <source> is unset>
  Source: <project.yaml | project.local.yaml | project.local.yaml (overrides project.yaml) | derived from rigor: <level> | default>
  Locally overridden: <yes | no>
  Whitelist: <"can be locally overridden" if is_locally_overridable returned 0, else "locked — project-wide">
当两个文件都设置了该键(LOCAL OVERRIDE 情况)时,在 Source 下额外添加两行:
  project.yaml value: <yamlvalue>
  project.local.yaml value: <localvalue>
当
<source>
为
rigor:<level>
时,在 Source 下添加一行,让用户知道该值可以设置以及设置方式:
  Set explicitly with: /project-settings <key>=<value>   (an explicit value wins over rigor)
当有效值为空(任何位置都未设置该键)时,只打印:
<key>

  Effective value: (not set)
  Locally overridden: no
  Whitelist: <"can be locally overridden" | "locked — project-wide">

Phase 4: Set-yaml Mode

阶段 4:设置 YAML 模式

(when
<key>=<value>
, no
--local
)
  1. Schema validation: call
    validate_enum_value <key> <value>
    . If it returns 1, the stderr line is shown to the user verbatim (
    Invalid value '<value>' for '<key>'. Allowed: ...
    ) and the skill exits without writing. If it returns 0, the value is either valid or the key has no enum constraint — proceed.
1b. Known-key check: run, from the project root as in Phase 1,
bash .claude/scripts/config-set.sh <key> <value> --dry-run
and read its
known
row. If it says
yes
, proceed. If it says
no
, nothing in Claude Code Game Studios reads that key, so writing it changes nothing; it is most often a typo. Do not write yet: say so, and ask with the question tool, with the options
Use <nearest> instead
(only when the row ends
nearest: <key>
),
Write <key> anyway
,
Cancel
. Continue only on an explicit choice; with
Use <nearest> instead
, start this phase again with that key. A skipped or empty answer cancels.
  1. Reserved warning: if
    <key>
    is in
    RESERVED_SET
    (Phase 1b), print BEFORE the approval prompt:
    "Note:
    <key>
    is RESERVED — no skill or hook reads it, so setting it will not change any behaviour. Your value is stored either way."
    Then continue to the approval gate as normal. Phase 5 carries the identical warning. Warning on one write path and not the other leaves a silent route to the same outcome, which is the whole failure this guards against.
  2. Shadow warning: read
    get_yaml_key project.local.yaml <key>
    . If it returns a non-empty value, print BEFORE the approval prompt:
    "Note: this setting is currently locally overridden in
    project.local.yaml
    (value:
    <localvalue>
    ). Writing to
    project.yaml
    will not change your effective value."
  3. Approval gate: ask with the question tool:
    • Prompt:
      Set `<key>=<value>` in `project.yaml`?
    • Options:
      [A] Yes, write
      /
      [B] No, cancel
    When
    <key>
    is
    engine.name
    , the same write points CLAUDE.md's
    ENGINE-REFERENCE-IMPORT
    line at
    @docs/engine-reference/<engine>/VERSION.md
    (the value's first word, lowercased), inserting it right after the marker comment's closing
    -->
    when there is none yet, so no session loads another engine's reference: name
    CLAUDE.md
    in the prompt too. The rest of an engine (its version, folders and Technology Stack) is
    /setup-engine
    's: say so in one line.
  4. Write: edit
    project.yaml
    in place. The edit strategy depends on what already exists in
    project.yaml
    :
    Case A — key exists: Read
    project.yaml
    . Locate the line
    <lastsegment>: <oldvalue>
    and the line immediately above it that introduces its parent block (e.g.
    modes:
    for
    modes.review_mode
    ). Make the edit's old text include the parent block line PLUS the leaf line, so the match is unique even if
    <lastsegment>: <oldvalue>
    appears elsewhere. Example for
    modes.review_mode=full
    :
    old_string:
      modes:
        review_mode: lean
    new_string:
      modes:
        review_mode: full
    Case B — parent block exists, leaf doesn't: Find the last line of the parent block. Append the new leaf line at the correct indentation, using the last existing leaf as the
    old_string
    anchor.
    Case C — parent block doesn't exist: Append a new top-level block at end-of-file (deterministic — always end-of-file, never between blocks). Use the last non-empty line of the file as the anchor and append the new block after it.
    Case D — file structure is unusual (commented-out keys with the same name, ambiguous nesting, malformed YAML): STOP and ask with the question tool:
    "Couldn't find a clean insertion point for
    <key>
    in
    project.yaml
    . Show me what to do."
  5. Confirm:
    Set `<key>=<value>` in `project.yaml`.
    When
    <key>
    is
    modes.rigor
    , the write also moves six other knobs, so print what they resolve to now — re-read each with
    resolve_setting
    rather than reciting the expansion table, since any of them may carry an explicit value that still wins:
    Set modes.rigor=full in project.yaml. It now supplies:
      modes.workflow: full            (derived from rigor: full)
      docs.density: terse             (project.yaml — explicit, unchanged)
      qa.level: full                  (derived from rigor: full)
      modes.story_granularity: fine   (derived from rigor: full)
      modes.review_mode: full         (derived from rigor: full)
      team.size: studio               (derived from rigor: full)
(
<key>=<value>
且不含
--local
时)
  1. Schema 校验:调用
    validate_enum_value <key> <value>
    。如果返回 1,则向用户逐字显示 stderr 行(
    Invalid value '<value>' for '<key>'. Allowed: ...
    ),并且 skill 在不写入的情况下退出。如果返回 0,则该值有效,或者该键没有枚举约束——继续执行。
1b. 已知键检查:从项目根目录运行(与阶段 1 相同):
bash .claude/scripts/config-set.sh <key> <value> --dry-run
,并读取其
known
行。如果显示
yes
,则继续。如果显示
no
,说明 Claude Code Game Studios 中没有任何内容读取该键,因此写入它不会产生任何变化;这通常是拼写错误。不要立即写入:应说明这一点,并使用 question tool 询问,提供以下选项:
Use <nearest> instead
(仅当该行以
nearest: <key>
结尾时提供)、
Write <key> anyway
、
Cancel
。只有在用户明确选择后才能继续;如果选择
Use <nearest> instead
,则使用该键重新开始本阶段。跳过或提供空答案将取消操作。
  1. 保留警告:如果
    <key>
    位于
    RESERVED_SET
    中(阶段 1b),请在审批提示之前打印:
    “Note:
    <key>
    is RESERVED — no skill or hook reads it, so setting it will not change any behaviour. Your value is stored either way.”
    然后照常进入审批门控。阶段 5 使用完全相同的警告。如果只在一条写入路径上警告而不在另一条上警告,就会留下一个静默写入路径,而它可能产生相同结果——这正是此机制要防范的失败。
  2. 遮蔽警告:读取
    get_yaml_key project.local.yaml <key>
    。如果返回非空值,请在审批提示之前打印:
    “Note: this setting is currently locally overridden in
    project.local.yaml
    (value:
    <localvalue>
    ). Writing to
    project.yaml
    will not change your effective value.”
  3. 审批门控:使用 question tool 询问:
    • 提示:
      Set `<key>=<value>` in `project.yaml`?
    • 选项:
      [A] Yes, write
      /
      [B] No, cancel
    当
    <key>
    为
    engine.name
    时,同一次写入还会将 CLAUDE.md 的
    ENGINE-REFERENCE-IMPORT
    行指向
    @docs/engine-reference/<engine>/VERSION.md
    (取该值的第一个单词并转换为小写),插入到标记注释的结束符
    -->
    之后;如果尚未插入该行,以确保没有会话加载其他引擎的参考文档。还要在提示中提及
    CLAUDE.md
    。引擎的其余部分(版本、文件夹和 Technology Stack)由
    /setup-engine
    负责:用一行说明这一点。
  4. 写入:就地编辑
    project.yaml
    。编辑策略取决于
    project.yaml
    中已经存在的内容:
    情况 A——键已存在:读取
    project.yaml
    。定位
    <lastsegment>: <oldvalue>
    行,以及其正上方引入父级块的行(例如
    modes.review_mode
    对应的
    modes:
    )。编辑的 old text 必须同时包含父级块行和叶节点行,以确保匹配唯一,即使
    <lastsegment>: <oldvalue>
    出现在其他位置也不会产生歧义。
    modes.review_mode=full
    的示例:
    old_string:
      modes:
        review_mode: lean
    new_string:
      modes:
        review_mode: full
    情况 B——父级块存在,但叶节点不存在:找到父级块的最后一行。在正确的缩进位置追加新的叶节点行,并使用最后一个现有叶节点作为
    old_string
    锚点。
    情况 C——父级块不存在:在文件末尾追加一个新的顶层块(采用确定性方式——始终追加到文件末尾,绝不插入两个块之间)。使用文件的最后一个非空行作为锚点,并在其后追加新块。
    情况 D——文件结构异常(存在同名但已注释的键、嵌套关系有歧义或 YAML 格式错误):停止操作,并使用 question tool 询问:
    “Couldn't find a clean insertion point for
    <key>
    in
    project.yaml
    . Show me what to do.”
  5. 确认:
    Set `<key>=<value>` in `project.yaml`.
    当
    <key>
    为
    modes.rigor
    时
    ,此次写入还会改变另外六个选项,因此应打印它们当前解析出的值——重新使用
    resolve_setting
    读取每一项,而不是照抄扩展表,因为其中任何一项都可能仍带有优先的显式值:
    Set modes.rigor=full in project.yaml. It now supplies:
      modes.workflow: full            (derived from rigor: full)
      docs.density: terse             (project.yaml — explicit, unchanged)
      qa.level: full                  (derived from rigor: full)
      modes.story_granularity: fine   (derived from rigor: full)
      modes.review_mode: full         (derived from rigor: full)
      team.size: studio               (derived from rigor: full)

Phase 5: Set-local Mode

阶段 5:设置本地配置模式

(when
--local <key>=<value>
)
  1. Whitelist check: call
    is_locally_overridable <key>
    .
    • If it returns 1 (locked), print one line:
      <key> cannot be locally overridden — it's a project-wide setting. Use `/project-settings <key>=<value>` (no `--local`) to change it for the whole team.
    • Exit without writing.
  2. Schema validation: call
    validate_enum_value <key> <value>
    . If it returns 1, show the stderr message verbatim and exit without writing.
2a. Known-key check: as in Phase 4 step 1b, with
--local
before
<key>
: if the
known
row says
no
, ask before writing, offering the
nearest:
key when the row names one.
2b. Reserved warning: if
<key>
is in
RESERVED_SET
(Phase 1b), print BEFORE the approval prompt:
"Note:
<key>
is RESERVED — no skill or hook reads it, so setting it will not change any behaviour. Your value is stored either way."
Identical to Phase 4 step 2, and deliberately so. Both write paths reach the same file-of-record for a user's intent; warning on one only would leave
--local
as the silent route.
  1. Base check: if
    project.yaml
    doesn't exist:
    "Cannot create
    project.local.yaml
    —
    project.yaml
    is missing. Run
    /start
    to create one first." Exit. (Local overrides require a base, per spec.)
  2. Approval gate: ask with the question tool:
    • Prompt:
      Set `<key>=<value>` in `project.local.yaml` (your personal override, gitignored)?
    • Options:
      [A] Yes, write
      /
      [B] No, cancel
  3. Write:
    • If
      project.local.yaml
      doesn't exist, create it with the new setting wrapped in its parent block(s). Minimal example for
      --local modes.automation=autonomous
      :
      yaml
      # project.local.yaml — per-developer overrides (gitignored)
      modes:
        automation: autonomous
    • If it exists, edit it with the same Case A/B/C strategy as Phase 4 step 5.
  4. Confirm:
    Set `<key>=<value>` in `project.local.yaml` (your override).
(
--local <key>=<value>
时)
  1. 白名单检查:调用
    is_locally_overridable <key>
    。
    • 如果返回 1(已锁定),打印一行:
      <key> cannot be locally overridden — it's a project-wide setting. Use `/project-settings <key>=<value>` (no `--local`) to change it for the whole team.
    • 不写入并退出。
  2. Schema 校验:调用
    validate_enum_value <key> <value>
    。如果返回 1,则逐字显示 stderr 消息,不写入并退出。
2a. 已知键检查:与阶段 4 第 1b 步相同,但在
<key>
前加上
--local
:如果
known
行显示
no
,则在写入前询问,并在该行提供键名时提供
nearest:
键。
2b. 保留警告:如果
<key>
位于
RESERVED_SET
中(阶段 1b),请在审批提示之前打印:
“Note:
<key>
is RESERVED — no skill or hook reads it, so setting it will not change any behaviour. Your value is stored either way.”
这与阶段 4 第 2 步完全相同,且是刻意如此。两条写入路径最终都会将用户的意图记录到同一个权威文件中;如果只警告其中一条,就会让
--local
成为静默路径。
  1. 基础配置检查:如果
    project.yaml
    不存在:
    “Cannot create
    project.local.yaml
    —
    project.yaml
    is missing. Run
    /start
    to create one first.” 退出。(按照规范,本地覆盖必须以基础配置为前提。)
  2. 审批门控:使用 question tool 询问:
    • 提示:
      Set `<key>=<value>` in `project.local.yaml` (your personal override, gitignored)?
    • 选项:
      [A] Yes, write
      /
      [B] No, cancel
  3. 写入:
    • 如果
      project.local.yaml
      不存在,则创建该文件,将新设置放入其父级块中。例如
      --local modes.automation=autonomous
      :
      yaml
      # project.local.yaml — per-developer overrides (gitignored)
      modes:
        automation: autonomous
    • 如果文件已经存在,则使用与阶段 4 第 5 步相同的情况 A/B/C 策略进行编辑。
  4. 确认:
    Set `<key>=<value>` in `project.local.yaml` (your override).

Phase 6: Usage

阶段 6:用法

When the argument doesn't match any of the four valid forms (or has empty operands), print:
Usage:
  /project-settings                          — view all effective config
  /project-settings <key>                    — view a single setting
  /project-settings <key>=<value>            — change a setting (project.yaml)
  /project-settings --local <key>=<value>    — change a setting locally
                                       (project.local.yaml, gitignored)

Examples:
  /project-settings modes.review_mode
  /project-settings modes.review_mode=full
  /project-settings --local modes.automation=autonomous
当参数不符合四种有效形式之一,或操作数为空时,打印:
Usage:
  /project-settings                          — view all effective config
  /project-settings <key>                    — view a single setting
  /project-settings <key>=<value>            — change a setting (project.yaml)
  /project-settings --local <key>=<value>    — change a setting locally
                                       (project.local.yaml, gitignored)

Examples:
  /project-settings modes.review_mode
  /project-settings modes.review_mode=full
  /project-settings --local modes.automation=autonomous

Notes

注意事项

  • All YAML writes are edits in place (existing keys and blocks) or a new file. The skill does not depend on
    yq
    or any external YAML library.
  • The whitelist is enforced in
    yaml-helper.sh
    (
    is_locally_overridable
    function). To extend it, edit the
    _yaml_helper_locally_overridable
    constant — do not duplicate the list here.
  • Derived values are not stored anywhere.
    modes.workflow
    ,
    docs.density
    ,
    qa.level
    ,
    modes.story_granularity
    ,
    modes.review_mode
    and
    team.size
    have no terminal default; when no file sets them their value comes from the
    modes.rigor
    expansion in
    yaml-helper.sh
    (
    _yaml_helper_rigor_expansion
    ). Report them via
    resolve_setting
    — a
    get_yaml_key
    read returns empty and would render them "(not set)" while every skill is in fact acting on a real value.
  • The schema-validation enum constants are in
    yaml-helper.sh
    (
    _yaml_helper_enums
    ).
    validate_enum_value
    is the single-key validator for pending writes;
    validate_yaml_enum
    validates whole files (used by
    session-start.sh
    ).
  • project.local.yaml
    is gitignored. These overrides never propagate to teammates.
  • For which value to choose for a given game type or situation — and when to suggest changing one — see
    .claude/docs/settings-guidance.md
    (advisory presets
    • change triggers).
      effects-map.md
      says what each setting does; that doc says which to pick.
  • 所有 YAML 写入都是对现有键和块的原地编辑,或者创建一个新文件。此 skill 不依赖
    yq
    或任何外部 YAML 库。
  • 白名单在
    yaml-helper.sh
    中强制执行(
    is_locally_overridable
    函数)。如需扩展,请编辑
    _yaml_helper_locally_overridable
    常量——不要在此处重复维护列表。
  • 派生值不会存储在任何位置。
    modes.workflow
    、
    docs.density
    、
    qa.level
    、
    modes.story_granularity
    、
    modes.review_mode
    和
    team.size
    没有终端默认值;当没有文件设置它们时,其值来自
    yaml-helper.sh
    中的
    modes.rigor
    扩展(
    _yaml_helper_rigor_expansion
    )。应通过
    resolve_setting
    报告这些值——使用
    get_yaml_key
    读取会返回空值,并将其呈现为“(not set)”,但实际上每个 skill 都在使用一个真实值。
  • Schema 校验的枚举常量位于
    yaml-helper.sh
    (
    _yaml_helper_enums
    )中。
    validate_enum_value
    是待写入项的单键校验器;
    validate_yaml_enum
    用于校验整个文件(由
    session-start.sh
    使用)。
  • project.local.yaml
    被 gitignore。这些覆盖配置永远不会传播给团队成员。
  • 关于针对特定游戏类型或场景应选择哪个值,以及何时建议更改设置,请参阅
    .claude/docs/settings-guidance.md
    (建议预设和变更触发条件)。
    effects-map.md
    说明每个设置的作用;该指导文档则说明应选择哪个值。