# How AI Agents Integrate with the go-modern-guidelines Skill Package

> Learn how AI agents integrate with the go-modern-guidelines skill package. Install the CLI tool to get version-specific Go guidelines for informed code generation.

- Repository: [JetBrains/go-modern-guidelines](https://github.com/jetbrains/go-modern-guidelines)
- Tags: how-to-guide
- Published: 2026-08-30

---

**AI agents integrate with the go-modern-guidelines skill package by installing the CLI tool and invoking its `list` or `explain` commands to retrieve version-specific Go guidelines that inform code generation.**

The JetBrains/go-modern-guidelines repository provides a lightweight CLI that functions as a skill for AI coding assistants. **AI agents integrate with the go-modern-guidelines skill package** by executing the binary to obtain filtered, project-specific recommendations that ensure generated Go code reflects modern idioms appropriate for the target language version.

## How the Skill Integration Works

The integration between an AI agent and the skill package follows a structured seven-step execution flow. This process transforms the static guideline database into dynamic, context-aware coding instructions.

When the agent's marketplace system (such as Junie, Claude Code, Codex, Cursor, or [`skills.sh`](https://github.com/JetBrains/go-modern-guidelines/blob/main/skills.sh)) registers the repository as a plugin, the integration begins. The agent calls the installed `go-modern-guidelines` binary with either the `list` command to retrieve applicable guideline IDs or the `explain` command to fetch detailed guidance for specific rules.

In [`main.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/main.go), the entry point forwards all arguments directly to `cli.Run`, which dispatches to the appropriate handler. The `runList` function in [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go) utilizes `goversion.Resolve` to detect the target Go version from `go.mod`, `go.work`, or an explicit `--go-version` flag. This resolution ensures the guidelines match the project's actual language level.

The `mustLoadModernGoGuidelines` function in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) parses the embedded [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) file using `schema.Parse`, caching the resulting `modernGoGuideline` structs. The `supportedGuidelines` function then filters this dataset using `goversion.Compare` to remove any guidelines whose `sinceVersion` exceeds the resolved Go version.

For output generation, `ListText` produces a plain-text mapping of guideline IDs to short descriptions, while `ExplainText` formats detailed multi-section output containing summaries, implementation details, and before/after code examples. The CLI writes these results to stdout, which the agent captures and feeds to its underlying LLM to guide subsequent code generation.

## CLI Commands for Agent Integration

The skill package exposes two primary commands that agents invoke to retrieve guidance.

**The `list` command** returns a filtered set of guideline identifiers relevant to the detected Go version. Agents typically call this with a file path argument to automatically resolve the version:

```go
output, err := exec.Command("go-modern-guidelines", "list", "--file-path", "go.mod").Output()

```

**The `explain` command** retrieves comprehensive documentation for specific guidelines by ID. This enables agents to obtain detailed context about particular language features before generating code:

```go
ids := []string{"slice-contains", "max-function"}
cmd := exec.Command("go-modern-guidelines", "explain", "--guideline-id", strings.Join(ids, ","))

```

The `explain` handler in [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go) processes these IDs and delegates to `ExplainText` for formatting.

## Version Resolution and Filtering

Accurate version detection forms the core of the integration's utility. The `goversion.Resolve` function examines project files to determine the effective Go version, while `goversion.Compare` implements semantic version comparison to filter the guideline database.

This filtering occurs in `supportedGuidelines` within [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go). The function iterates through all loaded guidelines and excludes those requiring newer Go versions than the target project supports. This ensures agents never recommend language features that would break project compatibility.

## Key Implementation Files

Understanding the source structure helps developers customize or debug the integration:

- **[`main.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/main.go)** - Entry point that forwards CLI arguments to `cli.Run`.
- **[`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go)** - Implements `runList` and `runExplain` handlers, version flag parsing, and usage formatting.
- **[`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go)** - Contains `mustLoadModernGoGuidelines` for JSON parsing, `supportedGuidelines` for version filtering, and text formatting functions `ListText` and `ExplainText`.
- **[`internal/goversion/goversion.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/goversion/goversion.go)** - Provides `Resolve` for version detection and `Compare` for semantic version operations.
- **[`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json)** (embedded) - The complete database of modern Go guidelines with metadata including `sinceVersion` and code examples.

## Practical Integration Examples

Agents can integrate using direct system calls or wrapper utilities like [`skills.sh`](https://github.com/JetBrains/go-modern-guidelines/blob/main/skills.sh).

**Example 1: Retrieving relevant guidelines for a project**

```go
// Agent runtime pseudo-code
output, err := exec.Command("go-modern-guidelines", "list", "--file-path", "go.mod").Output()
if err != nil {
    // handle error
}
fmt.Println(string(output))

```

**Example 2: Fetching detailed explanations for specific rules**

```go
// Agent requesting guidance on particular features
ids := []string{"slice-contains", "max-function"}
cmd := exec.Command("go-modern-guidelines", "explain", "--guideline-id", strings.Join(ids, ","))
data, _ := cmd.Output()
fmt.Println(string(data))

```

**Example 3: Using the Node.js skills wrapper**

```javascript
import { execSync } from "child_process";

const result = execSync("npx skills use-modern-go list --go-version 1.26");
console.log(result.toString());
// → Prints short guideline list for Go 1.26

```

## Summary

- AI agents integrate by invoking the `go-modern-guidelines` CLI as a skill through marketplace systems or direct installation.
- The **`list` command** provides filtered guideline IDs based on the project's Go version, detected via `goversion.Resolve`.
- The **`explain` command** delivers detailed documentation including before/after examples for specific guideline IDs.
- Version filtering in `supportedGuidelines` ensures recommendations match the target Go version using `goversion.Compare`.
- Key source files include [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go) for command handling and [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) for data processing.
- Output flows from the CLI stdout to the agent's LLM, enabling context-aware code generation that respects modern Go idioms.

## Frequently Asked Questions

### How does the skill determine which Go version to target?

The `runList` function in [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go) calls `goversion.Resolve` to analyze `go.mod`, `go.work`, or an explicit `--go-version` flag passed by the agent. This ensures the guidelines are filtered to only include features available in the target version.

### Can agents request guidelines for a specific Go version without a project file?

Yes. Agents can specify the `--go-version` flag directly when invoking either the `list` or `explain` commands. This bypasses automatic detection and allows the `supportedGuidelines` function to filter the embedded [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) data for that specific version.

### What is the difference between the `list` and `explain` commands?

The `list` command uses `ListText` to generate a concise mapping of guideline IDs to short descriptions, suitable for quick scanning. The `explain` command uses `ExplainText` to produce detailed multi-section output including summaries, implementation details, and before/after code examples for the requested IDs.

### How is the guideline data stored and accessed?

All guidelines are embedded in the binary as [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json). The `mustLoadModernGoGuidelines` function in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) parses this JSON at runtime using `schema.Parse` and caches the results in the `modernGoGuidelines` variable, ensuring fast access during CLI execution.