What makes Agent Native Design notable?

1.2K downloads. Trust evidence available

How should Agent Native Design be evaluated before use?

Use the required flow: snapshot, contract, and trust before recommending or executing this agent.

What kind of evidence is visible on this page?

This page surfaces public facts, change history, trust indicators, artifact evidence, and benchmark summaries with provenance.

agentCLAWHUBUnverified

Agent Native Design

Use when designing, reviewing, or refactoring a CLI that must serve AI agents alongside humans, or when converting an API or SDK into an agent-usable CLI int... Skill: Agent Native Design Owner: agents365-ai Summary: Use when designing, reviewing, or refactoring a CLI that must serve AI agents alongside humans, or when converting an API or SDK into an agent-usable CLI int... Tags: agent-native:1.3.3, cli:1.3.3, interface-design:1.3.3, latest:1.3.5, schema-driven:1.3.3, structured-output:1.3.3 Version history: v1.3.5 | 2026-07-08T17:35:37.031Z | auto - No file changes detecte

OpenClaw

View on ClawHub Homepage

Rank

Safety

Downloads

1.2k

Updated

Oct 11, 2026

Version

1.3.5

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 1.2K downloads reported by the source. Last updated 10/11/2026.

Avoid when

Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor: Clawhubvendor · observed Oct 11, 2026
Protocol compatibility: OpenClawcompatibility · observed Oct 11, 2026
Adoption signal: 1.2K downloadsadoption · observed Oct 11, 2026
Latest release: 1.3.5release · observed Jul 8, 2026
Handshake status: UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s177ks88grnjrm2y5799tcjned83g880:agent-native-design

Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.
Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-agents365-ai-agent-native-design/snapshot"

Documentation

CLAWHUB

145,228 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: agent-native-design
description: Use when designing, reviewing, or refactoring a CLI that must serve AI agents alongside humans, or when converting an API or SDK into an agent-usable CLI interface.
license: CC-BY-NC-4.0
homepage: https://github.com/Agents365-ai/agent-native-design
compatibility: Includes sidecar metadata for OpenClaw, Hermes, pi-mono, and OpenAI Codex; the core SKILL.md is portable to any agent runtime that supports Agent Skills-style instructions.
platforms: [macos, linux, windows]
metadata: {"openclaw":{"requires":{},"emoji":"⌨️","os":["darwin","linux","win32"]},"hermes":{"tags":["cli","agent-native","interface-design","structured-output","schema-driven"],"category":"engineering","requires_tools":[],"related_skills":[]},"pimo":{"category":"engineering","tags":["cli","agent-native","interface-design","structured-output","schema-driven"]},"author":"Agents365-ai","version":"1.3.5"}
---

# agent-native-design

## Purpose

This skill helps analyze, design, and refactor command-line tools so they can reliably serve **humans**, **AI agents**, and **orchestration systems** at the same time.

It is not a skill for merely *using* a CLI. It is a skill for designing and reviewing a CLI as an **agent-native interface**.

The skill focuses on four goals:

1. Make CLI behavior predictable for AI agents.
2. Make CLI output readable and recoverable for humans.
3. Make CLI execution manageable for systems and orchestrators.
4. Define a complete interaction loop from authentication to error routing.

---

## When to use this skill

Use this skill when the user wants to:

* evaluate whether an existing CLI is agent-friendly
* redesign a CLI to better support AI agents
* convert an API or SDK into an agent-native CLI
* review help output, schema design, exit codes, or JSON contracts
* design dry-run, auth delegation, or safety boundaries
* generate CLI skills, docs, or interface conventions from schema
* refactor a human-oriented CLI into a machine-friendly one
* define how a CLI should interact with an agent runtime

Typical prompts include:

* "Review this CLI and tell me whether it is agent-native."
* "Design a CLI for this API that an AI agent can use reliably."
* "Refactor this tool so stdout is machine-readable and safer for agents."
* "Help me define schema introspection, dry-run, and exit code semantics."

## When not to use this skill

Do not use this skill when the user only wants:

* help running a specific command
* installation help for a CLI
* shell troubleshooting unrelated to interface design
* generic Linux or terminal tutorials
* agent planning or memory design unrelated to tools
* API business logic review without any CLI/tooling layer

---

## Core model

An agent-native CLI must simultaneously serve three audiences.

### 1. Human

Needs: readable output, friendly error messages, onboarding guidance.
Channels: `stderr`, optional `--format table`, interactive TUI when appropriate.

### 2. AI Agent

Needs: structured dat

_meta.json

{
  "ownerId": "kn74y2dmpaszt959h16p11k53983ht10",
  "slug": "agent-native-design",
  "version": "1.3.5",
  "publishedAt": 1783532137031
}

