home / skills / openclaw / skills / go-linter-configuration

go-linter-configuration skill

needs review

/skills/irook661/go-linter-configuration

This skill helps configure and troubleshoot golangci-lint for Go projects, resolving imports, type-checking, and CI/local performance.

npx playbooks add skill openclaw/skills --skill go-linter-configuration

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

4.3 KB

---
name: go-linter-configuration
description: "Configure and troubleshoot golangci-lint for Go projects. Handle import resolution issues, type-checking problems, and optimize configurations for both local and CI environments."
metadata:
  {
    "openclaw":
      {
        "emoji": "🔍",
        "requires": { "bins": ["go", "golangci-lint"] },
        "install":
          [
            {
              "id": "golang",
              "kind": "script",
              "script": "curl -L https://golang.org/dl/go1.21.5.linux-amd64.tar.gz | tar -C /usr/local -xzf -",
              "bins": ["go"],
              "label": "Install Go",
            },
            {
              "id": "golangci",
              "kind": "script",
              "script": "curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.59.1",
              "bins": ["golangci-lint"],
              "label": "Install golangci-lint",
            },
          ],
      },
  }
---

# Go Linter Configuration Skill

Configure and troubleshoot golangci-lint for Go projects. This skill helps handle import resolution issues, type-checking problems, and optimize configurations for both local and CI environments.

## Installation

Install golangci-lint:

```bash
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
```

Or use the official installation script:

```bash
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.59.1
```

## Basic Usage

Run linter on entire project:

```bash
golangci-lint run ./...
```

Run with specific configuration:

```bash
golangci-lint run --config .golangci.yml ./...
```

## Configuration File (.golangci.yml)

### Minimal Configuration (for CI environments with import issues)
```yaml
run:
  timeout: 5m
  tests: false
  build-tags: []

linters:
  disable-all: true
  enable:
    - gofmt          # Format checking only

linters-settings:
  gofmt:
    simplify: true

issues:
  exclude-use-default: false
  max-issues-per-linter: 50
  max-same-issues: 3

output:
  format: tab
```

### Standard Configuration (for local development)
```yaml
run:
  timeout: 5m
  tests: true
  build-tags: []

linters:
  enable:
    - gofmt
    - govet
    - errcheck
    - staticcheck
    - unused
    - gosimple
    - ineffassign

linters-settings:
  govet:
    enable:
      - shadow
  errcheck:
    check-type-assertions: true
  staticcheck:
    checks: ["all"]

issues:
  exclude-use-default: false
  max-issues-per-linter: 50
  max-same-issues: 3

output:
  format: tab
```

## Troubleshooting Common Issues

### "undefined: package" Errors
Problem: Linter reports undefined references to imported packages
Solution: Use minimal configuration with `disable-all: true` and only enable basic linters like `gofmt`

### Import Resolution Problems
Problem: CI environment cannot resolve dependencies properly
Solution: 
1. Ensure go.mod and go.sum are up to date
2. Use `go mod download` before running linter in CI
3. Consider using simpler linters in CI environment

### Type-Checking Failures
Problem: Linter fails during type checking phase
Solution:
1. Temporarily disable complex linters that require type checking
2. Use `--fast` flag for quicker, less intensive checks
3. Verify all imports are properly declared

## CI/CD Optimization

For GitHub Actions workflow:

```yaml
name: Code Quality

on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: Set up Go
      uses: actions/setup-go@v4
      with:
        go-version: '1.21'
        cache: true

    - name: Download dependencies
      run: go mod download

    - name: Install golangci-lint
      run: |
        curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.59.1

    - name: Lint
      run: golangci-lint run --config .golangci.yml ./...
```

## Linter Selection Guidelines

- **gofmt**: For formatting consistency
- **govet**: For semantic errors
- **errcheck**: For unchecked errors
- **staticcheck**: For static analysis
- **unused**: For dead code detection
- **gosimple**: For simplification suggestions
- **ineffassign**: For ineffective assignments

Choose linters based on project needs and CI performance requirements.

Overview

This skill configures and troubleshoots golangci-lint for Go projects to improve code quality while avoiding CI and local environment pitfalls. It helps resolve import and type-checking errors, recommends linter sets for different contexts, and provides CI-optimized setups. The guidance balances thorough static analysis with practical performance and reliability constraints.

How this skill works

The skill inspects and generates recommended .golangci.yml configurations for local development and CI, toggling linters that require type information when necessary. It provides step-by-step fixes for common problems like undefined package errors, import resolution failures, and type-checking crashes, and suggests workflow steps (e.g., go mod download) to ensure the linter runs reliably in CI. It also explains which linters to enable based on trade-offs between accuracy and speed.

When to use it

Onboarding a Go project to consistent linting standards (local and CI).
When golangci-lint fails with undefined imports or type-checking errors.
Optimizing lint runs to reduce CI timeouts or flaky checks.
Creating minimal linting for dependency-limited CI environments.
Choosing linters for security, correctness, or maintenance priorities.

Best practices

Keep a minimal CI config that disables heavy type-checking linters if dependencies can’t be resolved; enable only fast linters like gofmt.
Run go mod download (or ensure go.sum is current) before linting in CI to avoid import resolution errors.
Use a fuller local config that enables govet, staticcheck, errcheck, and unused for developer feedback.
Cap issues per linter (e.g., max-issues-per-linter: 50) to keep output actionable.
Use --fast or temporarily disable type-checking linters when debugging failures to isolate the root cause.

Example use cases

Create a .golangci.yml minimal profile for CI that disables all but gofmt to avoid undefined package errors.
Diagnose linter crashes by disabling heavy linters and re-enabling them incrementally to find the failing package.
Add a GitHub Actions job that runs go mod download and then golangci-lint run to ensure consistent CI linting.
Switch to a comprehensive local config for full static analysis during development and code review.
Limit linter output in large repos using max-issues-per-linter and max-same-issues to reduce noise.

FAQ

What if golangci-lint reports undefined imports in CI?

Ensure go.mod and go.sum are up to date, run go mod download before linting, or use a minimal CI config that disables type-checking linters.

How do I speed up lint runs in CI?

Use a minimal linter set, enable caching for modules, run golangci-lint with --fast, and limit issues per linter to reduce runtime and output.