Agent usage

akua is designed agent-first. This doc covers how agents discover akua's capabilities, what ships out of the box, and why the architecture is the way it is.

The short version

• akua auto-detects agent sessions from standard env vars (AGENT=…, CLAUDECODE=1, etc.) and silently enables JSON output, structured errors, no-interactive, no-color. See cli-contract.md §1.5.
• The akua CLI surface follows a strict contract (JSON-first, typed exit codes, idempotent writes, plan mode, time-bounded) — the CLI is the agent API. See cli-contract.md.
• Agent-ready workflows ship as skills in skills/ following the open Agent Skills Specification. Install them into Claude Code, Cursor, Codex, Gemini CLI, Goose, Amp, OpenCode, or any of the 35+ supported agents.
• No MCP server. Shell + skills is structurally more efficient than MCP for operational tools (token cost, composability).

Why no MCP server?

MCP tool definitions consume 30k–90k tokens of agent context per connection before any reasoning starts. For a CLI with 20 verbs and 100+ subcommands, that's catastrophic.

The alternative the ecosystem is converging on — pioneered by Cloudflare, validated by Google Workspace CLI — is:

1. CLI surface with JSON-first output (structured data for the agent; legible for humans).
2. Skills in the repository (natural-language task descriptions the agent loads on-demand; ~100 tokens of metadata at startup, full body only when needed).
3. Auto-detection of agent context so the agent never has to remember --json or similar agent-specific flags.

This combination matches how agents already work. Agents compose through shell pipes; they read markdown. They don't need a separate protocol for each CLI.

How akua auto-detects agent context

At process start, akua checks environment variables in this order:

If any matches, akua silently enables --json, --log=json, --no-color, --no-progress, --no-interactive. Explicit flags always win (user can force text output with --no-json or --format=text).

No stderr announcement. No prelude on stdout. Detection is observable via akua whoami --json (reveals the agent_context field) or at --log-level=debug. Otherwise invisible.

How to install akua skills into your agent

Claude Code

Skills under skills/ in any project Claude Code opens are discovered automatically. No installation needed. Alternatively for global access:

cp -r path/to/akua/skills/* ~/.claude/skills/

OpenAI Codex

Install via the Codex skills manager:

codex skills install github:cnap-tech/akua/skills

Cursor

Add skills/ to Cursor's skill paths in .cursor/config.json:

{ "skills": { "paths": ["./skills"] } }

Gemini CLI

Install as a Gemini CLI extension:

gemini extensions install @akua/skills

Goose, Amp, OpenCode, Cline, Roo Code, Amp, Command Code, Kiro, Factory, and 25+ others

All support the open Agent Skills Specification. Any of:

• Symlink skills/ into the agent's expected location
• Use npx skills install github:cnap-tech/akua/skills
• Follow each agent's skill-installation instructions (linked from agentskills.io/overview)

Universal: npx skills

The Vercel Labs skills manager works across all Agent Skills compatible agents:

npx skills install github:cnap-tech/akua/skills
npx skills list
npx skills remove akua-*

Shipped skills

Eight initial skills covering the most common akua workflows. See skills/ for details.

Writing your own skill

Follow the spec:

skills/my-skill/
├── SKILL.md              # required
├── scripts/              # optional — helper scripts
├── references/           # optional — long-form docs
└── assets/               # optional — templates, diagrams

SKILL.md minimum:

---
name: my-skill
description: What this does and when to use it.
---

# My skill

Step-by-step instructions...

Validation: npx skills-ref validate ./skills/my-skill

Good descriptions include trigger keywords agents would recognize. Agents load metadata for all skills (~100 tokens each) at startup; they load the full body only when they decide a skill applies.

See the shipped skills for canonical examples.

Running agents against akua — example loop

agent receives user intent:
  "add a Redis to my checkout service"

agent loads skills metadata:
  reads ~100 tokens per skill, selects new-package + inspect-package

agent loads new-package SKILL.md fully:
  now has full procedure for scaffolding + adding sources

agent executes:
  $ akua add chart oci://ghcr.io/bitnami/charts/redis --version 21.0.0
  $ edit package.k to wire redis values to existing schema
  $ akua lint
  $ akua render --inputs inputs.yaml --out ./rendered

agent verifies:
  $ akua diff previous:v1.2 ./rendered --json
  (structural diff shows: new source redis, new schema field redis.replicas)

agent commits + opens PR:
  $ git commit -am "feat: add redis to checkout"
  $ gh pr create

CI runs:
  akua lint + diff-gate + policy check → attached to PR as comments

human reviews + approves + merges

deploy repo auto-updates; ArgoCD syncs

The whole loop: ~300 tokens of agent context for metadata, ~1000-2000 for the activated skill, plus primary task context. No MCP, no separate protocol, no magic — shell + git + markdown.

Related reading

• cli-contract.md — the CLI invariants agents rely on
• cli.md — full verb reference
• sdk.md — programmatic access if you prefer SDK over CLI
• agentskills.io — the skill-format standard
• Cloudflare: code execution > MCP tools for agent ops — the research that shifted the ecosystem