[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7154DW3RP5ET1R3ECXM7KJ7":3,"skill-same:01M7154DW3RP5ET1R3ECXM7KJ7":71},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":51,"commitSha":52,"skillDirectory":53,"forksCount":14,"repositoryHtmlUrl":54,"repositoryHomepageUrl":6,"ownerHtmlUrl":55,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":56,"install":57,"resources":70},"01M7154DW3RP5ET1R3ECXM7KJ7","ai-native-cli",null,"Design spec with 98 rules for building CLI tools that AI agents can safely use. Covers structured JSON output, error handling, input contracts, safety guardrails, exit codes, and agent self-description.","sapsapshen\u002Fai-memory-router","sapsapshen","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F20347959?v=4","01M6XDQEF1DP50DKF37H81J3J5","shenmian","01M6XDQEJPE41Y3DT2763X8ZJN",0,"MIT","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fcursor\u002Fai-native-cli\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"cli","native","ai native","ai native cli","2026","design","for","design spec","error","input","self","contracts","exit","agent-cli","Safety","Tools","Guardrails","JSON Output","ai agents","safe","2026-11-10 10:12:30",false,"---\nname: ai-native-cli\ndescription: \"Design spec with 98 rules for building CLI tools that AI agents can safely use. Covers structured JSON output, error handling, input contracts, safety guardrails, exit codes, and agent self-description.\"\nrisk: safe\nsource: https:\u002F\u002Fgithub.com\u002FChaosRealmsAI\u002Fagent-cli-spec\ndate_added: \"2026-03-15\"\n---\n\n# Agent-Friendly CLI Spec v0.1\n\nWhen building or modifying CLI tools, follow these rules to make them safe and\nreliable for AI agents to use.\n\n## Overview\n\nA comprehensive design specification for building AI-native CLI tools. It defines\n98 rules across three certification levels (Agent-Friendly, Agent-Ready, Agent-Native)\nwith prioritized requirements (P0\u002FP1\u002FP2). The spec covers structured JSON output,\nerror handling, input contracts, safety guardrails, exit codes, self-description,\nand a feedback loop via a built-in issue system.\n\n## When to Use This Skill\n\n- Use when building a new CLI tool that AI agents will invoke\n- Use when retrofitting an existing CLI to be agent-friendly\n- Use when designing command-line interfaces for automation pipelines\n- Use when auditing a CLI tool's compliance with agent-safety standards\n\n## Core Philosophy\n\n1. **Agent-first** -- default output is JSON; human-friendly is opt-in via `--human`\n2. **Agent is untrusted** -- validate all input at the same level as a public API\n3. **Fail-Closed** -- when validation logic itself errors, deny by default\n4. **Verifiable** -- every rule is written so it can be automatically checked\n\n## Layer Model\n\nThis spec uses two orthogonal axes:\n\n- **Layer** answers rollout scope: `core`, `recommended`, `ecosystem`\n- **Priority** answers severity: `P0`, `P1`, `P2`\n\nUse layers for migration and certification:\n\n- **core** -- execution contract: JSON, errors, exit codes, stdout\u002Fstderr, safety\n- **recommended** -- better machine UX: self-description, explicit modes, richer schemas\n- **ecosystem** -- agent-native integration: `agent\u002F`, `skills`, `issue`, inline context\n\nCertification maps to layers:\n\n- **Agent-Friendly** -- all `core` rules pass\n- **Agent-Ready** -- all `core` + `recommended` rules pass\n- **Agent-Native** -- all layers pass\n\n## How It Works\n\n### Step 1: Output Mode\n\nDefault is agent mode (JSON). Explicit flags to switch:\n\n```bash\n$ mycli list              # default = JSON output (agent mode)\n$ mycli list --human      # human-friendly: colored, tables, formatted\n$ mycli list --agent      # explicit agent mode (override config if needed)\n```\n\n- **Default (no flag)** -- JSON to stdout. Agent never needs to add a flag.\n- **--human** -- human-friendly format (colors, tables, progress bars)\n- **--agent** -- explicit JSON mode (useful when env\u002Fconfig overrides default)\n\n### Step 2: agent\u002F Directory Convention\n\nEvery CLI tool MUST have an `agent\u002F` directory at its project root. This is the\ntool's identity and behavior contract for AI agents.\n\n```\nagent\u002F\n  brief.md          # One paragraph: who am I, what can I do\n  rules\u002F            # Behavior constraints (auto-registered)\n    trigger.md      # When should an agent use this tool\n    workflow.md     # Step-by-step usage flow\n    writeback.md    # How to write feedback back\n  skills\u002F           # Extended capabilities (auto-registered)\n    getting-started.md\n```\n\n### Step 3: Four Levels of Self-Description\n\n1. **--brief** (business card, injected into agent config)\n2. **Every Command Response** (always-on context: data + rules + skills + issue)\n3. **--help** (full self-description: brief + commands + rules + skills + issue)\n4. **skills \\\u003Cname\\>** (on-demand deep dive into a specific skill)\n\n## Certification Requirements\n\nEach level includes all rules from the previous level.\nPriority tag `[P0]`=agent breaks without it, `[P1]`=agent works but poorly, `[P2]`=nice to have.\n\n### Level 1: Agent-Friendly (core -- 20 rules)\n\nGoal: CLI is a stable, callable API. Agent can invoke, parse, and handle errors.\n\n**Output** -- default is JSON, stable schema\n- `[P0]` O1: Default output is JSON. No `--json` flag needed\n- `[P0]` O2: JSON MUST pass `jq .` validation\n- `[P0]` O3: JSON schema MUST NOT change within same version\n\n**Error** -- structured, to stderr, never interactive\n- `[P0]` E1: Errors -> `{\"error\":true, \"code\":\"...\", \"message\":\"...\", \"suggestion\":\"...\"}` to stderr\n- `[P0]` E4: Error has machine-readable `code` (e.g. `MISSING_REQUIRED`)\n- `[P0]` E5: Error has human-readable `message`\n- `[P0]` E7: On error, NEVER enter interactive mode -- exit immediately\n- `[P0]` E8: Error codes are API contracts -- MUST NOT rename across versions\n\n**Exit Code** -- predictable failure signals\n- `[P0]` X3: Parameter\u002Fusage errors MUST exit 2\n- `[P0]` X9: Failures MUST exit non-zero -- never exit 0 then report error in stdout\n\n**Composability** -- clean pipe semantics\n- `[P0]` C1: stdout is for data ONLY\n- `[P0]` C2: logs, progress, warnings go to stderr ONLY\n\n**Input** -- fail fast on bad input\n- `[P1]` I4: Missing required param -> structured error, never interactive prompt\n- `[P1]` I5: Type mismatch -> exit 2 + structured error\n\n**Safety** -- protect against agent mistakes\n- `[P1]` S1: Destructive ops require `--yes` confirmation\n- `[P1]` S4: Reject `..\u002F..\u002F` path traversal, control chars\n\n**Guardrails** -- runtime input protection\n- `[P1]` G1: Unknown flags rejected with exit 2\n- `[P1]` G2: Detect API key \u002F token patterns in args, reject execution\n- `[P1]` G3: Reject sensitive file paths (*.env, *.key, *.pem)\n- `[P1]` G8: Reject shell metacharacters in arguments (; | && $())\n\n### Level 2: Agent-Ready (+ recommended -- 59 rules)\n\nGoal: CLI is self-describing, well-named, and pipe-friendly. Agent discovers capabilities and chains commands without trial and error.\n\n**Self-Description** -- agent discovers what CLI can do\n- `[P1]` D1: `--help` outputs structured JSON with `commands[]`\n- `[P1]` D3: Schema has required fields (help, commands)\n- `[P1]` D4: All parameters have type declarations\n- `[P1]` D7: Parameters annotated as required\u002Foptional\n- `[P1]` D9: Every command has a description\n- `[P1]` D11: `--help` outputs JSON with help, rules, skills, commands\n- `[P1]` D15: `--brief` outputs `agent\u002Fbrief.md` content\n- `[P1]` D16: Default JSON (agent mode), `--human` for human-friendly\n- `[P2]` D2\u002FD5\u002FD6\u002FD8\u002FD10: per-command help, enums, defaults, output schema, version\n\n**Input** -- unambiguous calling convention\n- `[P1]` I1: All flags use `--long-name` format\n- `[P1]` I2: No positional argument ambiguity\n- `[P2]` I3\u002FI6\u002FI7: --json-input, boolean --no-X, array params\n\n**Error**\n- `[P1]` E6: Error includes `suggestion` field\n- `[P2]` E2\u002FE3: errors to stderr, error JSON valid\n\n**Safety**\n- `[P1]` S8: `--sanitize` flag for external input\n- `[P2]` S2\u002FS3\u002FS5\u002FS6\u002FS7: default deny, --dry-run, no auto-update, destructive marking\n\n**Exit Code**\n- `[P1]` X1: 0 = success\n- `[P2]` X2\u002FX4-X8: 1=general, 10=auth, 11=permission, 20=not-found, 30=conflict\n\n**Composability**\n- `[P1]` C6: No interactive prompts in pipe mode\n- `[P2]` C3\u002FC4\u002FC5\u002FC7: pipe-friendly, --quiet, pipe chain, idempotency\n\n**Naming** -- predictable flag conventions\n- `[P1]` N4: Reserved flags (--agent, --human, --brief, --help, --version, --yes, --dry-run, --quiet, --fields)\n- `[P2]` N1\u002FN2\u002FN3\u002FN5\u002FN6: consistent naming, kebab-case, max 3 levels, --version semver\n\n**Guardrails**\n- `[P1]` I8\u002FI9: no implicit state, non-interactive auth\n- `[P1]` G6\u002FG9: precondition checks, fail-closed\n- `[P2]` G4\u002FG5\u002FG7: permission levels, PII redaction, batch limits\n\n#### Reserved Flags\n\n| Flag | Semantics | Notes |\n|------|-----------|-------|\n| `--agent` | JSON output (default) | Explicit override |\n| `--human` | Human-friendly output | Colors, tables, formatted |\n| `--brief` | One-paragraph identity | For sync into agent config |\n| `--help` | Full self-description JSON | Brief + commands + rules + skills + issue |\n| `--version` | Semver version string | |\n| `--yes` | Confirm destructive ops | Required for delete\u002Fdestroy |\n| `--dry-run` | Preview without executing | |\n| `--quiet` | Suppress stderr output | |\n| `--fields` | Filter output fields | Save tokens |\n\n### Level 3: Agent-Native (+ ecosystem -- 19 rules)\n\nGoal: CLI has identity, behavior contract, skill system, and feedback loop. Agent can learn the tool, extend its use, and report problems -- full closed-loop collaboration.\n\n**Agent Directory** -- tool identity and behavior contract\n- `[P1]` D12: `agent\u002Fbrief.md` exists\n- `[P1]` D13: `agent\u002Frules\u002F` has trigger.md, workflow.md, writeback.md\n- `[P1]` D17: agent\u002Frules\u002F*.md have YAML frontmatter (name, description)\n- `[P1]` D18: agent\u002Fskills\u002F*.md have YAML frontmatter (name, description)\n- `[P2]` D14: `agent\u002Fskills\u002F` directory + `skills` subcommand\n\n**Response Structure** -- inline context on every call\n- `[P1]` R1: Every response includes `rules[]` (full content from agent\u002Frules\u002F)\n- `[P1]` R2: Every response includes `skills[]` (name + description + command)\n- `[P1]` R3: Every response includes `issue` (feedback guide)\n\n**Meta** -- project-level integration\n- `[P2]` M1: AGENTS.md at project root\n- `[P2]` M2: Optional MCP tool schema export\n- `[P2]` M3: CHANGELOG.md marks breaking changes\n\n**Feedback** -- built-in issue system\n- `[P2]` F1: `issue` subcommand (create\u002Flist\u002Fshow)\n- `[P2]` F2: Structured submission with version\u002Fcontext\u002Fexit_code\n- `[P2]` F3: Categories: bug \u002F requirement \u002F suggestion \u002F bad-output\n- `[P2]` F4: Issues stored locally, no external service dependency\n- `[P2]` F5: `issue list` \u002F `issue show \u003Cid>` queryable\n- `[P2]` F6: Issues have status tracking (open\u002Fin-progress\u002Fresolved\u002Fclosed)\n- `[P2]` F7: Issue JSON has all required fields (id, type, status, message, created_at, updated_at)\n- `[P2]` F8: All issues have status field\n\n## Examples\n\n### Example 1: JSON Output (Agent Mode)\n\n```bash\n$ mycli list\n{\"result\": [{\"id\": 1, \"title\": \"Buy milk\", \"status\": \"todo\"}], \"rules\": [...], \"skills\": [...], \"issue\": \"...\"}\n```\n\n### Example 2: Structured Error\n\n```json\n{\n  \"error\": true,\n  \"code\": \"AUTH_EXPIRED\",\n  \"message\": \"Access token expired 2 hours ago\",\n  \"suggestion\": \"Run 'mycli auth refresh' to get a new token\"\n}\n```\n\n### Example 3: Exit Code Table\n\n```\n0   success         10  auth failed       20  resource not found\n1   general error   11  permission denied 30  conflict\u002Fprecondition\n2   param\u002Fusage error\n```\n\n## Quick Implementation Checklist\n\nImplement by layer -- each phase gets you the next certification level.\n\n**Phase 1: Agent-Friendly (core)**\n1. Default output is JSON -- no `--json` flag needed\n2. Error handler: `{ error, code, message, suggestion }` to stderr\n3. Exit codes: 0 success, 2 param error, 1 general\n4. stdout = data only, stderr = logs only\n5. Missing param -> structured error (never interactive)\n6. `--yes` guard on destructive operations\n7. Guardrails: reject secrets, path traversal, shell metacharacters\n\n**Phase 2: Agent-Ready (+ recommended)**\n8. `--help` returns structured JSON (help, commands[], rules[], skills[])\n9. `--brief` reads and outputs `agent\u002Fbrief.md` content\n10. `--human` flag switches to human-friendly format\n11. Reserved flags: --agent, --version, --dry-run, --quiet, --fields\n12. Exit codes: 20 not found, 30 conflict, 10 auth, 11 permission\n\n**Phase 3: Agent-Native (+ ecosystem)**\n13. Create `agent\u002F` directory: `brief.md`, `rules\u002Ftrigger.md`, `rules\u002Fworkflow.md`, `rules\u002Fwriteback.md`\n14. Every command response appends: rules[] + skills[] + issue\n15. `skills` subcommand: list all \u002F show one with full content\n16. `issue` subcommand for feedback (create\u002Flist\u002Fshow\u002Fclose\u002Ftransition)\n17. AGENTS.md at project root\n\n## Best Practices\n\n- Do: Default to JSON output so agents never need to add flags\n- Do: Include `suggestion` field in every error response\n- Do: Use the three-level certification model for incremental adoption\n- Do: Keep `agent\u002Fbrief.md` to one paragraph for token efficiency\n- Don't: Enter interactive mode on errors -- always exit immediately\n- Don't: Change JSON schema or error codes within the same version\n- Don't: Put logs or progress info on stdout -- use stderr only\n- Don't: Accept unknown flags silently -- reject with exit code 2\n\n## Common Pitfalls\n\n- **Problem:** CLI outputs human-readable text by default, breaking agent parsing\n  **Solution:** Make JSON the default output format; add `--human` flag for human-friendly mode\n\n- **Problem:** Errors reported in stdout with exit code 0\n  **Solution:** Always exit non-zero on failure and write structured error JSON to stderr\n\n- **Problem:** CLI prompts for missing input interactively\n  **Solution:** Return structured error with suggestion field and exit immediately\n\n## Related Skills\n\n- `@cli-best-practices` - General CLI design patterns (this skill focuses specifically on AI agent compatibility)\n\n## Additional Resources\n\n- [Agent CLI Spec Repository](https:\u002F\u002Fgithub.com\u002FChaosRealmsAI\u002Fagent-cli-spec)\n","# Agent-Friendly CLI Spec v0.1\n\nWhen building or modifying CLI tools, follow these rules to make them safe and\nreliable for AI agents to use.\n\n## Overview\n\nA comprehensive design specification for building AI-native CLI tools. It defines\n98 rules across three certification levels (Agent-Friendly, Agent-Ready, Agent-Native)\nwith prioritized requirements (P0\u002FP1\u002FP2). The spec covers structured JSON output,\nerror handling, input contracts, safety guardrails, exit codes, self-description,\nand a feedback loop via a built-in issue system.\n\n## When to Use This Skill\n\n- Use when building a new CLI tool that AI agents will invoke\n- Use when retrofitting an existing CLI to be agent-friendly\n- Use when designing command-line interfaces for automation pipelines\n- Use when auditing a CLI tool's compliance with agent-safety standards\n\n## Core Philosophy\n\n1. **Agent-first** -- default output is JSON; human-friendly is opt-in via `--human`\n2. **Agent is untrusted** -- validate all input at the same level as a public API\n3. **Fail-Closed** -- when validation logic itself errors, deny by default\n4. **Verifiable** -- every rule is written so it can be automatically checked\n\n## Layer Model\n\nThis spec uses two orthogonal axes:\n\n- **Layer** answers rollout scope: `core`, `recommended`, `ecosystem`\n- **Priority** answers severity: `P0`, `P1`, `P2`\n\nUse layers for migration and certification:\n\n- **core** -- execution contract: JSON, errors, exit codes, stdout\u002Fstderr, safety\n- **recommended** -- better machine UX: self-description, explicit modes, richer schemas\n- **ecosystem** -- agent-native integration: `agent\u002F`, `skills`, `issue`, inline context\n\nCertification maps to layers:\n\n- **Agent-Friendly** -- all `core` rules pass\n- **Agent-Ready** -- all `core` + `recommended` rules pass\n- **Agent-Native** -- all layers pass\n\n## How It Works\n\n### Step 1: Output Mode\n\nDefault is agent mode (JSON). Explicit flags to switch:\n\n```bash\n$ mycli list              # default = JSON output (agent mode)\n$ mycli list --human      # human-friendly: colored, tables, formatted\n$ mycli list --agent      # explicit agent mode (override config if needed)\n```\n\n- **Default (no flag)** -- JSON to stdout. Agent never needs to add a flag.\n- **--human** -- human-friendly format (colors, tables, progress bars)\n- **--agent** -- explicit JSON mode (useful when env\u002Fconfig overrides default)\n\n### Step 2: agent\u002F Directory Convention\n\nEvery CLI tool MUST have an `agent\u002F` directory at its project root. This is the\ntool's identity and behavior contract for AI agents.\n\n```\nagent\u002F\n  brief.md          # One paragraph: who am I, what can I do\n  rules\u002F            # Behavior constraints (auto-registered)\n    trigger.md      # When should an agent use this tool\n    workflow.md     # Step-by-step usage flow\n    writeback.md    # How to write feedback back\n  skills\u002F           # Extended capabilities (auto-registered)\n    getting-started.md\n```\n\n### Step 3: Four Levels of Self-Description\n\n1. **--brief** (business card, injected into agent config)\n2. **Every Command Response** (always-on context: data + rules + skills + issue)\n3. **--help** (full self-description: brief + commands + rules + skills + issue)\n4. **skills \\\u003Cname\\>** (on-demand deep dive into a specific skill)\n\n## Certification Requirements\n\nEach level includes all rules from the previous level.\nPriority tag `[P0]`=agent breaks without it, `[P1]`=agent works but poorly, `[P2]`=nice to have.\n\n### Level 1: Agent-Friendly (core -- 20 rules)\n\nGoal: CLI is a stable, callable API. Agent can invoke, parse, and handle errors.\n\n**Output** -- default is JSON, stable schema\n- `[P0]` O1: Default output is JSON. No `--json` flag needed\n- `[P0]` O2: JSON MUST pass `jq .` validation\n- `[P0]` O3: JSON schema MUST NOT change within same version\n\n**Error** -- structured, to stderr, never interactive\n- `[P0]` E1: Errors -> `{\"error\":true, \"code\":\"...\", \"message\":\"...\", \"suggestion\":\"...\"}` to stderr\n- `[P0]` E4: Error has machine-readable `code` (e.g. `MISSING_REQUIRED`)\n- `[P0]` E5: Error has human-readable `message`\n- `[P0]` E7: On error, NEVER enter interactive mode -- exit immediately\n- `[P0]` E8: Error codes are API contracts -- MUST NOT rename across versions\n\n**Exit Code** -- predictable failure signals\n- `[P0]` X3: Parameter\u002Fusage errors MUST exit 2\n- `[P0]` X9: Failures MUST exit non-zero -- never exit 0 then report error in stdout\n\n**Composability** -- clean pipe semantics\n- `[P0]` C1: stdout is for data ONLY\n- `[P0]` C2: logs, progress, warnings go to stderr ONLY\n\n**Input** -- fail fast on bad input\n- `[P1]` I4: Missing required param -> structured error, never interactive prompt\n- `[P1]` I5: Type mismatch -> exit 2 + structured error\n\n**Safety** -- protect against agent mistakes\n- `[P1]` S1: Destructive ops require `--yes` confirmation\n- `[P1]` S4: Reject `..\u002F..\u002F` path traversal, control chars\n\n**Guardrails** -- runtime input protection\n- `[P1]` G1: Unknown flags rejected with exit 2\n- `[P1]` G2: Detect API key \u002F token patterns in args, reject execution\n- `[P1]` G3: Reject sensitive file paths (*.env, *.key, *.pem)\n- `[P1]` G8: Reject shell metacharacters in arguments (; | && $())\n\n### Level 2: Agent-Ready (+ recommended -- 59 rules)\n\nGoal: CLI is self-describing, well-named, and pipe-friendly. Agent discovers capabilities and chains commands without trial and error.\n\n**Self-Description** -- agent discovers what CLI can do\n- `[P1]` D1: `--help` outputs structured JSON with `commands[]`\n- `[P1]` D3: Schema has required fields (help, commands)\n- `[P1]` D4: All parameters have type declarations\n- `[P1]` D7: Parameters annotated as required\u002Foptional\n- `[P1]` D9: Every command has a description\n- `[P1]` D11: `--help` outputs JSON with help, rules, skills, commands\n- `[P1]` D15: `--brief` outputs `agent\u002Fbrief.md` content\n- `[P1]` D16: Default JSON (agent mode), `--human` for human-friendly\n- `[P2]` D2\u002FD5\u002FD6\u002FD8\u002FD10: per-command help, enums, defaults, output schema, version\n\n**Input** -- unambiguous calling convention\n- `[P1]` I1: All flags use `--long-name` format\n- `[P1]` I2: No positional argument ambiguity\n- `[P2]` I3\u002FI6\u002FI7: --json-input, boolean --no-X, array params\n\n**Error**\n- `[P1]` E6: Error includes `suggestion` field\n- `[P2]` E2\u002FE3: errors to stderr, error JSON valid\n\n**Safety**\n- `[P1]` S8: `--sanitize` flag for external input\n- `[P2]` S2\u002FS3\u002FS5\u002FS6\u002FS7: default deny, --dry-run, no auto-update, destructive marking\n\n**Exit Code**\n- `[P1]` X1: 0 = success\n- `[P2]` X2\u002FX4-X8: 1=general, 10=auth, 11=permission, 20=not-found, 30=conflict\n\n**Composability**\n- `[P1]` C6: No interactive prompts in pipe mode\n- `[P2]` C3\u002FC4\u002FC5\u002FC7: pipe-friendly, --quiet, pipe chain, idempotency\n\n**Naming** -- predictable flag conventions\n- `[P1]` N4: Reserved flags (--agent, --human, --brief, --help, --version, --yes, --dry-run, --quiet, --fields)\n- `[P2]` N1\u002FN2\u002FN3\u002FN5\u002FN6: consistent naming, kebab-case, max 3 levels, --version semver\n\n**Guardrails**\n- `[P1]` I8\u002FI9: no implicit state, non-interactive auth\n- `[P1]` G6\u002FG9: precondition checks, fail-closed\n- `[P2]` G4\u002FG5\u002FG7: permission levels, PII redaction, batch limits\n\n#### Reserved Flags\n\n| Flag | Semantics | Notes |\n|------|-----------|-------|\n| `--agent` | JSON output (default) | Explicit override |\n| `--human` | Human-friendly output | Colors, tables, formatted |\n| `--brief` | One-paragraph identity | For sync into agent config |\n| `--help` | Full self-description JSON | Brief + commands + rules + skills + issue |\n| `--version` | Semver version string | |\n| `--yes` | Confirm destructive ops | Required for delete\u002Fdestroy |\n| `--dry-run` | Preview without executing | |\n| `--quiet` | Suppress stderr output | |\n| `--fields` | Filter output fields | Save tokens |\n\n### Level 3: Agent-Native (+ ecosystem -- 19 rules)\n\nGoal: CLI has identity, behavior contract, skill system, and feedback loop. Agent can learn the tool, extend its use, and report problems -- full closed-loop collaboration.\n\n**Agent Directory** -- tool identity and behavior contract\n- `[P1]` D12: `agent\u002Fbrief.md` exists\n- `[P1]` D13: `agent\u002Frules\u002F` has trigger.md, workflow.md, writeback.md\n- `[P1]` D17: agent\u002Frules\u002F*.md have YAML frontmatter (name, description)\n- `[P1]` D18: agent\u002Fskills\u002F*.md have YAML frontmatter (name, description)\n- `[P2]` D14: `agent\u002Fskills\u002F` directory + `skills` subcommand\n\n**Response Structure** -- inline context on every call\n- `[P1]` R1: Every response includes `rules[]` (full content from agent\u002Frules\u002F)\n- `[P1]` R2: Every response includes `skills[]` (name + description + command)\n- `[P1]` R3: Every response includes `issue` (feedback guide)\n\n**Meta** -- project-level integration\n- `[P2]` M1: AGENTS.md at project root\n- `[P2]` M2: Optional MCP tool schema export\n- `[P2]` M3: CHANGELOG.md marks breaking changes\n\n**Feedback** -- built-in issue system\n- `[P2]` F1: `issue` subcommand (create\u002Flist\u002Fshow)\n- `[P2]` F2: Structured submission with version\u002Fcontext\u002Fexit_code\n- `[P2]` F3: Categories: bug \u002F requirement \u002F suggestion \u002F bad-output\n- `[P2]` F4: Issues stored locally, no external service dependency\n- `[P2]` F5: `issue list` \u002F `issue show \u003Cid>` queryable\n- `[P2]` F6: Issues have status tracking (open\u002Fin-progress\u002Fresolved\u002Fclosed)\n- `[P2]` F7: Issue JSON has all required fields (id, type, status, message, created_at, updated_at)\n- `[P2]` F8: All issues have status field\n\n## Examples\n\n### Example 1: JSON Output (Agent Mode)\n\n```bash\n$ mycli list\n{\"result\": [{\"id\": 1, \"title\": \"Buy milk\", \"status\": \"todo\"}], \"rules\": [...], \"skills\": [...], \"issue\": \"...\"}\n```\n\n### Example 2: Structured Error\n\n```json\n{\n  \"error\": true,\n  \"code\": \"AUTH_EXPIRED\",\n  \"message\": \"Access token expired 2 hours ago\",\n  \"suggestion\": \"Run 'mycli auth refresh' to get a new token\"\n}\n```\n\n### Example 3: Exit Code Table\n\n```\n0   success         10  auth failed       20  resource not found\n1   general error   11  permission denied 30  conflict\u002Fprecondition\n2   param\u002Fusage error\n```\n\n## Quick Implementation Checklist\n\nImplement by layer -- each phase gets you the next certification level.\n\n**Phase 1: Agent-Friendly (core)**\n1. Default output is JSON -- no `--json` flag needed\n2. Error handler: `{ error, code, message, suggestion }` to stderr\n3. Exit codes: 0 success, 2 param error, 1 general\n4. stdout = data only, stderr = logs only\n5. Missing param -> structured error (never interactive)\n6. `--yes` guard on destructive operations\n7. Guardrails: reject secrets, path traversal, shell metacharacters\n\n**Phase 2: Agent-Ready (+ recommended)**\n8. `--help` returns structured JSON (help, commands[], rules[], skills[])\n9. `--brief` reads and outputs `agent\u002Fbrief.md` content\n10. `--human` flag switches to human-friendly format\n11. Reserved flags: --agent, --version, --dry-run, --quiet, --fields\n12. Exit codes: 20 not found, 30 conflict, 10 auth, 11 permission\n\n**Phase 3: Agent-Native (+ ecosystem)**\n13. Create `agent\u002F` directory: `brief.md`, `rules\u002Ftrigger.md`, `rules\u002Fworkflow.md`, `rules\u002Fwriteback.md`\n14. Every command response appends: rules[] + skills[] + issue\n15. `skills` subcommand: list all \u002F show one with full content\n16. `issue` subcommand for feedback (create\u002Flist\u002Fshow\u002Fclose\u002Ftransition)\n17. AGENTS.md at project root\n\n## Best Practices\n\n- Do: Default to JSON output so agents never need to add flags\n- Do: Include `suggestion` field in every error response\n- Do: Use the three-level certification model for incremental adoption\n- Do: Keep `agent\u002Fbrief.md` to one paragraph for token efficiency\n- Don't: Enter interactive mode on errors -- always exit immediately\n- Don't: Change JSON schema or error codes within the same version\n- Don't: Put logs or progress info on stdout -- use stderr only\n- Don't: Accept unknown flags silently -- reject with exit code 2\n\n## Common Pitfalls\n\n- **Problem:** CLI outputs human-readable text by default, breaking agent parsing\n  **Solution:** Make JSON the default output format; add `--human` flag for human-friendly mode\n\n- **Problem:** Errors reported in stdout with exit code 0\n  **Solution:** Always exit non-zero on failure and write structured error JSON to stderr\n\n- **Problem:** CLI prompts for missing input interactively\n  **Solution:** Return structured error with suggestion field and exit immediately\n\n## Related Skills\n\n- `@cli-best-practices` - General CLI design patterns (this skill focuses specifically on AI agent compatibility)\n\n## Additional Resources\n\n- [Agent CLI Spec Repository](https:\u002F\u002Fgithub.com\u002FChaosRealmsAI\u002Fagent-cli-spec)\n",{"name":5,"risk":43,"source":49,"date_added":50,"description":7},"https:\u002F\u002Fgithub.com\u002FChaosRealmsAI\u002Fagent-cli-spec","2026-03-15","main","7a38d8e7073e61c16eda85681cb32fb68a8657a5","skills-store\u002Fcursor\u002Fai-native-cli","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router","https:\u002F\u002Fgithub.com\u002Fsapsapshen","2026-04-14 21:12:12",{"source":8,"skillName":5,"commands":58,"prompt":68,"zipAvailable":69},[59,62,65],{"tool":60,"command":61},"npx","npx skills add sapsapshen\u002Fai-memory-router --skill ai-native-cli",{"tool":63,"command":64},"bunx","bunx skills add sapsapshen\u002Fai-memory-router --skill ai-native-cli",{"tool":66,"command":67},"pnpm","pnpm dlx skills add sapsapshen\u002Fai-memory-router --skill ai-native-cli","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fcursor\u002Fai-native-cli\u002FSKILL.md",true,[],[72,95,121,131,144,160],{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":83,"publishedAt":44},"01M71ATQRKG48SH06FQ697T5G9","wechat-search","Search WeChat Official Account articles using OpenClaw's web search and fetch capabilities with compliance-focused design.","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fopenclaw\u002Fwechat-search-release\u002FSKILL.md",[78],{"categoryNo":79,"categoryName":80,"taxonomyType":81,"taxonomyTypeDesc":82},"01JBSEEDCAT000000000000037","律师与法务","PROFESSION","适用职业",[84,85,86,87,88,29,89,90,91,92,93,94],"wechat search","wechat","search","capabilities","openclaw","web search","compliance","web","official","fetch","with",{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":44},"01M71ATNAVGZB35PFYM2GC5N00","trend-tap","Real-time trending topics aggregator across 7 platforms (X\u002FTwitter, Reddit, Google Trends, Hacker News, Zhihu, Bilibili, Weibo). Trigger: when user says 'trend', 'trends', 'trend tap', '热点', '热搜', or asks what is trending\u002Fhot. Do NOT use web_search — this skill already fetches live data from all platforms with zero API keys.","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fopenclaw\u002Ftrend-tap\u002FSKILL.md",[],[102,103,104,105,106,107,86,108,109,110,111,112,113,114,115,116,117,118,119,120],"trend","trend tap","tap","api keys","Bash","time","trending","hacker","aggregator","do","when","brew","live","data","google","install","read","across","api",{"skillNo":122,"name":123,"nameZh":6,"description":124,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":125,"categories":126,"keywords":127,"publishedAt":44},"01M71ATJ9AM5KM15AA8PS302EB","trend-radar","Real-time trending topics aggregator across 7 platforms (X\u002FTwitter, Reddit, Google Trends, Hacker News, Zhihu, Bilibili, Weibo). Trigger: when user says 'trend', 'trends', 'trend pulse', '热点', '热搜', or asks what is trending\u002Fhot. Do NOT use web_search — this skill already fetches live data from all platforms with zero API keys.","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fopenclaw\u002Ftrend-radar\u002FSKILL.md",[],[128,129,102,113,114,115,116,106,86,118,130,119,120,112,110,109,108,117,107,105],"trend radar","radar","pulse",{"skillNo":132,"name":133,"nameZh":6,"description":134,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":135,"categories":136,"keywords":137,"publishedAt":44},"01M71ATGF095N3EJM9G8SD0BB5","tech-news-daily","每日科技新闻汇——从全球多个 RSS 源抓取最新科技新闻，翻译（英→中）、去重、排版成每日简报。当用户询问科技新闻、科技新鲜事、每日科技、技术动态、Daily Tech News 或类似表达时触发此技能。","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fopenclaw\u002Ftech-news-daily\u002FSKILL.md",[],[138,139,140,141,142,143],"news","tech","tech news daily","daily","rss","翻译",{"skillNo":145,"name":146,"nameZh":6,"description":147,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":148,"categories":149,"keywords":153,"publishedAt":44},"01M71ATFAEAMQ17M70NQNY7SR8","summarize","Summarize URLs or files with the summarize CLI (web, PDFs, images, audio, YouTube).","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fopenclaw\u002Fsummarize\u002FSKILL.md",[150],{"categoryNo":151,"categoryName":152,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000021","资料检索与研究",[146,91,154,24,155,94,113,156,157,158,104,159,117],"Audio","youtube","images","https","files","pdfs",{"skillNo":161,"name":162,"nameZh":6,"description":163,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":164,"categories":165,"keywords":166,"publishedAt":44},"01M71ATDNS3R0M4H936PACQAWZ","sonoscli","Control Sonos speakers (discover\u002Fstatus\u002Fplay\u002Fvolume\u002Fgroup).","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fopenclaw\u002Fsonoscli\u002FSKILL.md",[],[162,167,168,169,117,170,157,171,172,173,174,175],"status","play","go","latest","github","discover","control","cmd","volume"]