y3owk1n/neru / .agents/skills/neru-add-config-option
neru-add-config-option
VerifiedAdd or change a Neru config.toml option end to end: struct field, shared and platform defaults, validation, examples, docs, and hot-reload behavior. Use whenever a change adds, renames, or removes a key in the TOML config schema. Not for theme palette entries or CLI flags.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.2 KB |
| agents/openai.yaml | config | 277 B |
SKILL.md
View on GitHub---
name: neru-add-config-option
description: "Add or change a Neru config.toml option end to end: struct field, shared and platform defaults, validation, examples, docs, and hot-reload behavior. Use whenever a change adds, renames, or removes a key in the TOML config schema. Not for theme palette entries or CLI flags."
---
# Adding a config option to Neru
Config changes fail in review when one link of the chain is missing, such as a default
that exists on macOS but not Linux, a validator that never runs, or an example
file that still shows the old key. `internal/config/AGENTS.md` states the
contract and which test fails per link. This skill gives the order to do it in.
Five steps are universal. Then check the conditional four, the ones that turn
a one-line option into a ten-file one, and that no guide used to name.
## The universal five
1. **Schema.** Add the struct field in `internal/config/config.go` with a
`toml:"snake_case_name"` tag matching the surrounding section. Follow the
existing nesting. Options live in their feature's sub-struct, not at root.
Then run `just genschema`, which renders the field into
`schemas/config.schema.json` for editors.
`TestConfigSchema_IsGeneratedFromTheConfigStructs` fails until you do.
2. **Shared default.** Set it in `newDefaultConfig()` in
`internal/config/config_defaults.go`. Assign the field by name even when the
value you assign is the zero value, and say in a comment what the zero
means, because a zero nobody wrote cannot be told from a forgotten one.
`TestEverySchemaFieldHasAnExplicitDefault` fails on an omission.
3. **Example.** Add the line to `configs/default-config.toml`, which is the file
a user copies. Comment it out if the option has no default, because an uncommented
empty value asserts a default that does not exist.
`TestConfigOptionsAppearInTheDefaultExample` fails when the line is missing.
Update the mode-specific examples (`grid-only-config.toml`,
`hints-only-config.toml`, `recursive-grid-only-config.toml`) only if they
show the affected section. They are deliberately partial, and only their
*keys* are checked, by `TestRender_AcceptsEveryShippedExample`. Those four
are the whole shipped set. `configs/embed.go` lists them, and anything else
in `configs/` is a working file rather than a project artifact. Only
`default-config.toml` is embedded, and the rest are read from disk by the tests
that check them.
4. **Docs.** Add the row to `docs/reference/configuration.md`. That file is the single
home for config reference facts. Do not also describe the option in
`docs/contributing/architecture.md` or README. **No test catches a missing row.** This is the one
universal link a reviewer has to check by eye.
5. **Platform column.** Add the option's path to `PlatformSupport()` in
`internal/config/platform_support.go`, saying which of macOS, Linux and
Windows writing it actually does something on. Say so even when the answer
is all three, because a column nobody wrote cannot be told from a forgotten one, and
`TestEveryConfigOptionDeclaresItsPlatformSupport` fails on an option that is
neither. A narrower column needs a note saying why, in the words the user
reads, because it reaches the load-time warning, the `neru doctor`
`platform_support` row and the published table, which you regenerate with
`just gensupportref`. A `config.Color` is declared at the field, not at its
`light` and `dark` leaves
(`docs/adr/0013-parity-is-measured-in-words-not-subsystems.md`).
Steps 2 and 3 exempt three shapes, and an option with one of them passes both
tests whether or not you do the work: the `light`/`dark` leaves under a `Color`,
a collection that ships empty, and any field of a repeated table nobody ships
entries for (`app_configs`, `layers`). Do the work anyway. See
`internal/config/AGENTS.md`.
## The conditional four
Each is skippable, and each is a whole file when it is not.
- **Platform override.** If a platform needs a different default, set it in
`applyPlatformDefaults()` in the matching `config_<os>.go`
(`config_darwin.go`, `config_linux.go`, `config_windows.go`,
`config_other.go`). Both layers are reached via `DefaultConfig()` in
`config_platform.go`, so never call `newDefaultConfig()` directly from feature
code. Nothing checks this, so pin the difference in a test.
- **Validator.** Add checks to the relevant `Validate*` method on `*Config` in
`internal/config/validators_*.go` (hints, grid, style, hotkeys, macros,
pointer, appconfig, …). Invalid values must fail validation with a clear
message, not get silently clamped. New enum-ish strings get an allowlist. A
brand-new `Validate*` method must be called from `ValidateWithWarnings` in
`validate.go`, or `TestEveryConfigValidatorRunsInTheLadder` fails.
- **Derivation helper.** If the value the daemon runs on is not the value the
user writes, resolve it once after the configuration is assembled rather than
in each consumer. `internal/config/grid_labels.go` and `held_repeat.go` are
the worked examples. The declared default stays what a user would type.
- **Cross-field rule.** If the option only makes sense alongside another, and a
user could act on the mismatch, collect it into `Warnings` so it rides out on
`LoadResult` and reaches `neru config validate`. `logger.Warn` reaches nobody
(ADR 0002, `docs/adr/0002-severity-tiered-config-validation.md`).
## Hot reload
Config is hot-reloadable via `internal/config/loader` (load/watch/persist/
set-field). If the option should be settable at runtime with `neru config set`,
confirm the field path resolves through the loader's set-field lookup. If it
intentionally requires a restart, say so in the docs.
## Tests
- Table-driven validator tests next to the validator you touched
(`validators_*_test.go`), covering the default, a valid custom value, and at
least one rejected value.
- If the default differs per platform, pin it in `config_defaults_test.go` or
the platform-tagged config test.
## Verify
```bash
just test-foundation # the fast cross-platform-safe slice
```
That one recipe now runs every package this skill's guardrails live in: the
config package, its loader, and `internal/architecture`.
Then the standard pre-commit gate from AGENTS.md.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |