Csharpier

CSharpier for .NET

Trigger On

• the repo uses or wants CSharpier
• the team prefers an opinionated formatter over many configurable style knobs

Value

• produce a concrete project delta: code, docs, config, tests, CI, or review artifact
• reduce ambiguity through explicit planning, verification, and final validation skills
• leave reusable project context so future tasks are faster and safer

Do Not Use For

• repos that already standardized on dotnet format as the only formatter

Inputs

• the nearest AGENTS.md
• current formatting ownership model
• any .csharpierignore or .editorconfig

Quick Start

1. Read the nearest AGENTS.md and confirm scope and constraints. 2. Run this skill's Workflow through the Ralph Loop until outcomes are acceptable. 3. Return the Required Result Format with concrete artifacts and verification evidence.

Workflow

1. Decide whether CSharpier is the primary formatter or only complements other tools. 2. Use check mode in CI. 3. Keep ignore files and config explicit in repo. 4. Do not let CSharpier and dotnet format both own the same formatting space without documentation.

Bootstrap When Missing

If CSharpier is not configured yet:

1. Detect current state:

• rg --files -g '.config/dotnet-tools.json' -g '.csharpierignore'
• dotnet tool list --local
• dotnet tool list --global

2. Prefer local tool installation for reproducible CI:

• dotnet new tool-manifest (if missing)
• dotnet tool install csharpier

3. Add .csharpierignore when needed and define ownership vs dotnet format in AGENTS.md. 4. Add dotnet csharpier check . to CI. 5. Run dotnet csharpier check . and return status: configured or status: improved. 6. If the repo intentionally uses only dotnet format, return status: not_applicable unless migration is requested.

Deliver

• explicit CSharpier ownership and commands
• CI-safe formatter checks

Validate

• formatter ownership is not ambiguous
• the repo is comfortable with opinionated formatting decisions

Ralph Loop

Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.

1. Plan first (mandatory):

• analyze current state
• define target outcome, constraints, and risks
• write a detailed execution plan
• list final validation skills to run at the end, with order and reason

2. Execute one planned step and produce a concrete delta. 3. Review the result and capture findings with actionable next fixes. 4. Apply fixes in small batches and rerun the relevant checks or review steps. 5. Update the plan after each iteration. 6. Repeat until outcomes are acceptable or only explicit exceptions remain. 7. If a dependency is missing, bootstrap it or return status: not_applicable with explicit reason and fallback path.

Required Result Format

• status: complete | clean | improved | configured | not_applicable | blocked
• plan: concise plan and current iteration step
• actions_taken: concrete changes made
• validation_skills: final skills run, or skipped with reasons
• verification: commands, checks, or review evidence summary
• remaining: top unresolved items or none

For setup-only requests with no execution, return status: configured and exact next commands.

Load References

• references/commands.md
• references/config.md
• references/csharpier.md

Example Requests

• "Set up CSharpier for this repo."
• "Compare CSharpier and dotnet format."

CSharpier CLI Commands

Installation

Local Tool (Recommended)

# Create tool manifest if missing
dotnet new tool-manifest

# Install CSharpier as local tool
dotnet tool install csharpier

# Update to latest version
dotnet tool update csharpier

Global Tool

# Install globally
dotnet tool install -g csharpier

# Update globally
dotnet tool update -g csharpier

Formatting Commands

Format Files

# Format all files in current directory recursively
dotnet csharpier .

# Format specific file
dotnet csharpier MyFile.cs

# Format specific directory
dotnet csharpier src/

# Format multiple paths
dotnet csharpier src/ tests/

Check Mode (CI)

# Check formatting without modifying files
# Returns non-zero exit code if files need formatting
dotnet csharpier check .

# Check specific directory
dotnet csharpier check src/

Additional Options

# Write formatted files to stdout instead of modifying
dotnet csharpier --write-stdout MyFile.cs

# Skip write (dry run) - validates syntax without output
dotnet csharpier --skip-write .

# Include generated files (excluded by default)
dotnet csharpier --include-generated .

# Disable cache (useful for debugging)
dotnet csharpier --no-cache .

# Use fast exit on first error
dotnet csharpier --fast .

# Pipe content through stdin/stdout
cat MyFile.cs | dotnet csharpier --write-stdout

Exit Codes

CI Integration Examples

GitHub Actions

