HK-hub/AgentSkills / agent-native-design
agent-native-design
VerifiedUse 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.6 KB |
| agents/openai.yaml | config | 1.1 KB |
| references/checklists.md | markdown | 3.6 KB |
| references/citations.md | markdown | 3.7 KB |
| references/design-patterns.md | markdown | 12.4 KB |
| references/examples.md | markdown | 8.1 KB |
| references/hybrid-mcp-cli.md | markdown | 3.9 KB |
| references/rubric.md | markdown | 3.5 KB |
| references/testing.md | markdown | 11.9 KB |
| scripts/validate-metadata.sh | script | 2.7 KB |
references/citations.md
View on GitHub# 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* — https://clig.dev/. The pre-agent baseline for human-first CLI design. This skill extends it; it does not replace it.
- `sysexits.h` — https://manpages.ubuntu.com/manpages/noble/man3/sysexits.h.3head.html. The BSD exit-code vocabulary that `design-patterns.md#exit-code-model` deliberately simplifies away from.
---
## A note on the "agent-native CLI" framing
The term used throughout this skill is one of several competing framings in current writing. *Agent-first CLI* (Propel, Keyboards Down) is more common; *CLI for humans and machines* (openstatus, Linearis) is the most descriptive. "Native" is chosen here to emphasize that agent support is a first-class design goal, not a retrofit on top of a human-only CLI.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |