Gen Linter

---
name: gen-linter
description: Generate .golangci.yml configuration for Go linting with 90+ linters
argument-hint: "[--force] [--dry-run]"
user-invocable: true
disable-model-invocation: true
allowed-tools: Read, Write, Bash(git:*), Bash(test:*), AskUserQuestion
---

# Generate golangci-lint Configuration

Instantly create a professional `.golangci.yml` configuration for Go projects with comprehensive linting coverage. This skill replaces the multi-step manual setup with a single invocation.

## Why This Skill Exists

**Problem**: Setting up golangci-lint requires manually creating YAML configuration, understanding 90+ linter options, and balancing strict quality checks with pragmatic development - a 15-30 minute process prone to over-configuration.

**Solution**: One-command generation that:
- Creates battle-tested `.golangci.yml` (224 lines)
- Enables all linters by default with sensible exclusions
- Balances code quality with development velocity
- Works out-of-the-box for most Go projects
- Includes inline documentation for customization

## Content Generation Rules

**CRITICAL**: When generating any content (configuration files, commit messages, or any other output):
- **NEVER** add Claude Code attribution or co-authorship
- **NEVER** include phrases like "Generated by Claude", "Created with Claude Code", or similar
- **NEVER** add "Co-Authored-By: Claude" in commit messages or documentation
- All generated content should appear as if written by a human developer
- Focus on technical accuracy and providing working templates

## Process (6 Phases)

### Phase 1: Prerequisites Validation

**Critical checks before proceeding:**

1. **Validate Git repository:**
   ```bash
   git rev-parse --git-dir
   ```
   - If fails: Exit with error "Not a git repository. Run 'git init' first."

2. **Validate Go project:**
   ```bash
   test -f go.mod
   ```
   - If fails: Exit with error "go.mod not found. This skill is for Go projects only."

3. **Check existing configuration:**
   ```bash
   test -f .golangci.yml || test -f .golangci.yaml
   ```
   - If either exists: Store `existingConfig = true` and `existingFile = <filename>`
   - If not exists: Store `existingConfig = false`

4. **Check for golangci-lint binary** (non-blocking):
   ```bash
   command -v golangci-lint
   ```
   - If not found: Store `linterNotInstalled = true` (will show warning later)
   - If found: Check version with `golangci-lint --version` and store for report

5. **Verify skill assets directory:**
   - Use Read tool to verify `${CLAUDE_PLUGIN_ROOT}/assets/linter/.golangci.yml` exists
   - If fails: Exit with error "Skill assets directory not found at ${CLAUDE_PLUGIN_ROOT}/assets/linter/. Plugin may be corrupted. Reinstall the go-specialist plugin."

### Phase 2: Argument Parsing

Parse skill arguments from `$argument` string:

**Supported flags:**
- `--force`: Skip confirmation if .golangci.yml already exists
- `--dry-run`: Show preview without writing file

**Parsing logic:**
```
arguments = split($argument by space)
for each arg in arguments:
  if arg == "--force": set forceMode = true
  if arg == "--dry-run": set dryRunMode = true
```

**File Selection:**
- Single file generation: `.golangci.yml` (224 lines)

### Phase 3: Template Reading

**Read template file** from skill assets directory:

**Template location:**
- Path: `${CLAUDE_PLUGIN_ROOT}/assets/linter/.golangci.yml`
- Expected size: ~6.5 KB (224 lines)
- Format: YAML with inline comments

**Reading logic:**
```
Use Read tool to read: ${CLAUDE_PLUGIN_ROOT}/assets/linter/.golangci.yml
Store content as: templateContent
Verify: content is not empty and starts with "# golangci-lint"
```

**Error handling:**
- If file not found: Exit with error "Template file not found at ${CLAUDE_PLUGIN_ROOT}/assets/linter/.golangci.yml"
- If file empty: Exit with error "Template file is empty or corrupted"

**No variable substitution required** - the template is copied as-is.

### Phase 4: User Confirmation

**Build preview message:**