- name: Check formatting
  run: dotnet csharpier check .

Azure DevOps

- script: dotnet csharpier check .
  displayName: 'Check CSharpier formatting'

Pre-commit Hook

#!/bin/sh
dotnet csharpier check .

MsBuild Integration

Add to .csproj for build-time formatting check:

<Target Name="CheckFormatting" BeforeTargets="Build">
  <Exec Command="dotnet csharpier check ." />
</Target>

IDE Extensions

• Visual Studio: CSharpier extension from VS Marketplace
• VS Code: CSharpier extension
• JetBrains Rider: CSharpier plugin

Configure format-on-save in IDE settings for seamless workflow.

CSharpier Configuration

Configuration File

CSharpier uses .csharpierrc (or .csharpierrc.json, .csharpierrc.yaml) in the repository root.

JSON Format (.csharpierrc or .csharpierrc.json)

{
  "printWidth": 100,
  "useTabs": false,
  "tabWidth": 4,
  "endOfLine": "auto"
}

YAML Format (.csharpierrc.yaml)

printWidth: 100
useTabs: false
tabWidth: 4
endOfLine: auto

Configuration Options

printWidth

Maximum line width before wrapping.

• Type: integer
• Default: 100
• Range: 1-1000

{
  "printWidth": 120
}

useTabs

Use tabs instead of spaces for indentation.

• Type: boolean
• Default: false

{
  "useTabs": true
}

tabWidth

Number of spaces per indentation level (when useTabs is false).

• Type: integer
• Default: 4
• Range: 1-1000

{
  "tabWidth": 2
}

endOfLine

Line ending style.

• Type: string
• Default: "auto"
• Values: "auto", "lf", "crlf"

{
  "endOfLine": "lf"
}

Ignore File

Create .csharpierignore in the repository root to exclude files from formatting.

Syntax

Uses gitignore-style patterns:

# Ignore generated files
**/Generated/**
**/*.generated.cs

# Ignore specific directories
**/obj/
**/bin/
**/Migrations/

# Ignore specific files
src/Legacy/OldCode.cs

# Ignore test fixtures
tests/Fixtures/**/*.cs

Default Exclusions

CSharpier automatically excludes:

• Files in obj/ and bin/ directories
• Files matching *.generated.cs pattern
• Files with <auto-generated> comment header

EditorConfig Integration

CSharpier respects .editorconfig for some settings:

[*.cs]
indent_style = space
indent_size = 4
end_of_line = lf
max_line_length = 100

Priority order:

1. .csharpierrc settings (highest) 2. .editorconfig settings 3. CSharpier defaults (lowest)

Preprocessor Directives

CSharpier handles preprocessor directives but may format them differently than expected. Use .csharpierignore for files with complex preprocessor logic that must not change.

Example Repository Setup

repo/
├── .csharpierrc
├── .csharpierignore
├── .editorconfig
├── .config/
│   └── dotnet-tools.json
└── src/
    └── ...

Minimal .csharpierrc

{
  "printWidth": 100
}

Minimal .csharpierignore

**/Migrations/
**/Generated/

Troubleshooting

Formatting Conflicts with dotnet format

If using both tools, ensure they do not conflict:

1. Disable whitespace/formatting rules in .editorconfig for dotnet format 2. Let CSharpier own all formatting decisions 3. Document ownership in AGENTS.md

Cache Issues

Clear the CSharpier cache if formatting seems inconsistent:

# Disable cache for single run
dotnet csharpier --no-cache .

# Cache location (for manual clearing)
# Windows: %LOCALAPPDATA%/CSharpier
# macOS/Linux: ~/.cache/CSharpier

CSharpier

Open/Free Status

• open source
• free to use

Install

Global tool:

dotnet tool install csharpier -g

Verify First

Before installing, check whether the repo already has a local or global CSharpier tool:

rg --files -g '.config/dotnet-tools.json' -g '.csharpierignore'
dotnet tool list --local
dotnet tool list --global
command -v csharpier

Common Usage

csharpier format .
csharpier check .
dotnet csharpier --version

CI Fit

• use csharpier check . as the gate
• keep .csharpierignore versioned if needed
• document the relationship to .editorconfig and dotnet format

When Not To Use

• when the repo wants detailed .editorconfig-driven formatting rather than one opinionated formatter

Sources

• CSharpier repository