agentcli-go_skill

Overview

This skill is a concise reference for the agentcli-go framework, a collection of reusable Go helpers and scaffolding for building CLI tools. It describes the library surface, common workflows (scaffold, add command, doctor), and the recommended project layout and patterns. Use it to speed up CLI development, enforce consistent structure, and avoid reimplementing common plumbing.

How this skill works

The skill documents exported helpers across modules: logging, argument parsing, filesystem helpers, command execution, lifecycle hooks, error/exit handling, scaffolding, a cobrax/Cobra integration, and a small config loader. It explains programmatic scaffolding (new project, add command), how to wire root commands with cobrax, and how configx composes defaults, files, environment, and flags. Practical examples show generated files and Taskfile tasks for CI and validation.

When to use it

• When scaffolding a new Go CLI project with consistent layout and tooling.
• When adding a new command or preset to an existing agentcli-based CLI.
• When integrating standardized logging, config loading, and lifecycle hooks.
• When debugging framework behavior or validating project health with doctor.
• When you want minimal, reusable CLI primitives without business logic.

Best practices

• Keep consumer code focused on business logic; import only what you need from agentcli.
• Use cobrax.RootSpec and CommandSpec to register commands and persistent flags.
• Prefer configx.Load with NormalizeEnv to combine defaults, files, env, and flags.
• Follow the golden project layout for predictable CI, tests, and packaging.
• Use ScaffoldNew and ScaffoldAddCommand to ensure consistent command templates.
• Respect the library rules: flat package design and minimal third-party deps.

Example use cases

• Generate a new CLI skeleton: agentcli new --name my-tool --module github.com/me/my-tool.
• Add a file-sync command preset: agentcli add command --name sync --preset file-sync.
• Implement app lifecycle hooks and run preflight/postflight checks via RunLifecycle.
• Run agentcli doctor to produce a JSON DoctorReport for CI health checks.
• Load configuration with configx.Decode into a typed config struct for runtime.