settings skill

/settings — view or change project config

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 schemachanges decision (a default automationalwaysask category), so /settings confirms config writes even in autonomous mode unless the user has removed schemachanges from their always-ask list.

Phase 0: Parse Arguments

Determine which of the four forms the user invoked:

For Set-yaml and Set-local, is a dotted YAML path (e.g. modes.review_mode, testing.strict.logic) and is the new value.

Empty-operand validation: After splitting the key=value operand on =, if either or 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 /settings --local =foo and /settings --local key= both go to Phase 6).

Anything else that doesn't match the four forms above → Phase 6 (usage).

Phase 1: Load Helper

All four subcommands need yaml-helper.sh. Source it once via Bash:

source "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/yaml-helper.sh"

If .claude/hooks/yaml-helper.sh is missing, this is not a CCGS project. Report the error and exit.

Phase 1b: Reserved-setting detection

Some settings are fully documented, enum-validated 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):

grep -B14 '^> ### RESERVED' .claude/docs/effects-map.md | grep -E '^## '

Match the banner HEADING (> ### RESERVED), never the bare word "RESERVED". platform.certtier'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

/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.

Phase 2: View-all Mode

(when no arguments)

1. Confirm project.yaml exists. If missing, report:

"No project.yaml found — run /start to create one."

And exit.

1. Check if project.local.yaml exists.

If project.local.yaml exists, also run validateyamlenum project.local.yaml. Tag each error with its source file so the user can tell them apart.

1. Run validateyamlenum project.yaml and capture any errors.

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.

1. Enumerate leaves. Use the Read tool to read both YAML files as

Then append the rigor family — modes.rigor, modes.workflow, docs.density, qa.level, modes.storygranularity, modes.reviewmode, 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.reviewmode 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.

1. For each leaf, perform three reads and one check:

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.

• resolve_setting → , TAB, . This walks the

show what a local override is shadowing)

• getyamlkey project.yaml → yaml-only value (needed only to

• islocallyoverridable → 0 (overridable) or 1 (locked)

Compute the source annotation from :

Append , locked to the annotation when islocallyoverridable returned 1.

Append , reserved when the leaf is in RESERVEDSET (Phase 1b)**, and print this line with the legend below the block:

reserved = stored and validated, 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.

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:

1. Print, grouped by top-level section (framework, modes,

project.yaml: present
project.local.yaml: present

Schema validation: ok

Effective config:

framework:
  version: 1.1.1            (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.6              (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
/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.