Configure Agents CLI capabilities and operating mode

Learning objective

Configure Agents CLI skills and plugins, then choose agent mode or human mode for a development step. This lesson focuses on how capabilities reach the coding environment and who drives the CLI, not on building an ADK agent.

Core idea

Keep two decisions separate:

1. Capability packaging: A skill supplies task-specific instructions and resources. An Agent Plugin can package skills and optional Model Context Protocol (MCP) servers for a compatible client.
2. Control mode: In agent mode, a coding agent interprets your intent, loads the relevant skills, and invokes Agents CLI. In human mode, you invoke the same CLI commands yourself.

The modes change who chooses and sequences commands, not the runtime. Google describes Agents CLI as one CLI and skills package that works either through a coding agent or directly from a terminal in the Agents CLI getting-started guide.

How it works

Configure the Agents CLI skills

An Agent Skill is a directory with a required SKILL.md file and optional scripts, references, and assets. A coding agent discovers a skill from its name and description, then loads the instructions when the task matches, as defined by the Agent Skills overview.

Agents CLI bundles seven lifecycle skills. setup installs the CLI and these skills into detected coding agents at global scope by default. Use --workspace for project scope, --agent to select clients, and --dry-run to preview. This sequence previews and installs the bundle for all supported clients in the current workspace:

agents-cli setup --workspace --agent all --dry-run
agents-cli setup --workspace --agent all

Refresh a workspace-scoped installation with:

agents-cli update --workspace

The Agents CLI reference documents these options. Choose global scope for a personal cross-project toolchain and workspace scope for repository-specific capabilities. To install only the skills, use:

npx skills add google/agents-cli

Understand the plugin boundary

A skill is one loadable unit of expertise. An Agent Plugin is a portable package: it has a root plugin.json manifest and can contain multiple skills in skills/ plus MCP server definitions in mcp.json. The Agent Plugins specification standardizes the package layout, but leaves installation, permissions, and user experience to the client.

The official google/agents-cli repository has a plugin.json manifest and a skills/ directory, so compatible clients can consume it as a plugin. However, agents-cli setup installs the skill bundle; it does not define a universal agents-cli plugin install command. For the plugin route, use the client’s documented plugin manager and review every component and permission.

Do not confuse this with an Agents CLI extension. A plugin packages client capabilities; an extension adds or overrides agents-cli commands. Extensions have their own scope and trust model, as described in Using Extensions.

Choose agent mode or human mode

Use agent mode for intent-heavy work such as designing from requirements, editing code, generating evaluation cases, or iterating on failures. Skills give the coding agent lifecycle guidance; the human still sets constraints and approves consequential actions.

Use human mode when the command is known or a script, CI job, runbook, or change-control process requires an explicit invocation. It gives deterministic control over which command runs, not over model output.

Agent mode and human mode are operating patterns, not mutually exclusive CLI settings. There is no global --mode agent or --mode human flag, and --interactive only enables prompts for a command. You can switch modes at any lifecycle step. Google’s announcement calls this distinction Human Intent + Agent Execution.

Key distinctions and trade-offs

Agent mode adds a separate authentication boundary: the coding agent has its own credentials, while the agent under development needs model credentials and may need Google Cloud deployment credentials. Human mode removes only the coding-agent layer. See the Agents CLI authentication model.

Architecture / decision scenario

A platform team maintains an incident-triage agent. Developers use different coding agents, but this repository needs the same guidance. The team previews and installs the lifecycle skills at workspace scope for all supported clients; other repositories keep their own approved toolchains.

During feature development, a developer uses agent mode: “Add a runbook-search tool, create evaluation cases for missing citations, and run the evaluation.” The coding agent loads the relevant skills, edits the project, and invokes the required CLI commands. The developer reviews the diff and results.

In CI, the team uses human mode through explicit pipeline commands such as agents-cli eval run. The pipeline does not need a coding agent to reinterpret the task. Before production deployment, an operator runs agents-cli deploy --dry-run, reviews the planned operation, and then follows the organization’s approval process.

If the team later distributes the skills with an approved MCP server, it adopts an Agent Plugin and uses each client’s plugin mechanism. It avoids installing the same skills again through setup.

Common exam traps

• Treating Agents CLI as a coding agent. It is a CLI and skill package used by a coding agent or directly by a human.
• Assuming the modes use different command implementations or runtimes.
• Looking for a global mode flag. The mode describes who drives the workflow.
• Calling a skill a tool. A skill supplies instructions and resources; tool access comes from the coding environment or an MCP server.
• Assuming agents-cli setup installs an Agent Plugin. It installs the skill bundle; plugin installation is client-managed.
• Confusing an Agent Plugin, an Agents CLI extension, and an ADK runtime plugin. They package client capabilities, modify CLI commands, and intercept ADK runtime events, respectively.
• Assuming human mode removes authentication or IAM requirements.

What to remember

• Separate capability packaging from control mode.
• Use workspace-scoped skills for repository-specific consistency and global skills for a personal cross-project default.
• Treat a skill as focused expertise and an Agent Plugin as a portable bundle of skills and optional MCP servers.
• Use agent mode for intent-heavy iteration and human mode for explicit, repeatable commands; mix them across the lifecycle.
• Mode choice does not change runtime permissions, credentials, or the deployed agent architecture.

Knowledge check

References

• Agents CLI, Getting Started
• Agents CLI, CLI Reference
• Google Developers Blog, Agents CLI in Agent Platform: create to production in one CLI
• Agent Skills, Agent Skills Overview
• Agent Plugins, Agent Plugins Specification
• Google, google/agents-cli plugin manifest
• Agents CLI, Using Extensions
• Agents CLI, Authentication