dirien/yet-another-agent-harness / .claude/skills/agent-ready-go
agent-ready-go
VerifiedPrepares Go applications to work effectively with AI coding agents. Use when setting up a new Go project or retrofitting an existing one to ensure: structured JSON logging (slog/Zap/ZeroLog/Logrus), machine-readable command output, thorough golangci-lint configuration, non-interactive CLI design with --yes flags, structured error handling with meaningful exit codes, proper context.Context propagation, graceful shutdown, health check endpoints, and a standardized Makefile. Triggers when a user asks to make their Go app "agent-ready," "AI-friendly," wants to improve agent tooling/observability in a Go project, or needs to audit an existing Go project against agent-readiness best practices.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.3 KB |
| assets/Makefile | other | 2.5 KB |
| references/config.md | markdown | 4.0 KB |
| references/error-handling.md | markdown | 5.6 KB |
| references/logging.md | markdown | 7.1 KB |
| references/non-interactive.md | markdown | 4.8 KB |
| references/services.md | markdown | 5.8 KB |
| references/testing.md | markdown | 6.5 KB |
references/non-interactive.md
View on GitHub<!-- Copyright 2025-2026 Richard Shade. Licensed under Apache-2.0. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
# Non-Interactive Design for Agent-Ready Go
Agents execute commands programmatically. Interactive prompts that block waiting
for user input will deadlock an agent. The goal is not to eliminate all
interactivity — it is to ensure every blocking prompt has a machine-usable
bypass.
## The --yes Flag Pattern
Any command that asks for confirmation must support `--yes` / `-y`:
```go
var yes bool
cmd.Flags().BoolVarP(&yes, "yes", "y", false, "skip confirmation prompts")
func runDelete(cmd *cobra.Command, args []string) error {
if !yes {
confirmed, err := promptConfirm(fmt.Sprintf("Delete %d records?", count))
if err != nil {
return fmt.Errorf("prompt failed: %w", err)
}
if !confirmed {
return nil
}
}
return store.DeleteAll(cmd.Context())
}
```
Agents invoke: `myapp delete --yes`
## Environment Variable Overrides
For flags agents always want set, support env var fallbacks so they can be
configured once in the environment:
```go
// Accept both flag and env var (flag wins if both set)
apiKey := os.Getenv("MYAPP_API_KEY")
cmd.Flags().StringVar(&apiKey, "api-key", apiKey, "API key (or MYAPP_API_KEY)")
```
Standard env var conventions:
- Prefix with app name: `MYAPP_`
- All caps with underscores: `MYAPP_LOG_LEVEL`, `MYAPP_DRY_RUN`
- Booleans: `MYAPP_YES=1` or `MYAPP_YES=true`
## Avoiding Pure TUI Libraries
Some TUI libraries (bubbletea interactive menus, survey, promptui) render
full-screen UIs that agents cannot navigate.
**Use instead:**
- `--format json|text|csv` flag for format selection
- Positional arguments for required inputs
- Config files for complex multi-field inputs
- `--yes` for confirmations
- `--dry-run` to preview without executing
If you must include a TUI for human users, always provide a non-TUI path:
```go
// TUI path for humans
if term.IsTerminal(int(os.Stdin.Fd())) && !yes {
return runInteractiveWizard()
}
// Non-TUI path for agents
return runWithFlags(flags)
```
## Dry Run Support
Agents benefit from being able to preview operations without side effects:
```go
var dryRun bool
cmd.Flags().BoolVar(&dryRun, "dry-run", false, "preview changes without applying")
if dryRun {
fmt.Fprintf(os.Stderr, "[dry-run] would delete %d records\n", count)
return nil
}
// proceed
```
## stdin Detection
Never block reading from stdin unless it is explicitly piped:
```go
stat, _ := os.Stdin.Stat()
if (stat.Mode() & os.ModeCharDevice) != 0 {
// stdin is a terminal — do not block
return fmt.Errorf("no input provided; pipe data or use --file flag")
}
data, _ := io.ReadAll(os.Stdin)
```
## CI/CD Environment Detection
CI environments set well-known environment variables. Use them to auto-enable
non-interactive mode so agents and pipelines never encounter blocking prompts:
```go
func isCI() bool {
return os.Getenv("CI") != "" ||
os.Getenv("GITHUB_ACTIONS") != "" ||
os.Getenv("GITLAB_CI") != "" ||
os.Getenv("JENKINS_URL") != ""
}
// In command flags:
var yes bool
cmd.Flags().BoolVarP(&yes, "yes", "y", isCI(), "skip confirmation prompts")
```
## NO\_COLOR and --no-color
Respect the `NO_COLOR` standard (<https://no-color.org/>) and the `dumb` terminal
type. Agents and log aggregators do not render ANSI escape codes — they appear
as noise in structured output:
```go
func colorEnabled() bool {
if os.Getenv("NO_COLOR") != "" || os.Getenv("TERM") == "dumb" {
return false
}
return term.IsTerminal(int(os.Stdout.Fd()))
}
```
## --quiet Flag
Suppress informational progress messages when running in scripts or pipelines.
Always write progress to stderr so it can be redirected independently:
```go
var quiet bool
cmd.Flags().BoolVarP(&quiet, "quiet", "q", false, "suppress informational output")
if !quiet {
fmt.Fprintln(os.Stderr, "Processing 42 records...")
}
```
## --timeout Flag
Long-running commands must support a timeout so agents can bound execution time
and fail fast rather than waiting indefinitely:
```go
var timeout time.Duration
cmd.Flags().DurationVar(&timeout, "timeout", 30*time.Second, "maximum execution time")
ctx, cancel := context.WithTimeout(cmd.Context(), timeout)
defer cancel()
```
## Summary Checklist
- [ ] Destructive commands have `--yes`/`-y`
- [ ] CI environments auto-enable `--yes` (via `CI`/`GITHUB_ACTIONS` env vars)
- [ ] Sensitive config accepts env vars with `APPNAME_` prefix
- [ ] No interactive menus without a `--flag` alternative
- [ ] `--dry-run` on all state-changing commands
- [ ] stdin reads are guarded against blocking on a terminal
- [ ] `NO_COLOR` respected; color codes suppressed in non-TTY output
- [ ] `--quiet`/`-q` suppresses informational stderr
- [ ] Long-running commands support `--timeout`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |