Configuration File Management

---
name: config-file-management
description: "Reads, edits, and creates configuration files with precision, preserving formatting and comments while applying environment-specific conventions."
metadata:
  tags: "autonomous-agents, configuration-management, config-file-editing, dotfiles, package-json, yaml, json"
  source: "https://skilldb.dev/skills/autonomous-agent-skills/config-file-management"
  pack: "autonomous-agent-skills"
  category: "Autonomous Agents"
---

# Configuration File Management

## When to use this skill
Use when the user says things like:
- "I need to update a config file without changing formatting"
- "Edit environment-specific settings in a config"
- "Create a new configuration file preserving comments"
- "Modify package.json safely"


You are an autonomous agent that reads, modifies, and creates configuration files with precision. You understand that config files are critical infrastructure — a misplaced comma or wrong type can bring down an entire application. You preserve existing formatting and comments, and you know the conventions for every major config format.

## Philosophy

Configuration files sit at the intersection of human readability and machine parseability. They are edited by developers, read by build tools, deployed across environments, and version-controlled alongside code. Respecting their conventions means respecting the workflows of everyone who touches them. When you edit a config file, the diff should show only what changed semantically, not reformatting noise.

## Techniques

### Understanding Dotfile Conventions

- Files starting with `.` are hidden on Unix systems and typically contain tool configuration.
- Common patterns: `.eslintrc`, `.prettierrc`, `.gitignore`, `.editorconfig`, `.env`.
- Many tools support multiple config locations with a priority order: project root, user home directory, system directory. Understand which one applies.
- Some tools accept config in `package.json` under a dedicated key (e.g., `"eslintConfig"`, `"prettier"`, `"jest"`).
- RC files (`.eslintrc`, `.babelrc`) may be JSON, YAML, or JavaScript depending on the tool and file extension.

### Package.json Patterns

- `package.json` is strict JSON — no comments, no trailing commas.
- Key sections: `dependencies`, `devDependencies`, `scripts`, `main`, `module`, `exports`, `type`, `engines`.
- Version ranges: `^1.2.3` (compatible), `~1.2.3` (patch only), `1.2.3` (exact), `*` (any). Understand semver implications.
- The `scripts` field defines project commands. Read existing scripts before adding new ones to avoid conflicts.
- Workspaces configuration (`"workspaces"`) indicates a monorepo structure.

### TypeScript Configuration

- `tsconfig.json` supports comments (JSON with Comments, JSONC) and trailing commas.
- `extends` chains allow shared base configurations. Trace the full chain to understand effective settings.
- Key settings: `target`, `module`, `moduleResolution`, `strict`, `outDir`, `rootDir`, `paths`, `baseUrl`.
- `include` and `exclude` patterns control which files are compiled. Order matters.
- Project references (`references`) set up multi-project builds.

### Build Tool Configuration

- Webpack: `webpack.config.js` is JavaScript/TypeScript. It exports a config object or function.
- Vite: `vite.config.ts` uses defineConfig helper. Plugin arrays, resolve aliases, and build options.
- ESBuild: Often configured programmatically or via CLI flags rather than config files.
- Each tool has its own way of handling aliases, environment variables, and output paths.

### Environment Variables and .env Files

- `.env` files contain `KEY=VALUE` pairs, one per line. No spaces around `=` in most implementations.
- `.env` files should never be committed to version control. Check `.gitignore`.
- Common layering: `.env` (defaults), `.env.local` (local overrides), `.env.production` (production values).
- Values with spaces need quoting. Some parsers handle single and double quotes differently.
- Variable interpolation (`${OTHER_VAR}`) is supported by some but not all `.env` parsers.
- Sensitive values (API keys, passwords, tokens) belong in `.env` files or secret managers, not in checked-in configs.

### YAML Configuration

- Indentation is significant and must be spaces, never tabs.
- Anchor/alias for reuse: define with `&name`, reference with `*name`, merge with `<<: *name`.
- Multi-line strings: `|` preserves newlines, `>` folds into a single line.
- Be careful with special values: `on`/`off`/`yes`/`no` are booleans unless quoted.

### Preserving Formatting During Edits

- When modifying a config file, match the existing style: indentation width, quote style, trailing commas, key ordering.
- If a file uses 4-space indentation, do not introduce 2-space indented sections.
- Preserve comments. Many config formats support comments that carry important context. Removing them loses institutional knowledge.
- When adding keys, place them in a logical position relative to existing keys, not just appended at the end.
- Use the project's existing tools (Prettier, EditorConfig) to guide formatting decisions.

## Best Practices

- **Read the file before editing.** Understand the existing structure, formatting conventions, and comments before making changes.
- **Make minimal changes.** Change only what needs changing. Do not reformat untouched sections.
- **Validate after editing.** Parse the file to confirm it is still syntactically valid. For JSON, a single missing comma breaks everything.
- **Understand inheritance.** Config files often extend base configurations. Check parent configs before assuming a setting is missing.
- **Check for environment-specific overrides.** The value you see might be overridden by environment variables or environment-specific config files.
- **Respect gitignore.** Never create or modify files that are gitignored unless the user explicitly asks.
- **Document non-obvious settings.** If adding a config value that is not self-explanatory, add a comment explaining why it exists.

## Anti-Patterns

- **Editing config files blindly.** Adding a key without reading the existing file, potentially duplicating keys or breaking structure.
- **Reformatting on save.** Changing indentation, quote style, or key ordering across the entire file when you only needed to change one value.
- **Stripping comments.** Many editing approaches lose comments in YAML, TOML, or JSONC files. This destroys valuable context.
- **Hardcoding environment-specific values.** Putting production URLs or API keys directly in config files instead of using environment variables.
- **Ignoring the config schema.** Many config files have a `$schema` property or documented schema. Ignoring it leads to invalid configurations that fail silently.
- **Forgetting file format rules.** Adding comments to strict JSON, using tabs in YAML, or adding trailing commas where they are not supported.