Skip to content

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.json
index 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.md
index 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.json
new file mode 100644
index 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/LICENSE
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.