>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3583219. --> Reported by: [alex ua](https://www.drupal.org/user/110386) Related to !21 >>> <h3>Problem/Motivation</h3> <p>AI agents consistently mishandle Drupal's configuration system because they don't understand the three distinct storage mechanisms or when to use each:</p> <ul> <li><strong>Config vs. State vs. Settings confusion.</strong> Agents store runtime data (like "last cron run") in config instead of state, or put environment-specific values (like API keys) in config instead of settings.php. This causes deployment bugs (state getting overwritten by config import) and security issues (secrets in config that gets committed to git).</li> <li><strong>Config schema errors.</strong> Agents create config files without matching schema definitions, or write schemas that don't match the actual data structure. This breaks config validation and translation.</li> <li><strong>Simple config vs. config entity confusion.</strong> Agents create config entities for simple key-value settings, or use simple config for admin-manageable structured data that should be a config entity.</li> <li><strong>Config import/export workflow errors.</strong> Agents edit YAML files directly in <code>config/sync</code> instead of making changes through the UI/API and exporting, or they don't export after making changes programmatically.</li> <li><strong>Config override confusion.</strong> Agents don't understand the override system (settings.php overrides, language overrides, module overrides) and try to "fix" overridden values by writing to config directly.</li> </ul> <h3>Proposed Resolution</h3> <p>Create a <code>working-with-configuration/SKILL.md</code> skill covering:</p> <h4>The three storage mechanisms (decision tree)</h4> <table> <thead> <tr> <th>Question</th> <th>Answer</th> <th>Use</th> </tr> </thead> <tbody> <tr> <td>Should it be the same across all environments?</td> <td>Yes</td> <td>Config</td> </tr> <tr> <td>Is it environment-specific (DB credentials, API keys)?</td> <td>Yes</td> <td>settings.php</td> </tr> <tr> <td>Is it runtime data that changes frequently (timestamps, counters)?</td> <td>Yes</td> <td>State</td> </tr> <tr> <td>Should admins manage multiple instances of it through the UI?</td> <td>Yes</td> <td>Config Entity</td> </tr> <tr> <td>Is it a simple set of key-value module settings?</td> <td>Yes</td> <td>Simple Config</td> </tr> </tbody> </table> <h4>Config schema: why it matters and how to write it</h4> <p>Config without schema breaks validation, translation, and the config inspector. Every <code>config/install/*.yml</code> file needs a matching entry in <code>config/schema/*.schema.yml</code>.</p> <h4>The export workflow</h4> <p>Make changes &rarr; <code>drush cex</code> &rarr; commit the YAML. Never hand-edit files in <code>config/sync</code> unless you are certain the schema matches. Never commit config that contains state or secrets.</p> <h3>Remaining Tasks</h3> <ol> <li>Draft the skill file with decision tree and worked examples</li> <li>Write eval cases: agent stores an API key (must use settings.php, not config), agent creates module settings (must include schema), agent stores a timestamp (must use state)</li> <li>Add entry to AGENTS.md</li> <li>Review with config system maintainers</li> </ol>