Go Lint Audit Skill | Agent Skills

Go Lint Audit

Extended lint analysis with human-readable explanations. Wraps golangci-lint with better categorization, explanations, and configuration recommendations.

What It Does

Runs golangci-lint with comprehensive linter set
Groups findings by category and severity
Explains each finding in plain language with fix examples
Recommends config improvements for .golangci.yml

Steps

API Integration (Optional)

If GOPHER_GUIDES_API_KEY is set, verify it:

curl -s -H "Authorization: Bearer $GOPHER_GUIDES_API_KEY" \
  https://gopherguides.com/api/gopher-ai/me

If not set, local analysis tools (go vet, staticcheck, golangci-lint) still provide comprehensive analysis. Set the key for enhanced API-powered insights. Get your key at gopherguides.com.

1. Check Configuration

# Find existing config
ls .golangci.yml .golangci.yaml .golangci.toml 2>/dev/null

# If no config exists, note it — will recommend one

2. Run Analysis

# Run with all findings shown
golangci-lint run \
  --max-issues-per-linter 0 \
  --max-same-issues 0 \
  --out-format json \
  ./... 2>&1

If golangci-lint is not installed:

# Install
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

3. Categorize Findings

Group findings into categories:

| Category | Linters | Severity | |----------|---------|----------| | Bugs | govet, staticcheck, gosec | 🔴 Critical | | Error Handling | errcheck, errorlint | 🔴 Critical | | Performance | prealloc, bodyclose | 🟡 Warning | | Style | gofmt, goimports, misspell | 🟢 Suggestion | | Complexity | cyclop, gocognit, funlen | 🟡 Warning | | Maintainability | gocritic, revive, dupl | 🟡 Warning | | Security | gosec | 🔴 Critical |

4. Explain Findings

For each finding, provide:

What it means in plain language
Why it matters (bug risk, performance, maintainability)
How to fix it with a code example
When to ignore it (if applicable, with //nolint directive)

Example:

#### errcheck: Error return value of `os.Remove` is not checked

**What:** The function `os.Remove()` returns an error that your code ignores.

**Why:** If the file doesn't exist or can't be deleted, your program won't know,
potentially leaving stale files or masking permission issues.

**Fix:**
```go
// Before
os.Remove(tempFile)

// After
if err := os.Remove(tempFile); err != nil {
    return fmt.Errorf("failed to remove temp file %s: %w", tempFile, err)
}
```

**Ignore:** Only if the file removal is truly best-effort:
```go
_ = os.Remove(tempFile) //nolint:errcheck // best-effort cleanup
```

5. Configuration Recommendations

Suggest .golangci.yml improvements:

# Recommended golangci-lint configuration
linters:
  enable:
    # Bug detection
    - govet
    - staticcheck
    - gosec
    # Error handling
    - errcheck
    - errorlint
    # Style
    - gofmt
    - goimports
    - misspell
    # Complexity
    - cyclop
    - gocognit
    # Maintainability
    - gocritic
    - revive
    - dupl
    # Performance
    - prealloc
    - bodyclose

linters-settings:
  cyclop:
    max-complexity: 15
  gocognit:
    min-complexity: 20
  funlen:
    lines: 80
    statements: 50
  goimports:
    local-prefixes: github.com/yourorg
  errcheck:
    check-type-assertions: true
    check-blank: true

issues:
  exclude-use-default: false
  max-issues-per-linter: 0
  max-same-issues: 0

run:
  timeout: 5m

Output Format

## Lint Audit Report

**Project:** {name}
**Linters:** {count} active
**Total Findings:** {count}

### Summary

| Category | Count | Severity |
|----------|-------|----------|
| Bugs | {n} | 🔴 |
| Error Handling | {n} | 🔴 |
| Performance | {n} | 🟡 |
| Style | {n} | 🟢 |
| Complexity | {n} | 🟡 |

### Findings by Category

#### 🔴 Bugs ({n})
{detailed findings with explanations}

#### 🔴 Error Handling ({n})
{detailed findings with explanations}

...

### Configuration Recommendations
{suggested .golangci.yml changes}

### Quick Fixes Available
{list of auto-fixable issues with `golangci-lint run --fix`}

Gopher Guides API Integration

Note: API calls send source code to gopherguides.com for analysis. Ensure your organization's policy permits external code analysis.

For full API usage examples, see API Usage Reference.

Helper Script

After installation via install.sh, scripts are at .github/skills/scripts/. Run the full audit including lint + API:

bash .github/skills/scripts/audit.sh

Severity Configuration

After installation via install.sh, lint categories map to severity levels at .github/skills/config/severity.yaml. See the Setup Guide for details.

References

Existing gopher-ai command: plugins/go-dev/commands/lint-fix.md
golangci-lint documentation
Go Code Review Comments

Agent Skills: Go Lint Audit

Install this agent skill to your local

Skill Files