Dotfiles Optimizer - Main Orchestrator

Coordinate comprehensive analysis and optimization of dotfiles with intelligent, context-aware recommendations.

Purpose

This skill orchestrates the complete dotfiles optimization workflow: analyzing configurations, identifying issues, recommending improvements, and optionally applying fixes. It reads the dotfiles path from user settings in .claude/dotfiles-optimizer.local.md (defaults to ~/.dotfiles). Supports modular zsh configuration, Neovim, Tmux, Git multi-config setup, and themed terminal environments.

Arguments

When invoked via /optimize, the following arguments are supported:

Component Scope (optional, positional):

zsh - Shell configuration only
tmux - Tmux configuration only
nvim - Neovim configuration only
git - Git configuration only
terminal - Terminal configs (Kitty/Ghostty) only
all or omitted - Entire dotfiles structure

Flags (optional):

--apply - Automatically apply critical and recommended fixes without confirmation
--security - Focus analysis on security issues only
--performance - Focus analysis on performance optimization only
--modern-tools - Focus on modern tool recommendations only

Examples:

/optimize                    # Full analysis of all components
/optimize zsh                # Analyze shell configuration only
/optimize --security         # Security audit across all components
/optimize zsh --apply        # Analyze shell and auto-apply fixes
/optimize --performance      # Performance optimization focus

When to Use

Activate this skill when users request:

General optimization ("optimize my dotfiles", "improve my shell")
Security audits ("check for exposed credentials", "audit my configs")
Performance improvements ("make my shell faster", "speed up zsh startup")
Modern tool recommendations ("what CLI tools should I use")
Configuration analysis ("analyze my setup", "check my tmux config")

Workflow

Follow this orchestration workflow when activated:

1. Determine Scope

Context-aware scoping: Analyze what the user is currently working on or explicitly requested:

If user is editing a specific config file (e.g., .zshrc, tmux.conf):
- Focus analysis on that component and related files
- Example: Editing .zshrc → analyze shell configuration (zsh.d/, aliases, functions)
If user requests specific component (e.g., "optimize my zsh"):
- Scope to that component only
- Components: shell (zsh), editor (nvim), multiplexer (tmux), git, terminal (kitty/ghostty)
If user requests general optimization:
- Analyze entire dotfiles structure
- Prioritize critical issues first, then component-by-component

Configuration loading: Check for user settings in .claude/dotfiles-optimizer.local.md:

Default path: /Users/kriscard/.dotfiles
User can override with dotfiles_path field in frontmatter
User can disable proactive warnings with enable_proactive_warnings: false

2. Invoke Analysis Agent

Call the dotfiles-analyzer agent to perform deep analysis:

Invoke dotfiles-analyzer agent with:
- Scope: [determined above]
- Depth: deep (2-3 minute comprehensive analysis)
- Focus areas: security, performance, modern tools, configuration patterns

The agent will:

Parse configuration files
Check for security issues (exposed credentials, insecure permissions)
Identify performance bottlenecks (startup time, lazy loading opportunities)
Suggest modern CLI tool alternatives
Validate configuration patterns against best practices

3. Reference Best Practices

Consult the dotfiles-best-practices skill for knowledge about:

Modern CLI tools and their benefits
Shell performance optimization techniques
Security patterns for credential management
Configuration organization strategies
Git workflow improvements

Use this knowledge to enhance the analyzer's findings with context and rationale.

4. Generate Prioritized Recommendations

Organize findings into three priority levels:

🔴 Critical Issues

Security vulnerabilities (exposed API keys, passwords, tokens)
Insecure file permissions (should be 600/700 for sensitive files)
Breaking configuration errors
Data loss risks

🟡 Recommended Improvements

Performance optimizations (lazy loading, startup time)
Modern tool suggestions (eza instead of ls)
Better configuration patterns (modular organization)
Missing best practices (git signing, env templates)

🟢 Optional Enhancements

Aesthetic improvements (themes, prompts)
Nice-to-have features (additional plugins)
Alternative approaches (different tools)
Advanced configurations

Output format:

## Analysis Results for [Scope]

🔴 Critical Issues (N)
  - Issue 1 with location and remediation
  - Issue 2 with location and remediation

🟡 Recommended Improvements (N)
  - Improvement 1 with rationale and benefit
  - Improvement 2 with rationale and benefit

🟢 Optional Enhancements (N)
  - Enhancement 1 with description
  - Enhancement 2 with description

5. Offer to Apply Fixes

After presenting recommendations:

For Critical Issues:

Strongly recommend immediate fixes
Offer to apply automatically with user confirmation
Explain risks of not fixing

For Recommended Improvements:

Ask which improvements user wants to apply
Can apply all, selected, or none
Provide implementation guidance

For Optional Enhancements:

Present as "nice-to-haves"
User can request specific ones
Don't push for these

Application workflow:

Ask: "Which fixes would you like to apply?"
Options:
- All critical issues (recommended)
- All recommended improvements
- Specific items (let me choose)
- None (just wanted the analysis)

If --apply flag was passed:

Apply all critical issues automatically
Apply all recommended improvements automatically
Skip optional enhancements (user can request separately)
Show progress for each fix applied

If user chooses to apply interactively:

Use Read tool to examine current configs
Use Edit tool to make precise changes
Explain each change as it's made
Validate changes don't break syntax

Backup strategy (always, before modifying any file):

cp ~/.dotfiles/.zshrc ~/.dotfiles/.zshrc.backup.$(date +%Y%m%d-%H%M%S)

Create timestamped backups so changes are always reversible.

6. Integration with Existing Tools

