Initial commit

skills/clang-format/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: clang-format Configuration
+description: The model must invoke this skill when any trigger occurs - (1) user mentions "clang-format" or ".clang-format", (2) user requests analyzing code style/formatting patterns/conventions, (3) user requests creating/modifying/generating formatting configuration, (4) user troubleshoots formatting behavior or unexpected results, (5) user asks about brace styles/indentation/spacing/alignment/line breaking/pointer alignment, (6) user wants to preserve existing style/minimize whitespace changes/reduce formatting diffs/codify dominant conventions.
+---
+
+# clang-format Configuration
+
+Configure the clang-format code formatting tool using ready-to-use templates, integration scripts, and comprehensive reference documentation.
+
+## Purpose
+
+This skill provides procedural workflows for clang-format configuration tasks:
+
+- Create new .clang-format files from proven templates
+- Analyze existing code style and generate matching configurations
+- Set up editor and git integration with bundled scripts
+- Troubleshoot formatting behavior using reference documentation
+
+## Workflow Routing by Trigger Type
+
+Once invoked, route to appropriate workflow based on which trigger fired:
+
+**Trigger 1: Explicit clang-format mention** → If user asks about specific options: Consult references/01-09.md for relevant category → If user needs complete reference: Direct to references/complete/clang-format-style-options.md → If user asks about CLI usage: Reference references/cli-usage.md
+
+**Trigger 2: Code style analysis request** → Follow "Analyzing Existing Code Style" workflow below → Examine code samples systematically (braces→indentation→spacing→breaking→alignment) → Map patterns to closest template in assets/configs/ → Generate initial configuration hypothesis as a temporary configuration file "/tmp/<repo*name>/hypothesis*<number>.clang-format" → VERIFY IMPACT: Run `clang-format --style="/tmp/<repo_name>/hypothesis_<number>.clang-format" file.cpp | diff - file.cpp` on 3-5 representative samples → MEASURE IMPACT using weighted scoring: • Metric 1: Line count changes (lines added/removed) - weight 10 • Metric 2: In-line whitespace changes (spacing within existing lines) - weight 1 • Impact Score = (line_count_changes × 10) + (whitespace_changes × 1) • Lower score = lower impact to rebasing conflicts, future git-diff analysis, and merge request change reviews = better configuration → ITERATE: Adjust config options targeting highest-impact settings, re-test, compare scores → REPEAT until reaching minimal achievable score while maintaining consistent style enforcement → REPORT TO USER: Present winning configuration with: • Final impact score and breakdown (line changes vs whitespace changes) • Comparison table showing all tested hypotheses and their scores • Example diff snippets showing what will change, with commands for the user to test it themselves against files of their choice. • Rationale for selected configuration → AWAIT USER APPROVAL before finalizing configuration → Only after approval: provide final configuration file
+
+**Trigger 3: Configuration file operations** → If creating new: Follow "Creating New Configuration from Template" workflow → If modifying existing: Read current config, identify changes needed, consult relevant category guide → If generating from code: Use Trigger 2 workflow (code style analysis)
+
+**Trigger 4: Formatting behavior investigation** → Follow "Troubleshooting Formatting Issues" workflow below → Verify config detection with --dump-config → Identify affected category, consult relevant references/0X.md guide → Test isolated options with minimal config
+
+**Trigger 5: Style option inquiries** → Map question to category: braces→03, indentation→04, spacing→05, alignment→01, breaking→02 → Reference specific category guide in references/ → Provide examples from quick-reference.md if applicable
+
+**Trigger 6: Minimal-disruption requests** → Use "Analyzing Existing Code Style" workflow to match current patterns → Emphasize starting from closest template to minimize changes → Test on representative samples before project-wide application → Document which patterns were preserved vs normalized
+
+## Bundled Resources
+
+### Configuration Templates (assets/configs/)
+
+Seven ready-to-use `.clang-format` templates optimized for common scenarios:
+
+- `google-cpp-modified.clang-format` - Google C++ style with 4-space indent, 120 column limit
+- `linux-kernel.clang-format` - Linux kernel coding standards (tabs, K&R braces)
+- `microsoft-visual-studio.clang-format` - Microsoft/Visual Studio conventions
+- `modern-cpp17-20.clang-format` - Modern C++17/20 style with contemporary idioms
+- `compact-dense.clang-format` - Compact style for space-constrained environments
+- `readable-spacious.clang-format` - Spacious style prioritizing readability
+- `multi-language.clang-format` - Multi-language configuration (C++, JavaScript, Java)
+
+**When to use templates**: Start new projects, establish team standards, or quickly test formatting approaches.
+
+### Integration Scripts (assets/integrations/)
+
+Three editor and git integration scripts:
+
+- `pre-commit` - Git pre-commit hook for automatic formatting of staged files
+- `vimrc-clang-format.vim` - Vim configuration for format-on-save
+- `emacs-clang-format.el` - Emacs configuration for clang-format integration
+
+**When to use integrations**: Set up automatic formatting in development workflow.
+
+### Reference Documentation (references/)
+
+Detailed documentation organized by category:
+
+**Quick Navigation**:
+
+- `index.md` - Overview and documentation hub
+- `quick-reference.md` - Complete working configurations with explanations
+- `cli-usage.md` - Command-line usage, editor setup, CI/CD integration
+
+**Option Categories** (01-09.md):
+
+1. `01-alignment.md` - Vertical alignment of declarations, assignments, operators
+2. `02-breaking.md` - Line breaking and wrapping rules
+3. `03-braces.md` - Brace placement styles (K&R, Allman, GNU, etc.)
+4. `04-indentation.md` - Indentation rules and special cases
+5. `05-spacing.md` - Whitespace control around operators, keywords
+6. `06-includes.md` - Include/import organization and sorting
+7. `07-languages.md` - Language-specific options for C++, Java, JavaScript
+8. `08-comments.md` - Comment formatting and reflow
+9. `09-advanced.md` - Penalty system, raw string formatting, experimental features
+
+**Complete Reference** (complete/):
+
+- `clang-format-cli.md` - Full command-line interface documentation
+- `clang-format-style-options.md` - All 194 style options with examples
+
+## Common Workflows
+
+### Creating New Configuration from Template
+
+To create a new `.clang-format` file:
+
+1. Identify requirements (style guide, team preferences, language)
+2. Select closest template from `assets/configs/`
+3. Copy template to project root as `.clang-format`
+4. Test formatting: `clang-format --dry-run file.cpp`
+5. Customize specific options using references/01-09.md as needed
+6. Verify changes: `clang-format file.cpp | diff - file.cpp`
+
+Example:
+
+```bash
+# Copy Google C++ template
+cp assets/configs/google-cpp-modified.clang-format /path/to/project/.clang-format
+
+# Test on sample file
+clang-format --dry-run /path/to/project/src/main.cpp
+
+# Apply if satisfied
+clang-format -i /path/to/project/src/*.cpp
+```
+
+### Analyzing Existing Code Style
+
+To generate configuration matching existing code:
+
+1. Examine code samples for formatting patterns
+2. Identify key characteristics:
+   - Brace placement → consult `references/03-braces.md`
+   - Indentation (spaces/tabs, width) → consult `references/04-indentation.md`
+   - Spacing (operators, keywords) → consult `references/05-spacing.md`
+   - Line breaking (column limit, wrapping) → consult `references/02-breaking.md`
+   - Alignment patterns → consult `references/01-alignment.md`
+3. Map patterns to closest base style in `references/quick-reference.md`
+4. Start with that template from `assets/configs/`
+5. Override specific options to match observed patterns
+6. Test on representative code samples
+7. Iterate until formatting matches existing style
+
+This workflow minimizes whitespace-only changes when introducing clang-format to existing projects.
+
+### Setting Up Editor Integration
+
+To enable format-on-save in editors:
+
+**Vim**:
+
+1. Copy `assets/integrations/vimrc-clang-format.vim` content to `.vimrc`
+2. Restart Vim or source configuration
+3. Save any C/C++/Java file to trigger formatting
+
+**Emacs**:
+
+1. Copy `assets/integrations/emacs-clang-format.el` to Emacs config
+2. Restart Emacs or evaluate configuration
+3. Save any supported file to trigger formatting
+
+**Other editors**: Consult `references/cli-usage.md` for VS Code, CLion, and other editor setup instructions.
+
+### Setting Up Git Pre-commit Hook
+
+To automatically format staged changes before commit:
+
+1. Copy `assets/integrations/pre-commit` to `.git/hooks/pre-commit`
+2. Make executable: `chmod +x .git/hooks/pre-commit`
+3. Test by staging and committing changes
+
+The hook formats only staged files, preserving unstaged changes.
+
+### Troubleshooting Formatting Issues
+
+When formatting produces unexpected results:
+
+1. Verify configuration detection: `clang-format --dump-config file.cpp`
+2. Check command options in `references/cli-usage.md`
+3. Identify affected formatting category (braces, spacing, breaking, etc.)
+4. Consult relevant category guide in references/01-09.md
+5. Test isolated options: create minimal config with suspect option
+6. For comprehensive option details, check `references/complete/clang-format-style-options.md`
+
+### Setting Up CI/CD Formatting Checks
+
+To enforce formatting in continuous integration:
+
+1. Review CI examples in `references/cli-usage.md`
+2. Add clang-format check to pipeline:
+   ```bash
+   # Check formatting without modifying files
+   clang-format --dry-run --Werror src/**/*.{cpp,h}
+   ```
+3. Configure to fail build on formatting violations
+4. Document formatting requirements for contributors
+
+## Key Concepts
+
+**Base Styles**: Predefined configurations (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft, GNU) provide starting points. Set with `BasedOnStyle: Google` then override specific options.
+
+**Multi-Language Support**: Configure different languages separately in single file using `Language:` key. See `assets/configs/multi-language.clang-format` for example.
+
+**Penalty System**: clang-format uses penalties to choose between formatting alternatives. Higher penalty values discourage specific choices. See `references/09-advanced.md` for details.
+
+**Progressive Refinement**: Start with template closest to requirements, then customize incrementally. Test frequently on representative code samples.
+
+## Testing Configurations
+
+```bash
+# Preview changes without modifying file
+clang-format --dry-run file.cpp
+
+# Show diff of proposed changes
+clang-format file.cpp | diff - file.cpp
+
+# Apply formatting to file
+clang-format -i file.cpp
+
+# Format entire project
+find src include -name '*.cpp' -o -name '*.h' | xargs clang-format -i
+
+# Check formatting in CI (fail on violations)
+clang-format --dry-run --Werror src/**/*.{cpp,h}
+```
+
+## Navigation Strategy
+
+For most tasks, follow this progression:
+
+1. **Start with templates**: Browse `assets/configs/` for ready-to-use configurations
+2. **Quick reference**: Check `references/quick-reference.md` for complete configurations with explanations
+3. **Category guides**: Consult `references/01-09.md` for specific option categories
+4. **CLI usage**: Reference `references/cli-usage.md` for command-line and integration details
+5. **Complete reference**: Use `references/complete/` for exhaustive option documentation
+
+When analyzing code or troubleshooting, identify the formatting aspect (braces, spacing, alignment, etc.) and jump directly to the relevant category guide in references/.