Cursor plugin specification and official plugins
TypeScript
feat: add cli-for-agent plugin with agent-friendly CLI skill
ericzakariasson26a149749329
diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.jsonindex bb5e31f0..4df6677e 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.mdindex e64eb1ff..e84e9a02 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 `[email protected]` in the manifest).diff --git a/cli-for-agent/.cursor-plugin/plugin.json b/cli-for-agent/.cursor-plugin/plugin.jsonnew file mode 100644index 00000000..c0d3a06a--- /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": "[email protected]"+ },+ "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/LICENSEnew file mode 100644index 00000000..ca2bba77--- /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.mdnew file mode 100644index 00000000..6aaedae1--- /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.mdnew file mode 100644index 00000000..3c560387--- /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 <image-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.