```
📋 golangci-lint Configuration Preview

Files to be created:
  .golangci.yml (224 lines, ~6.5 KB)

Configuration features:
  • Enables all linters by default (90+)
  • Disables overly strict linters (goerr113, wrapcheck, etc.)
  • 5-minute timeout for large projects
  • Fast mode with caching enabled
  • Parallel execution across all CPUs
  • Project-agnostic settings

Excluded linters (too opinionated):
  • depguard, exhaustruct, gci, gochecknoglobals
  • godox, goerr113, inamedparam, maintidx
  • nonamedreturns, testpackage, wrapcheck, wsl

Integration ready:
  ✓ GitHub Actions (via gen-github-dir)
  ✓ GitLab CI (via gen-gitlab-ci)
  ✓ Task runner (via gen-taskfiles)
  ✓ Pre-commit hooks
  ✓ VS Code, GoLand, Vim/Neovim

<CONDITIONAL WARNINGS>
```

**Conditional warnings:**

If `existingConfig = true`:
```
⚠️  WARNING: Existing configuration detected
    File: <existingFile>
    This will OVERWRITE your existing linter configuration.
    Consider backing up your current settings before proceeding.
```

If `linterNotInstalled = true`:
```
ℹ️  INFO: golangci-lint binary not found
    Configuration will be created, but you'll need to install golangci-lint to use it:
      • macOS: brew install golangci-lint
      • Other: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
    After installation, verify with: golangci-lint --version
```

**Confirmation logic:**

If `dryRunMode = true`:
```
[DRY RUN MODE - No files will be written]
```
Skip to Phase 6 (report preview only)

If `forceMode = true`:
```
[--force mode enabled, skipping confirmation]
```
Proceed to Phase 5

If `existingConfig = true` and `forceMode = false`:
```
Use AskUserQuestion:
  Question: "Overwrite existing .golangci.yml configuration?"
  Options:
    - "Yes, overwrite configuration" (proceed to Phase 5)
    - "No, cancel operation" (exit with message "Operation cancelled by user")
```

If `existingConfig = false`:
```
Use AskUserQuestion:
  Question: "Create .golangci.yml in project root?"
  Options:
    - "Yes, create configuration" (proceed to Phase 5)
    - "No, cancel operation" (exit with message "Operation cancelled by user")
```

### Phase 5: File Creation

**Write configuration file:**

Use Write tool to create:
```
File: .golangci.yml (in project root, not in .github/)
Content: <templateContent from Phase 3>
```

**Writing logic:**
```
Use Write tool:
  file_path: ./.golangci.yml (absolute path to project root)
  content: templateContent (no modifications, copy as-is)
```

**Error handling:**
- If write fails: Report error to user with file path and error message
- If write succeeds: Proceed to Phase 6

### Phase 6: Validation & Success Report

**Post-creation validation:** confirm `.golangci.yml` exists and is non-zero, and report its
line count.

**If `dryRunMode == true`:** report that nothing was written, name the file that *would* be
created with its line count, and note that dropping `--dry-run` performs the creation.

**Otherwise report to the user** — cover these facts; no fixed layout required:

- **Files written:** `.golangci.yml` with its line count.
- **Next steps:** run `golangci-lint run ./...`; auto-fix what can be fixed with
  `golangci-lint run --fix ./...`; see which linters are active via
  `golangci-lint run -v ./...`; isolate one linter with
  `golangci-lint run --disable-all --enable=govet ./...`; edit `.golangci.yml` to adjust
  enabled linters, timeouts or exclusions.
- **CI integration:** `/gen-github-dir` for GitHub Actions (includes a linter workflow),
  `/gen-gitlab-ci` for GitLab CI (includes a lint job), `/gen-taskfiles` for the lint tasks.
- **Editor integration:** VS Code — install the Go extension and set
  `"go.lintTool": "golangci-lint"`; GoLand — Settings → Tools → File Watchers → add
  golangci-lint; Vim/Neovim — configure the ale plugin with golangci-lint.