The user has an existing dotfiles CLI script at /Users/kriscard/.dotfiles/dotfiles. Complement this tool:

This plugin provides:

Intelligent analysis and recommendations
Security scanning
Best practice validation
Modern tool suggestions

The dotfiles script provides:

Installation automation (dotfiles init)
Health checks (dotfiles doctor)
Syncing (dotfiles sync)
Backup management (dotfiles backup)

Recommendation: When user needs to run init, sync, or backup operations, suggest using their existing dotfiles script. Focus this plugin on analysis and optimization guidance.

Component-Specific Analysis

Shell (Zsh)

Analyze the modular configuration in zsh/zsh.d/:

00-env.zsh - Environment variables (check for exposed credentials)
10-options.zsh - Shell options (validate settings)
20-completions.zsh - Completion system (check for performance)
30-plugins.zsh - Plugin loading (identify slow plugins, suggest lazy loading)
40-lazy.zsh - Lazy loading patterns (validate implementation)
50-keybindings.zsh - Key mappings (check for conflicts)
60-aliases.zsh - Aliases (suggest modern tool alternatives)
70-functions.zsh - Functions (optimize complex functions)
80-integrations.zsh - External integrations (validate configurations)
99-local.zsh.example - Local overrides (check for security)

Key checks:

Startup time profiling (should be <500ms)
Plugin lazy loading opportunities
Modern aliases (eza, bat, fd, ripgrep, zoxide)
Secure environment variable handling

Editor (Neovim)

Analyze .config/nvim/:

LSP configurations (validate server setups)
Plugin management (check for outdated or conflicting plugins)
Performance (startup time, lazy loading)
Keybindings (identify conflicts)

Multiplexer (Tmux)

Analyze .config/tmux/:

Plugin configuration
Keybinding sanity
Performance settings
Integration with sesh session manager

Git

Analyze git configuration files:

.gitconfig - Main configuration
.gitconfig-personal - Personal settings
.gitconfig-work - Work settings
Check for exposed credentials
Validate signing configuration
Suggest workflow improvements

Terminal (Kitty/Ghostty)

Analyze .config/kitty/ and .config/ghostty/:

Theme consistency (Catppuccin Macchiato)
Font configuration
Performance settings
Key mappings

Modern Tool Recommendations

Reference these tool replacements (from user's existing setup):

Traditional	Modern Alternative	User Has	Benefit
`ls`	`eza`	✅	Git integration, icons
`cat`	`bat`	✅	Syntax highlighting
`find`	`fd`	✅	Faster, simpler syntax
`grep`	`ripgrep`	✅	Blazing fast search
`cd`	`zoxide`	✅	Smart jumping

Validate these are properly aliased and configured. Suggest additional modern tools if relevant.

Security Validation

Always check for:

Exposed credentials: API keys, tokens, passwords in plain text
File permissions: Sensitive files should be 600 (user read/write only)
History settings: Ensure sensitive commands aren't logged
Git safety: Validate .gitignore patterns for secrets
Environment files: Check .env vs .env.example patterns

Performance Optimization

Check for:

Shell startup time: Profile and identify slow components
Lazy loading: Defer loading of tools not used in every session
Completion caching: Validate completion cache strategies
Plugin efficiency: Identify slow or redundant plugins

Output Best Practices

Be specific:

Include file paths and line numbers
Show before/after examples
Explain why changes help

Be actionable:

Provide exact commands or edits
Link to documentation when relevant
Offer to make changes

Be educational:

Explain rationale for recommendations
Reference best practices
Help user learn, not just fix

Additional Resources

Related Skills

dotfiles-best-practices - Detailed knowledge base for patterns and modern tools

Agent Invocation

Use the dotfiles-analyzer agent for deep analysis:

Activated by this orchestrator
Can also trigger proactively on critical security issues
Provides detailed, file-by-file analysis

Commands

Users can also invoke explicitly via commands:

/optimize - Full workflow (same as this skill)
/audit - Read-only analysis without offering fixes

Example Session

User: "Optimize my dotfiles"

1. Determine scope: Entire dotfiles (no specific context)
2. Invoke dotfiles-analyzer agent for comprehensive analysis
3. Reference dotfiles-best-practices for context
4. Generate findings:

   🔴 Critical Issues (2)
     - API key in zsh.d/00-env.zsh line 45: GITHUB_TOKEN=ghp_xxx
     - .gitconfig-work has permissions 644, should be 600

   🟡 Recommended Improvements (5)
     - Enable lazy loading for nvm (saves ~300ms startup)
     - Use eza with git integration (already installed, needs alias)
     - Modularize .zshrc further (move local config to 99-local.zsh)
     - Add .env.example template for safe credential patterns
     - Enable git commit signing for security

   🟢 Optional Enhancements (3)
     - Consider starship prompt for better performance
     - Add bat theme matching Catppuccin setup
     - Configure tmux plugin manager (tpm) for easier plugin management

5. Ask: "Which fixes would you like to apply?"
   User: "All critical and recommended"

6. Apply fixes with explanations:
   - Move GITHUB_TOKEN to .env (not committed)
   - Update .gitconfig-work permissions to 600
   - Add lazy loading wrapper for nvm
   - Create eza alias with --git flag
   - [Continue for each fix...]

7. Verify changes and confirm completion

Notes

Always load dotfiles path from user settings or default to /Users/kriscard/.dotfiles
Respect existing dotfiles CLI script - complement, don't replace
Focus on intelligent analysis - let user's script handle mechanical operations
Prioritize security issues always
Be context-aware - don't over-analyze when user has specific request
Provide education along with fixes