From 26a1497493298e36d8bf39208a57bb59252a811e Mon Sep 17 00:00:00 2001 From: ericzakariasson Date: Thu, 26 Mar 2026 10:37:40 +0100 Subject: [PATCH] feat: add cli-for-agent plugin with agent-friendly CLI skill Add marketplace plugin listing the cli-for-agents skill: non-interactive flags, layered help with examples, pipelines, actionable errors, idempotency, dry-run, and predictable command structure. Made-with: Cursor --- .cursor-plugin/marketplace.json | 5 ++ README.md | 1 + cli-for-agent/.cursor-plugin/plugin.json | 30 +++++++ cli-for-agent/LICENSE | 21 +++++ cli-for-agent/README.md | 11 +++ cli-for-agent/skills/cli-for-agents/SKILL.md | 87 ++++++++++++++++++++ 6 files changed, 155 insertions(+) create mode 100644 cli-for-agent/.cursor-plugin/plugin.json create mode 100644 cli-for-agent/LICENSE create mode 100644 cli-for-agent/README.md create mode 100644 cli-for-agent/skills/cli-for-agents/SKILL.md diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index bb5e31f..4df6677 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -37,6 +37,11 @@ "name": "agent-compatibility", "source": "agent-compatibility", "description": "CLI-backed repo compatibility scans plus Cursor agents that audit startup, validation, and docs against reality." + }, + { + "name": "cli-for-agent", + "source": "cli-for-agent", + "description": "Patterns for designing CLIs that coding agents can run reliably: flags, help with examples, pipelines, errors, idempotency, dry-run." } ] } diff --git a/README.md b/README.md index e64eb1f..e84e9a0 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc | `cursor-team-kit` | [Cursor Team Kit](cursor-team-kit/) | Cursor | Developer Tools | Internal team workflows used by Cursor developers for CI, code review, and shipping. | | `create-plugin` | [Create Plugin](create-plugin/) | Cursor | Developer Tools | Scaffold and validate new Cursor plugins. | | `agent-compatibility` | [Agent Compatibility](agent-compatibility/) | Cursor | Developer Tools | CLI-backed repo compatibility scans plus Cursor agents that audit startup, validation, and docs against reality. | +| `cli-for-agent` | [CLI for Agents](cli-for-agent/) | Cursor | Developer Tools | Patterns for designing CLIs that coding agents can run reliably: flags, help with examples, pipelines, errors, idempotency, dry-run. | Author values match each plugin’s `plugin.json` `author.name` (Cursor lists `plugins@cursor.com` in the manifest). diff --git a/cli-for-agent/.cursor-plugin/plugin.json b/cli-for-agent/.cursor-plugin/plugin.json new file mode 100644 index 0000000..c0d3a06 --- /dev/null +++ b/cli-for-agent/.cursor-plugin/plugin.json @@ -0,0 +1,30 @@ +{ + "name": "cli-for-agent", + "displayName": "CLI for Agents", + "version": "1.0.0", + "description": "Patterns for designing CLIs that coding agents can run reliably: non-interactive flags, layered help with examples, pipelines, actionable errors, idempotency, and dry-run.", + "author": { + "name": "Cursor", + "email": "plugins@cursor.com" + }, + "homepage": "https://github.com/cursor/plugins/tree/main/cli-for-agent", + "repository": "https://github.com/cursor/plugins", + "license": "MIT", + "keywords": [ + "cli", + "command-line", + "agents", + "automation", + "terminal", + "flags", + "help" + ], + "category": "developer-tools", + "tags": [ + "cli", + "agents", + "automation", + "developer-tools" + ], + "skills": "./skills/" +} diff --git a/cli-for-agent/LICENSE b/cli-for-agent/LICENSE new file mode 100644 index 0000000..ca2bba7 --- /dev/null +++ b/cli-for-agent/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Cursor + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/cli-for-agent/README.md b/cli-for-agent/README.md new file mode 100644 index 0000000..6aaedae --- /dev/null +++ b/cli-for-agent/README.md @@ -0,0 +1,11 @@ +# CLI for Agents + +Cursor plugin with a single skill that encodes patterns for **CLIs meant to be driven by coding agents**: non-interactive flags first, layered `--help` with examples, stdin and pipelines, fast actionable errors, idempotency, `--dry-run`, and predictable command structure. + +## What it includes + +- `cli-for-agents`: design and review guidance for agent-friendly command-line tools + +## When to use it + +Use when you are building or refactoring a CLI, writing subcommand help, or reviewing whether an existing tool will block agents (interactive prompts, missing examples, ambiguous errors). diff --git a/cli-for-agent/skills/cli-for-agents/SKILL.md b/cli-for-agent/skills/cli-for-agents/SKILL.md new file mode 100644 index 0000000..3c56038 --- /dev/null +++ b/cli-for-agent/skills/cli-for-agents/SKILL.md @@ -0,0 +1,87 @@ +--- +name: cli-for-agents +description: >- + Designs or reviews CLIs so coding agents can run them reliably: non-interactive + flags, layered --help with examples, stdin/pipelines, fast actionable errors, + idempotency, dry-run, and predictable structure. Use when building a CLI, + adding commands, writing --help, or when the user mentions agents, terminals, + or automation-friendly CLIs. +--- + +# CLI for agents + +Human-oriented CLIs often block agents: interactive prompts, huge upfront docs, and help text without copy-pasteable examples. Prefer patterns that work headlessly and compose in pipelines. + +## Non-interactive first + +- Every input should be expressible as a flag or flag value. Do not require arrow keys, menus, or timed prompts. +- If flags are missing, **then** fall back to interactive mode—not the other way around. + +**Bad:** `mycli deploy` → `? Which environment? (use arrow keys)` +**Good:** `mycli deploy --env staging` + +## Discoverability without dumping context + +- Agents discover subcommands incrementally: `mycli`, then `mycli deploy --help`. Do not print the entire manual on every run. +- Let each subcommand own its documentation so unused commands stay out of context. + +## `--help` that works + +- Every subcommand has `--help`. +- Every `--help` includes **Examples** with real invocations. Examples do more than prose for pattern-matching. + +```text +Options: + --env Target environment (staging, production) + --tag Image tag (default: latest) + --force Skip confirmation + +Examples: + mycli deploy --env staging + mycli deploy --env production --tag v1.2.3 + mycli deploy --env staging --force +``` + +## stdin, flags, and pipelines + +- Accept stdin where it makes sense (e.g. `cat config.json | mycli config import --stdin`). +- Avoid odd positional ordering and avoid falling back to interactive prompts for missing values. +- Support chaining: `mycli deploy --env staging --tag $(mycli build --output tag-only)`. + +## Fail fast with actionable errors + +- On missing required flags: exit immediately with a clear message and a **correct example invocation**, not a hang. + +```text +Error: No image tag specified. + mycli deploy --env staging --tag + Available tags: mycli build list --output tags +``` + +## Idempotency + +- Agents retry often. The same successful command run twice should be safe (no-op or explicit "already done"), not duplicate side effects. + +## Destructive actions + +- Add `--dry-run` (or equivalent) so agents can preview plans before committing. +- Offer `--yes` / `--force` to skip confirmations while keeping the safe default for humans. + +## Predictable structure + +- Use a consistent pattern everywhere, e.g. `resource` + `verb`: if `mycli service list` exists, `mycli deploy list` and `mycli config list` should follow the same shape. + +## Success output + +- On success, return machine-useful data: IDs, URLs, durations. Plain text is fine; avoid relying on decorative output alone. + +```text +deployed v1.2.3 to staging +url: https://staging.myapp.com +deploy_id: dep_abc123 +duration: 34s +``` + +## When reviewing an existing CLI + +- Check: non-interactive path, layered help, examples on `--help`, stdin/pipeline story, error messages with invocations, idempotency, dry-run, confirmation bypass flags, consistent command structure, structured success output.