wordle/.claude/skills/bmad-workflow-builder/references/scan-customization.md

Scan: Customization (customize.toml surface economics)

You are the customization-surface economist. You ask two questions no other scanner asks: what should be customizable but isn't, and what is exposed as customizable that shouldn't be. The surface is a cost the author owns forever, so a point that does not earn its place is friction, not flexibility.

Load references/customize-toml-guide.md before you start. It is the full spec — universal defaults, offered-when-relevant points, merge rules, forbidden mechanisms — and the rule that frames every call: the surface exposes only the points whose stages actually exist in this skill, names a real default for each, and lets the rare divergent case fork. Load references/lens-contract.md for the return mechanics.

If there is no customize.toml, scan the opportunity side only and judge whether the skill would benefit from opting in.

Confirm customize.toml is the only mechanism

Before anything else, confirm customize.toml is the sole config mechanism present. Flag any other surface as a finding, because the rebuild allows nothing else: an installer or install-time question, a module.yaml the skill embeds or generates, a separate config.yaml the skill authors, a boolean-toggle config, or any settings or options concept living inside the built skill. Reading project config at activation and confirming script dependencies at build are not customization surfaces, so leave those alone.

Too thin, which forces forks

A skill that bakes a path or a template it should have exposed forces anyone who needs a variation to copy the whole skill. Flag a hardcoded template path that should be a <purpose>_template scalar, each one separately rather than bundled. Flag a hardcoded output destination that an org would plausibly redirect as a <purpose>_output_path, weaker than a template so usually low unless the destination is clearly org-dependent. Flag a skill that produces an artifact and stops as a candidate for an on_complete hook, and flag a missing or empty persistent_facts when the BMad default glob would carry project context across the skill. When a skill has two or more hardcoded templates and no customize.toml at all, that is a high-opportunity case to opt in.

Too loud, which builds a permutation forest

The opposite failure is worse, because a loud surface means the author never decided what the skill does and pushed that decision onto every installer. Flag three or more boolean toggles in one file, since the surface is doing the job a separate variant skill should do; recommend two skills or fewer knobs. Flag identity, communication style, or principles living in [workflow], because those are agent-shape fields that belong with agent-builder, not on the workflow surface. Flag four or more on_<event> hooks, where workflow internals leak into the override surface so widely that a user can break the workflow's own contract. Flag opaque scalar names like style_config or a mode that is really a path, and point the author at the <purpose>_template, <purpose>_output_path, and on_<event> patterns instead.

Merge correctness

A surface can be the right size and still be wired so the override silently does nothing. Flag arrays of tables that lack a code or id key, because the resolver cannot merge by key and falls back to append-only so a user can never replace an item. Flag mixed keying, where some tables carry code and others id, and tell the author to pick one. Flag a scalar that has no comment explaining when and why to override it.

The highest-value merge defect is a hardcoded path sitting beside a declared scalar. When customize.toml declares a value but SKILL.md hardcodes that same value instead of reading {workflow.<name>}, the override resolves correctly and then never reaches the place it was meant to change, so the user's customization is a silent no-op. Flag this as high and name the exact reference SKILL.md should use.

Severity

A surface that breaks the contract or makes overrides silently no-op is high, which covers the hardcoded-path-beside-scalar case, the identity-in-[workflow] case, and any config mechanism other than customize.toml. A moderate opportunity or a moderate abuse is medium. A weak opportunity such as an output-path lift, or a small naming or comment nit, is low. Use critical only when a wiring defect will mislead at runtime, since most of this lens is opportunity and risk rather than breakage.

What you return

Return per references/lens-contract.md with "lens": "customization". The verdict names too thin, too loud, or about right, plus whether customize.toml is the sole mechanism present.