mcp2skill: Instructions file for Codex

AGENTS.md

Instructions for AI coding assistants working in this repository.

Project Overview

mcp2skill is a Go CLI tool that converts MCP (Model Context Protocol) servers into agent skills. It generates skill packages with SKILL.md documentation from MCP server metadata.

Build, Lint, and Test Commands

# Build
go build ./cmd/mcp2skill                              # Standard build
CGO_ENABLED=0 go build -ldflags="-s -w" ./cmd/mcp2skill  # Static binary for distribution

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run a single test file
go test -v ./internal/config

# Run a single test function
go test -v -run TestFunctionName ./internal/config

# Run tests in specific package with timeout
go test -timeout 30s ./internal/mcp

# Lint (if golangci-lint is installed)
golangci-lint run ./...
golangci-lint run --new-from-rev HEAD~1  # Lint only changes

Code Style Guidelines

Formatting

• Use gofmt (or go fmt) to format code before committing
• Run go vet to catch common mistakes
• Configure editor to format on save with gofmt

Imports

• Use standard Go import organization with go fmt/goimports
• Group imports: standard library first, then third-party, then internal
• Use dot imports sparingly (only in test files when helpful)

Types and Interfaces

• Use struct types for data containers with JSON tags for config files
• Define interfaces for external dependencies (e.g., MCP client) to enable testing
• Prefer concrete types over interfaces unless mocking is needed
• Use type aliases for domain-specific strings (e.g., type TransportType string)

Naming Conventions

• Packages: lowercase, short, descriptive (e.g., config, mcp, cliapp)
• Exported identifiers: PascalCase (e.g., LoadEffective, ServerConfig)
• Unexported identifiers: camelCase (e.g., loadEffective, serverCfg)
• Variables: concise but descriptive; avoid single letters except loop indices
• Constants: SNAKE_CASE for grouped constants, PascalCase for exported enums
• Acronyms: Use consistent casing (e.g., ServeMux, not ServeMIX or ServeMuxID)