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/rubric.md
View on GitHub# Rubric
14 criteria, scored 0–2 each. Every criterion is tagged with the principle it backs, so scoring the rubric is the same act as auditing the seven principles. Use this when producing the score component of a CLI review.
| Criterion | Principle | 0 — Fail | 1 — Partial | 2 — Pass |
|-----------|-----------|----------|-------------|----------|
| **Three-audience support** | P0 | Designed for only one audience (human-only, or agent-only) | Serves two audiences well; the third is an afterthought or broken | Deliberately designed for human + agent + system with documented trade-offs |
| **Stdout contract** | P1 | Prose or mixed output | JSON sometimes, not always | Always parseable JSON with stable envelope when stdout is not a TTY (agent context); human-readable by default only under TTY or explicit `--format table` |
| **Stderr separation** | P1 | Diagnostics mixed into stdout | Some separation | Diagnostics always on stderr |
| **Exit code semantics** | P1/P2 | All errors map to same code | Some codes defined | Documented, stable, distinct codes per failure class |
| **Self-description (help)** | P3 | No `--help` or single flat page | Layered help exists but incomplete | Full progressive help: top → resource → action → schema |
| **Schema introspection** | P6 | Not available | Partial or undocumented | `tool schema <resource.action>` returns full typed schema |
| **Dry-run** | P3/P4 | Not available | Available for some commands | Available for all mutating commands |
| **Idempotent retries** | P1 | Mutating commands have no idempotency story; retries create duplicates | `--idempotency-key` exists on some commands, or retry semantics are inconsistent | Every mutating command accepts `--idempotency-key`; retried calls return the original result; the `retryable` flag in the error envelope is meaningful and correct |
| **Non-interactive operation** | P0 | CLI prompts on confirmation or password input regardless of TTY state; no `--yes`/`--force` flags | Some commands support `--yes` but TTY detection is incomplete or pagers still block | CLI never prompts when stdin is not a TTY; `--yes` / `--no-input` supported on every confirmation; pagers disabled when stdout is not a TTY; structured `confirmation_required` error returned instead of blocking |
| **Safety tiers** | P4 | Destructive ops at same level as reads | Some warning on destructive ops | Read/write/destructive clearly tiered; destructive hidden from skills |
| **Boundary validation** | P5 | Validation scattered across internal functions, or missing | Boundary validation exists but internal code still re-validates or accepts raw input | All input validated once at the CLI entry point; internal code operates on typed, trusted structures; validators are centralized and tested for pass and reject cases |
| **Auth delegation** | P7 | Agent manages token lifecycle, runs login or token-retrieval subcommands | Token via env var but refreshed by the agent | Human/system manages token acquisition and refresh; agent receives a pre-fetched credential and never invokes the auth retrieval path |
| **Error recoverability** | P1 | No error fields | `code` + `message` only | `code` + `message` + `retryable` + context fields |
| **Trust boundary** | P2 | CLI args used for auth/config | Mixed | Env vars / config set by human; agent supplies only runtime params |
**Scoring guide (max 28):**
- 26–28: Agent-native
- 17–25: Partially agent-native — specific gaps, actionable fixes
- 0–16: Not yet agent-native — structural redesign needed
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 |