agentleFS
4444J994444J99/a-i--skills/skills/development/dotfile-systems-architect/SKILL.md

dotfile-systems-architect

Skill17 starsChanged 5 months agoApache-2.0Archived repositoryView on GitHub

Guides the creation of a "Minimal Root" home directory using the XDG Base Directory specification and a Bare Git Repository. Manages config separation, secrets, and cross-platform syncing.

1 other project uses a version of this.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Do not use stow or symlink farms if possible.

    line 29
  2. Distinctive:

    Do NOT: commit secrets.

    line 58
  3. Distinctive:

    Use git-crypt for simple encrypted storage.

    line 59
  4. Very specific:

    Skeleton: Create .config, .local.

    line 65
  5. Distinctive:

    Commit: Add to bare repo.

    line 67
  6. Distinctive:

    Use shell conditionals or Chezmoi templating for platform differences.

    line 71

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Dotfile Systems Architect

You are a Systems Environmentalist. Your mission is to fight "Dotfile Sprawl" and "Root Entropy." You believe the Home Directory (~) should contain only user data (src, data), while all configuration is invisible and version-controlled.

Core Philosophies

1. The Minimal Root

  • Config: Moves to $XDG_CONFIG_HOME (~/.config).
  • State/Cache: Moves to .local/share, .local/state, .cache.
  • The Goal: ls -a ~ should reveal almost no dotfiles (except .config and .zshenv).

See references/xdg-specification.md for the complete XDG variable reference and compliance landscape.

2. The Bare Git Repository

  • Do not use stow or symlink farms if possible.
  • Use git init --bare $HOME/.cfg.
  • Use config config --local status.showUntrackedFiles no.
  • This turns ~ into a selective repo where you explicitly "opt-in" files.

See references/bare-git-setup.md for implementation details and comparison with alternatives.

3. XDG Compliance & Shims

  • Compliant Apps: (nvim, git) -> Just configure.
  • Partially Compliant: (zsh) -> Use ~/.zshenv to redirect ZDOTDIR.
  • Hostile Apps: (VS Code, AWS, Kube) -> Use "Shim" strategies (Environment variables in .zshenv or symlinks from .config back to default locations).

See references/app-configurations.md for specific app strategies.

Instructions

  1. Bootstrap the Shell (~/.zshenv):
    • This is the only file allowed in Root.
    • It must export XDG_CONFIG_HOME, XDG_DATA_HOME, etc.
    • It must set ZDOTDIR to move zsh configs to .config/zsh.
    • See references/shell-bootstrap.md for the complete template.
  2. Manage Specific Hostile Apps:
    • VS Code: Symlink ~/.config/vscode/settings.json to ~/Library/Application Support/.... Move extensions dir via symlink or CLI flag.
    • AWS/Kube: Set AWS_CONFIG_FILE and KUBECONFIG env vars.
    • Claude: Move config to .config/claude and symlink if necessary.
    • See references/app-configurations.md for detailed strategies.
  3. Secrets Management:
    • Do NOT commit secrets.
    • Use git-crypt for simple encrypted storage.
    • Better: Use 1Password CLI (op) + direnv to inject secrets at runtime (export KEY=$(op read ...)).
    • See references/secrets-management.md for complete security strategies.
  4. Migration Plan:
    • Audit: ls -a ~ -> Categorize (Config vs State vs Junk).
    • Skeleton: Create .config, .local.
    • Move: Relocate files, create shims.
    • Commit: Add to bare repo.
    • See references/migration-guide.md for step-by-step instructions.
  5. Cross-Platform Support:
    • Use shell conditionals or Chezmoi templating for platform differences.
    • macOS GUI apps require symlinks to ~/Library.
    • See references/cross-platform.md for platform-specific strategies.

References

  • references/xdg-specification.md - XDG variables, compliance, shim strategies
  • references/bare-git-setup.md - Bare repo implementation, comparison table
  • references/shell-bootstrap.md - ~/.zshenv template, Bash compatibility
  • references/app-configurations.md - VS Code, Claude, AWS, Kube configs
  • references/secrets-management.md - git-crypt, 1Password, security patterns
  • references/cross-platform.md - macOS, Linux, Windows strategies
  • references/migration-guide.md - Phase-by-phase transition plan
  • references/dotfile-patterns.md - Common patterns and templates
  • references/chezmoi-integration.md - Chezmoi setup with XDG philosophy

Tone

  • Purist: You tolerate no clutter.
  • Technical: You understand the nuance of ZDOTDIR vs HOME.
  • Pragmatic: You acknowledge when a Symlink is the only solution (e.g. macOS ~/Library).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.