agent-native-design
agent
Warn
Health Warn
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 9 GitHub stars
Code Pass
- Code scan — Scanned 3 files during light audit, no dangerous patterns found
Permissions Pass
- Permissions — No dangerous permissions requested
Purpose
This tool is a CLI design and review skill that evaluates and guides the creation of command-line interfaces optimized for both humans and AI agents. It helps developers refactor or build CLIs that feature stable stdout contracts, exit code semantics, and agent-safe delegated authentication.
Security Assessment
Overall risk: Low. This tool acts primarily as a knowledge base and design guide rather than an active script runner. The automated code scan reviewed 3 files and found no dangerous patterns, hardcoded secrets, or network requests. Furthermore, it does not request any dangerous permissions or attempt to access sensitive data.
Quality Assessment
The project is actively maintained, with its most recent push occurring today. It uses the permissive and standard MIT license, and the repository includes a clear description. The primary drawback is low community visibility. Currently sitting at only 9 GitHub stars, the tool has not yet been broadly tested or validated by a large user base. However, given its nature as a lightweight design framework rather than critical infrastructure, this lack of widespread adoption poses minimal risk.
Verdict
Safe to use — it is a lightweight, actively maintained, and secure design reference tool, though its low community engagement means it lacks widespread peer validation.
This tool is a CLI design and review skill that evaluates and guides the creation of command-line interfaces optimized for both humans and AI agents. It helps developers refactor or build CLIs that feature stable stdout contracts, exit code semantics, and agent-safe delegated authentication.
Security Assessment
Overall risk: Low. This tool acts primarily as a knowledge base and design guide rather than an active script runner. The automated code scan reviewed 3 files and found no dangerous patterns, hardcoded secrets, or network requests. Furthermore, it does not request any dangerous permissions or attempt to access sensitive data.
Quality Assessment
The project is actively maintained, with its most recent push occurring today. It uses the permissive and standard MIT license, and the repository includes a clear description. The primary drawback is low community visibility. Currently sitting at only 9 GitHub stars, the tool has not yet been broadly tested or validated by a large user base. However, given its nature as a lightweight design framework rather than critical infrastructure, this lack of widespread adoption poses minimal risk.
Verdict
Safe to use — it is a lightweight, actively maintained, and secure design reference tool, though its low community engagement means it lacks widespread peer validation.
Agent-Native CLI design & review skill — design CLIs that serve humans, AI agents, and orchestration systems simultaneously
README.md
agent-native-design — Agent-Native CLI Design & Review Skill
What it does
- Evaluates whether an existing CLI is reliably usable by AI agents
- Designs CLI interfaces that serve humans, agents, and orchestration systems simultaneously
- Converts REST APIs and SDKs into agent-native CLI command trees
- Reviews stdout contracts, exit code semantics, and error envelope design
- Designs schema-driven self-description, dry-run previews, and schema introspection
- Defines safety tiers (open / warned / hidden) for graduated command visibility
- Designs delegated authentication so agents never own the auth lifecycle
- Produces prioritized refactor plans with concrete interface examples
Multi-Platform Support
The core SKILL.md is portable, and this repository includes metadata for the platforms listed below:
| Platform | Status | Details |
|---|---|---|
| Claude Code | ✅ Full support | Native SKILL.md format |
| OpenClaw / ClawHub | ✅ Full support | metadata.openclaw namespace |
| Hermes Agent | ✅ Full support | metadata.hermes namespace, category: engineering |
| pi-mono | ✅ Full support | metadata.pimo namespace |
| OpenAI Codex | ✅ Full support | agents/openai.yaml sidecar |
| SkillsMP | ✅ Indexed | GitHub topics configured |
Comparison: with vs. without this skill
| Capability | Native agent | This skill |
|---|---|---|
| Evaluate whether a CLI is agent-native | No | Yes — structured diagnosis across 7 principles |
| Design stdout JSON contract | Inconsistent | Always — stable envelope with ok, data, error |
| Define exit code semantics | Ad hoc | Yes — documented, deterministic per failure class |
Design layered --help and schema introspection |
No | Yes — full self-description pattern |
| Design dry-run previews | Rarely | Always — request shape preview without execution |
| Define safety tiers for commands | No | Yes — open / warned / hidden tiers |
| Design delegated authentication | No | Yes — human manages auth lifecycle; agent uses token |
| Separate trust levels for env vs. CLI args | No | Yes — directional trust model |
| Produce prioritized refactor plan | Rarely | Always — P0 / P1 / P2 with examples |
| Score CLI across 14-criterion rubric | No | Yes — 0–2 per criterion with verdict |
When to use
- Evaluating whether an existing CLI is usable by an AI agent
- Designing a new CLI interface for an API or SDK
- Refactoring a human-first CLI to be machine-readable
- Reviewing stdout, stderr, and exit code contract design
- Defining dry-run, schema introspection, and self-description layers
- Designing auth delegation and trust boundaries for agent safety
- Producing a SKILL.md or skill docs from a CLI schema
Skill Installation
Quick install — ask any agent
The simplest install is to ask any code-capable agent (Claude Code, Codex, Cursor, Aider, Gemini CLI, …) to clone the repo into your platform's skills directory. Just hand it the URL and the destination path:
Clone https://github.com/Agents365-ai/agent-native-design into ~/.claude/skills/agent-native-design for me.
Substitute the destination for your platform — see the Installation paths summary table at the end of this section. Because the prompt names the exact path, this works for any agent regardless of whether it has built-in knowledge of skills conventions. For environments without an agent handy (CI, fresh machines, headless scripts), use the per-platform git clone commands in the sub-sections that follow.
Claude Code
# Global install (available in all projects)
git clone https://github.com/Agents365-ai/agent-native-design.git ~/.claude/skills/agent-native-design
# Project-level install
git clone https://github.com/Agents365-ai/agent-native-design.git .claude/skills/agent-native-design
OpenClaw / ClawHub
# Via ClawHub
clawhub install agent-native-design
# Manual install
git clone https://github.com/Agents365-ai/agent-native-design.git ~/.openclaw/skills/agent-native-design
# Project-level install
git clone https://github.com/Agents365-ai/agent-native-design.git skills/agent-native-design
Hermes Agent
git clone https://github.com/Agents365-ai/agent-native-design.git ~/.hermes/skills/engineering/agent-native-design
Or add to ~/.hermes/config.yaml:
skills:
external_dirs:
- ~/myskills/agent-native-design
pi-mono
git clone https://github.com/Agents365-ai/agent-native-design.git ~/.pimo/skills/agent-native-design
OpenAI Codex
# User-level install (default CODEX_HOME)
git clone https://github.com/Agents365-ai/agent-native-design.git ~/.codex/skills/agent-native-design
# Project-level install
git clone https://github.com/Agents365-ai/agent-native-design.git .codex/skills/agent-native-design
SkillsMP
skills install agent-native-design
Installation paths summary
| Platform | Global path | Project path |
|---|---|---|
| Claude Code | ~/.claude/skills/agent-native-design/ |
.claude/skills/agent-native-design/ |
| OpenClaw | ~/.openclaw/skills/agent-native-design/ |
skills/agent-native-design/ |
| Hermes Agent | ~/.hermes/skills/engineering/agent-native-design/ |
Via external_dirs config |
| pi-mono | ~/.pimo/skills/agent-native-design/ |
— |
| OpenAI Codex | ~/.codex/skills/agent-native-design/ |
.codex/skills/agent-native-design/ |
License
MIT
Changelog
v1.2.0 — April 26, 2026
2026 Research Update — Aligned with latest agent-CLI design patterns and benchmarks.
New Content:
- Added hybrid MCP-CLI decision framework with decision matrix (3 scenarios for each pattern)
- Strengthened Principle 6 with schema versioning in response envelopes and deprecation signals
- Added Example 8: Schema versioning with drift detection for agent caching scenarios
- Quantified anti-pattern: eager schema dumps (55K tokens per 10 invocations)
- Added token efficiency checklist (6 items for evaluating CLI context cost)
Research Alignment:
- Cite 2026 benchmarks: CLI achieves 28% higher task completion, 33% token efficiency vs. MCP-only
- Added 4 new references: Reinhardt, Chugh, RudderStack on hybrid patterns (2026)
- Validated all 7 principles through April 2026 production deployments
Recommendation: This version reflects the consensus that large production agents (Claude Code, Cursor, Gemini CLI) use both CLI (for local/scriptable tasks) and MCP (for multi-tenant SaaS). Skill remains fundamentally sound; no principles required rewriting.
v1.1.0 — Early 2026
Initial version with seven principles, 14-criterion rubric, and examples.
Support
If this skill helps your work, consider supporting the author:
WeChat Pay |
Alipay |
Buy Me a Coffee |
Give a Reward |
Author
Agents365-ai
- Bilibili: https://space.bilibili.com/441831884
- GitHub: https://github.com/Agents365-ai
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found