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

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) 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, the entry point forwards all arguments directly to cli.Run, which dispatches to the appropriate handler. The runList function in 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 parses the embedded 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:

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:

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 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. 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 - Entry point that forwards CLI arguments to cli.Run.
• internal/cli/cli.go - Implements runList and runExplain handlers, version flag parsing, and usage formatting.
• internal/guidelines/guidelines.go - Contains mustLoadModernGoGuidelines for JSON parsing, supportedGuidelines for version filtering, and text formatting functions ListText and ExplainText.
• internal/goversion/goversion.go - Provides Resolve for version detection and Compare for semantic version operations.
• 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.

Example 1: Retrieving relevant guidelines for a project

// 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

// 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

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 for command handling and 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 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 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. The mustLoadModernGoGuidelines function in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}