- **Enabled features:** 90+ linters on by default, balanced for quality vs. pragmatism, fast
  execution with caching, parallel processing, CI/CD ready.
- **Missing tools:** if `linterNotInstalled`, remind to install it —
  `brew install golangci-lint` on macOS, otherwise
  `go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest` — and verify with
  `golangci-lint --version`.
- **Docs:** https://golangci-lint.run/usage/configuration/

**On failure:** report which files were written, which failed and why, and that `--force`
retries. Partial success is a warning, total failure an error — for a total failure also
name the likely causes (permissions, disk space, filesystem restrictions).

## Integration with Other Skills

This skill works seamlessly with other go-specialist skills:

**Before gen-linter:**
- None required (can be run first)

**After gen-linter:**
- `/gen-github-dir` - Includes linter workflow using this configuration
- `/gen-gitlab-ci` - Includes lint job using this configuration
- `/gen-taskfiles` - Includes lint tasks for local development

**Typical workflow:**
```bash
# 1. Generate linter config
/gen-linter

# 2. Fix initial issues
golangci-lint run --fix ./...

# 3. Set up CI/CD
/gen-github-dir  # or /gen-gitlab-ci

# 4. Add task automation
/gen-taskfiles
```

## Best Practices

**Configuration maintenance:**
- Review and update `.golangci.yml` when upgrading golangci-lint versions
- Adjust linter selection based on team preferences
- Document any custom exclusions in comments
- Test configuration changes with `--fast` flag first

**CI/CD integration:**
- Always run linter in CI before tests
- Use `--timeout=5m` for large projects
- Cache golangci-lint binary and build cache
- Block PRs with linting failures

**Local development:**
- Run linter before committing: `golangci-lint run ./...`
- Use auto-fix when possible: `golangci-lint run --fix ./...`
- Configure editor integration for real-time feedback
- Set up pre-commit hooks for automatic checks

**Team adoption:**
- Gradually enable stricter linters
- Document project-specific conventions
- Review linter output in code reviews
- Share configuration explanations with team

## Limitations & Caveats

**Golangci-lint installation:**
- This skill only creates configuration
- Binary must be installed separately
- Requires Go 1.21+ for full linter compatibility

**Configuration style:**
- Opinionated defaults (pragmatic over perfect)
- May need customization for specific projects
- Some linters may conflict with project conventions

**Performance considerations:**
- Initial run can be slow on large codebases
- Enable caching for faster subsequent runs
- Use `--fast` flag for quick checks during development

**CI/CD requirements:**
- Workflows expect golangci-lint v2.4.0+
- Docker images may need golangci-lint installation
- GitHub Actions uses dedicated golangci-lint action

## Error Recovery

**If linter fails after generation:**
1. Check golangci-lint version: `golangci-lint --version`
2. Validate configuration: `golangci-lint run --help`
3. Test with minimal config: `golangci-lint run --disable-all --enable=govet ./...`
4. Check for syntax errors: `yamllint .golangci.yml`

**If too many issues reported:**
1. Start with auto-fix: `golangci-lint run --fix ./...`
2. Disable problematic linters temporarily
3. Use `--exclude` patterns for known issues
4. Gradually enable stricter linters

**If conflicts with existing tooling:**
1. Review `.golangci.yml` disable list
2. Adjust exclusions for project needs
3. Check for conflicting editor plugins
4. Verify Go version compatibility

## Additional Resources

**Official documentation:**
- Configuration reference: https://golangci-lint.run/usage/configuration/
- Linters list: https://golangci-lint.run/usage/linters/
- Editor integrations: https://golangci-lint.run/usage/integrations/

**Related skills:**
- `/gen-github-dir` - GitHub Actions with linter workflow
- `/gen-gitlab-ci` - GitLab CI with lint jobs
- `/gen-taskfiles` - Task automation with lint tasks

**Community resources:**
- Example configurations: https://github.com/golangci/golangci-lint/tree/master/test
- Best practices: https://golangci-lint.run/usage/best-practices/
- GitHub repository: https://github.com/golangci/golangci-lint