dotfiles

name	dotfiles
description	Reference for repository dotfiles, including their purposes, standard configurations, and usage guidelines. You MUST load this skill when configuring, troubleshooting, or understanding repository dotfiles.
license	MIT

dotfiles

When to Use

• Identifying the correct dotfile to modify for a specific configuration change (e.g., formatting, linting, git behavior).
• Troubleshooting CI/CD, linting, formatting, or environment configuration issues.
• Setting up a new repository with standard organizational configuration files.
• Understanding the purpose of existing hidden configuration files in the root directory.

When Not to Use

• Modifying application-specific source code or core business logic.
• Configuring cloud infrastructure outside the repository itself (e.g., Terraform, AWS).
• Modifying standard documentation files (README.md, CONTRIBUTING.md) that are not hidden dotfiles.

Step-by-Step Workflows

Configuring a Dotfile

1. Identify the Scope: Determine what needs configuring (e.g., editor settings, git attributes, linting rules, dependency management).
2. Locate the Dotfile: Find the appropriate dotfile in the repository root or .github/ directory.
3. Analyze Existing Configuration: Read the file to understand current rules, overrides, and syntax.
4. Apply Changes: Modify the configuration following the specific tool's exact documentation and syntax.
5. Verify Changes: Run the associated tool (linter, formatter, or git command) to ensure changes are valid and have the intended effect.

Dotfile Reference

Git Repository & Workspace Dotfiles

• .astro/config.yaml: Configuration file for the Astro web framework, defining build options, integrations, and project settings.
• .claude/: Directory containing workspace-specific Claude configuration, such as settings.json for hooks, tool permissions, and model or other workspace settings.
• .devcontainer/: Directory for containerized development environments, containing devcontainer.json (configuration), requirements.txt (Python dependencies), and apt-packages.txt (system packages).
• .editorconfig: Defines consistent coding styles (indentation, line endings, character set) for multiple developers working on the same project across various IDEs.
• .env.example / .env.sample / .env.dist: Provides a template of required environment variables without including actual secret values.
• .fdignore: Specifies files and directories to ignore for the fd search tool, often mirroring .gitignore but used for faster file finding.
• .gemini/: Directory containing configuration for Google Gemini, such as settings.json which typically points it to use AGENTS.md for context.
• .github/CODEOWNERS: Defines individuals or teams responsible for specific code paths, automatically assigning them as PR reviewers.
• .github/ISSUE_TEMPLATE/*.yml: Structured templates for bug reports and feature requests to ensure consistent issue reporting.
• .github/actionlint.yml: Configuration file for actionlint to define custom linting rules or ignore specific errors in GitHub Actions workflows.
• .github/copilot-instructions.md: Comprehensive coding standards and instructions for GitHub Copilot in the repository context.
• .github/dependabot.yml: Configures GitHub Dependabot to automatically check for and create pull requests to update dependencies.
• .github/mcp-config.json: Configuration for the Model Context Protocol (MCP) server, providing agents with access to GitHub tools.

Linux-specific & User Home ($HOME) Dotfiles

• .bash_history: Stores the command history for the Bash shell.
• .bash_profile / .profile: Initialization scripts for login shells; .bash_profile is Bash-specific, while .profile is a more general fallback.
• .bashrc: The primary initialization script for non-login Bash shells, used for aliases, environment variables, and prompt settings.
• .cache/: Directory for user-specific non-essential data (XDG_CACHE_HOME), such as downloaded files or temporary application state.
• .config/: Directory for user-specific configuration files (XDG_CONFIG_HOME), following the XDG Base Directory Specification.
• .ctags: Configuration for Ctags, used to define how source code symbols are indexed for navigation.
• .curlrc: Default configuration for the curl command-line tool, used to specify common flags or proxy settings.
• .drush/: Configuration directory for Drush (Drupal Shell), containing aliases and command-specific settings.
• .gdbinit: Initialization script for the GDB debugger, used to define custom commands or UI settings.
• .gitconfig: The global Git configuration file (typically in $HOME), containing user identity, global aliases, and default behaviors.
• .gnupg/: Directory for GnuPG (GNU Privacy Guard) configuration, keys, and trust database.
• .hyper.js: Configuration file for the Hyper terminal emulator.
• .inputrc: Configuration for the Readline library, used by shells (Bash) and other CLI tools for line editing and history.
• .lesshst: Stores the search and command history for the less pager.
• .lldbinit: Initialization script for the LLDB debugger, similar to .gdbinit.
• .netrc: Stores credentials for automatic login to FTP servers, HTTP sites, and other services used by tools like and . : Should be kept secure with permissions.

Best Practices

• Keep it Minimal: Only add necessary rules; rely on community standard defaults where possible.
• Document Non-Standard Rules: If a configuration deviates from standard conventions, add an inline comment explaining why.
• Merge, Don't Replace: When updating existing configuration files, merge organizational standards into the existing content rather than replacing the file entirely. Preserve project-specific customizations.
• Lexicographical Order: Maintain hooks in .pre-commit-config.yaml and other list-based configurations in alphabetical order.
• Standard Formatting: Use 4-space indentation for most files, but 2-space for YAML and JSON in .editorconfig.
• Test Hooks Locally: Always test .pre-commit-config.yaml changes locally by running pre-commit run --all-files before pushing.
• Use .env.example: Never commit actual .env files. Maintain an up-to-date .env.example for developers to copy.

Common Snippets

Search for dotfiles repositories

gh search repos "dotfiles" --limit 20

Common Pitfalls

• Overlapping Rules: Configuring conflicting rules in .editorconfig and language-specific linters (e.g., Prettier/ESLint). Ensure linter configs take precedence or align exactly with .editorconfig.
• Ignoring Generated Files: Forgetting to add build output directories (like node_modules/, dist/, .venv/) to .gitignore, leading to massive, unwanted commits.
• Incorrect Line Endings: Not enforcing * text=auto eol=lf in .gitattributes, causing cross-platform line ending issues (CRLF vs LF) and noisy git diffs.
• Hardcoding Secrets: Accidentally committing secrets because .env wasn't added to .gitignore before creating the file.

Related Skills

• agent-md: You MUST load this skill when working with AGENTS.md or other agent-specific configuration files.
• code-tour: You MUST load this skill when creating or updating .tours/ files.
• devcontainer: You MUST load this skill when managing .devcontainer/ configurations.
• dot-github: You MUST load this skill when standardizing or updating the .github/ directory structure.
• editorconfig: You MUST load this skill when creating or updating an .editorconfig file.
• gitattributes: You MUST load this skill when configuring Git behaviors via .gitattributes.
• gh-search: You MUST load this skill when searching for repositories or code examples using the GitHub CLI.
• github-actions: You MUST load this skill when troubleshooting or configuring GitHub Actions workflows.
• pre-commit: You MUST load this skill when managing pre-commit hooks.
• yaml: You MUST load this skill when updating YAML configuration dotfiles.