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/checklists.md
View on GitHub# 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 help CLIs realize the per-call token advantage over eager-loaded MCP servers (see `hybrid-mcp-cli.md` for the benchmark data this is based on).
- [ ] Top-level `--help` response is under 500 tokens
- [ ] Full schema is not dumped in top-level `--help`; accessed via `schema <resource.action>` instead
- [ ] Field selection supported on list responses (`--json field1,field2,...` or similar)
- [ ] Default list responses are compact (3–5 fields); full detail via `--full` flag
- [ ] Requests that would normally require two CLI calls are collapsed (e.g., `count` + `list` → return count in the envelope)
- [ ] Schema versioning allows agents to cache and avoid re-discovery on every invocation
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 |