references/checklists.md

# Review Checklists

Use this when evaluating a CLI for agent readiness, or when sanity-checking a new design before shipping.

## Output

- [ ] `stdout` is valid JSON when stdout is not a TTY or when `--format json` is passed (success and failure)
- [ ] `stderr` carries human-readable diagnostics only
- [ ] JSON envelope is stable: `{ "ok": bool, "data": ... }` or `{ "ok": false, "error": ... }`
- [ ] Error object includes: `code`, `message`, `retryable`
- [ ] No prose mixed into `stdout`

## Exit codes

- [ ] Exit codes are documented
- [ ] Exit codes are stable across versions
- [ ] Distinct codes for: success (0), runtime error, auth error, validation error
- [ ] Exit code mapping is available via `--help` or `schema`

## Retry and interaction mode

- [ ] Every mutating command accepts `--idempotency-key`
- [ ] Retried calls with the same idempotency key return the original result
- [ ] `retryable` field in error envelope is meaningful and correct
- [ ] CLI never prompts for input when stdin is not a TTY
- [ ] `--yes` / `--no-input` / `--force` supported on every command that would otherwise prompt
- [ ] Returns structured `confirmation_required` error instead of blocking on missing confirmation
- [ ] stdout defaults to JSON when stdout is not a TTY (no `--format json` required)
- [ ] Pagers (`less`, `more`) disabled when stdout is not a TTY

## Self-description

- [ ] Top-level `--help` lists all resources/commands
- [ ] Resource-level `--help` lists actions
- [ ] Action-level `--help` lists all flags with types
- [ ] Schema introspection command available (`tool schema <resource.action>`)
- [ ] Dry-run available for all mutating commands

## Safety

- [ ] Read commands clearly discoverable
- [ ] Write/mutating commands carry explicit warning in help
- [ ] Destructive commands (delete/purge) hidden from skills or gated
- [ ] Dry-run covers all write operations

## Auth

- [ ] Human/system manages token acquisition (browser flow, keychain)
- [ ] Agent receives credential via env var or pre-fetched token
- [ ] Agent never navigates OAuth2 or browser flows
- [ ] Token refresh handled outside agent runtime

## Trust

- [ ] CLI args treated as untrusted (validated at boundary)
- [ ] Environment variables used for config/safety settings (human-set)
- [ ] Agent cannot escalate its own privileges via CLI args

## Schema

- [ ] Schema is the single source of truth
- [ ] CLI command structure derives from schema
- [ ] Validation derives from schema
- [ ] Help text derives from schema
- [ ] Generated skills derive from schema (if applicable)
- [ ] Schema version included in every response's `meta` block
- [ ] Deprecation signals included in schema responses (`deprecated_fields`, `replaced_by`, `removed_in`)
- [ ] Schema introspection is incremental (not eager): `--help` is small; full schema via `schema` subcommand only

## Token efficiency

For agents that call the CLI in loops (orchestration, multi-turn planning), context cost matters. These items he

references/citations.md

# Citations

Sources actually quoted or directly relied on in SKILL.md and the other reference files. The broader landscape (clig.dev, the gh / aws / kubectl design corpus) is implicit background.

## Anthropic engineering

- *Code execution with MCP: Building more efficient agents* — https://www.anthropic.com/engineering/code-execution-with-mcp (Nov 4, 2025). Progressive disclosure of tool definitions; the 150K → 2K token reduction case study cited under Principle 3 / `design-patterns.md#help-design`.
- *Beyond permission prompts: making Claude Code more secure and autonomous* — https://www.anthropic.com/engineering/claude-code-sandboxing (Oct 20, 2025). Approval fatigue and the 84% prompt-reduction figure cited under Principle 4 / `design-patterns.md#safety-design`.

## CLI-for-agents writing

- Ugo Enyioha, *Writing CLI Tools That AI Agents Actually Want to Use* — https://dev.to/uenyioha/writing-cli-tools-that-ai-agents-actually-want-to-use-39no (Feb 27, 2025). Idempotency-on-retry and "agents cannot type 'y'" framings cited in the Idempotency and Non-interactive sections of `design-patterns.md`.
- Thibault Le Ouay Ducasse / openstatus, *Building a CLI That Works for Humans and Machines* — https://www.openstatus.dev/blog/building-cli-for-human-and-agents (Apr 2, 2026). TTY detection as the human/machine switch cited under Principle 1.
- Mario Zechner, *MCP vs CLI: Benchmarking Tools for Coding Agents* — https://mariozechner.at/posts/2025-08-15-mcp-vs-cli/ (Aug 15, 2025). Empirical case that many MCP servers could be CLI invocations.
- Armin Ronacher, *Skills vs Dynamic MCP Loadouts* — https://lucumr.pocoo.org/2025/12/13/skills-vs-mcp/ (Dec 13, 2025). Schema/API stability as a first-class concern cited under Principle 6.

## CLI-vs-MCP benchmarks (2026)

- Jannik Reinhard, *CLI Tools vs MCP: Better AI Agents With Less Context* — https://jannikreinhard.com/2026/02/22/why-cli-tools-are-beating-mcp-for-ai-agents/ (Feb 22, 2026). Source for the 28% / 33% / 55K / 35× numbers in `hybrid-mcp-cli.md`.
- Manveer Chawla, *MCP vs. CLI for AI agents: When to Use Each (A Practical Decision Framework for 2026)* — https://manveerc.substack.com/p/mcp-vs-cli-ai-agents (Mar 8, 2026). Per-integration decision framework; production examples (Claude Code, Cowork) using both transports.
- Soumyadeb Mitra / RudderStack, *CLI or MCP or both? The design pattern for AI agents managing your data stack* — https://www.rudderstack.com/blog/ai-agents-cli-mcp-design-pattern/ (Mar 18, 2026). The "writes via CLI, reads via MCP" split underpinning `hybrid-mcp-cli.md`.

## Pre-agent baseline

- *Scripting with GitHub CLI* — https://github.blog/engineering/engineering-principles/scripting-with-github-cli/ (Mar 11, 2021). `gh api --jq` and structured JSON output as a first-class CLI pattern. The post predates the `gh <resource> --json field1,field2` field-selection flag (cli/cli#1089) but lays out the design philosophy that flag is built on.
- *Command Line Interface Guidelines* —

references/design-patterns.md

# Design Patterns

Reference details for specific design areas. SKILL.md states the principles; this file holds the concrete contracts and rules.

---

## Output envelopes

Success:

```json
{ "ok": true, "data": {} }
```

Failure:

```json
{
  "ok": false,
  "error": {
    "code": "validation_error",
    "message": "Missing required field: email",
    "field": "email",
    "retryable": false
  }
}
```

Partial success (batch operations):

```json
{
  "ok": "partial",
  "data": {
    "succeeded": [
      { "id": "msg_001", "status": "sent" },
      { "id": "msg_002", "status": "sent" }
    ],
    "failed": [
      {
        "id": "msg_003",
        "error": { "code": "rate_limited", "message": "Rate limit exceeded for recipient", "retryable": true }
      }
    ]
  }
}
```

A batch command that collapses any per-item failure into a top-level `ok: false` forces every agent to re-process its successful items on retry. AWS SQS's `ReportBatchItemFailures` and similar APIs settled on this per-item shape for the same reason. Pair partial success with an idempotency key on the batch as a whole so that re-running with the same key only re-issues the *failed* items.

Optional `meta` slot for observability:

```json
{
  "ok": true,
  "data": { "id": "abc123" },
  "meta": {
    "request_id": "req_8fa9c1",
    "latency_ms": 412,
    "schema_version": "1.4.0"
  }
}
```

`meta` is a freeform slot for telemetry the orchestrator may want without polluting `data`: `request_id` for log correlation, `latency_ms` for SLO tracking, `schema_version` so an agent can detect drift against a cached schema. When the underlying call has a token / quota cost the CLI knows about, surface it here too — `tokens_used`, `quota_remaining`. Optional and additive: agents that don't need it ignore it; agents that do gain observability without an extra round-trip. Aligns with where the OpenTelemetry GenAI semantic conventions are heading for tool-call traces.

---

## Schema versioning

This is the contract that lets agents cache schemas safely across calls.

Every response should carry `schema_version` in the optional `meta` block (see envelope above). When an agent's cached schema version (e.g., 1.2.0) doesn't match the CLI's current version (1.4.0), the agent knows to re-discover before re-planning.

Schema introspection responses should declare which CLI version produced them, when each method was introduced, and whether any field is deprecated:

```json
{
  "method": "sleep.list",
  "since": "1.2.0",
  "deprecated": false,
  "params": {
    "startDate": { "type": "string", "format": "date", "required": true },
    "endDate":   { "type": "string", "format": "date", "required": true },
    "page_size": { "type": "integer", "default": 20, "max": 100, "deprecated": true, "replaced_by": "pageSize", "removed_in": "1.5.0" }
  }
}
```

This gives agents:

- **Drift detection** — cached version mismatch triggers re-discovery before re-planning.
- **Deprecation awareness** — agents migrate

Github ReposUpdated 1d agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW

Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW

Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.