Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
feat(ai): add "create-cli" skill
jkomyno committed
Feb 18, 2026 at 15:54 UTC
33e6c97f31895abf6506337bc7bc493c51bca355
3 files changed
+333
.claude/skills/create-cli/SKILL.md
new
+1
@@ -0,0 +1 @@
1
+../../../ts/packages/cli/.cursor/rules/cli-design-guidelines.mdc
\ No newline at end of file
ts/packages/cli/.cursor/rules/cli-design-guidelines.mdc
new
+321
@@ -0,0 +1,321 @@
1
+---
2
+description: CLI design guidelines — arguments, flags, subcommands, help, output, errors, interactivity, config precedence. Apply when designing new commands or reviewing CLI UX.
3
+globs:
4
+ - "src/**/*.ts"
5
+alwaysApply: true
6
+---
7
+
8
+# CLI Design Guidelines
9
+
10
+Design CLI surface area (syntax + behavior), human-first, script-friendly.
11
+Adapted from [clig.dev](https://clig.dev/) for our TypeScript + Effect.ts + Clack stack.
12
+
13
+## When to Use
14
+
15
+- Designing a CLI spec (before implementation) or refactoring CLI surface area.
16
+- Adding new commands, flags, or interactive prompts.
17
+- Reviewing CLI UX decisions.
18
+
19
+## Our Stack
20
+
21
+| Library | Role | Source reference |
22
+| ------- | ---- | --------------- |
23
+| `@effect/cli` | Command, Options, Args declaration and parsing | `ts/vendor/effect/packages/cli/src/` |
24
+| `@clack/prompts` | Interactive terminal UI (prompts, spinners, logs, notes) | `ts/vendor/clack/packages/prompts/src/` |
25
+| `effect` | Core runtime, services, layers, error handling | `ts/vendor/effect/packages/effect/src/` |
26
+| `@effect/platform` | FileSystem, Terminal abstraction | `ts/vendor/effect/packages/platform/src/` |
27
+
28
+Existing architecture is documented in `ts/packages/cli/AGENTS.md`.
29
+
30
+## Philosophy
31
+
32
+1. **Human-first design** — Optimize for humans; scripts work via `--json`, `--plain`, exit codes.
33
+2. **Simple parts that work together** — stdout for data, stderr for decoration, respect exit codes and signals.
34
+3. **Consistency** — Reuse standard flag names (`--help`, `--version`, `--json`, `--dry-run`).
35
+4. **Say just enough** — Brief success output, visible progress, no noise.
36
+5. **Ease of discovery** — Help text is UX. Lead with examples; suggest next commands on error.
37
+6. **Conversation as the norm** — Expect trial-and-error. Provide `--dry-run` and confirmations for scary actions.
38
+7. **Robustness** — Validate early, fail fast, no stack traces by default.
39
+8. **Empathy** — Make success likely; make failure informative. Character is fine; clutter is not.
40
+
41
+## Output Conventions
42
+
43
+The CLI separates human-readable decoration from machine-readable data:
44
+
45
+- **stdout** — data only (`ui.output()`). Captured by pipes and scripts.
46
+- **stderr** — all decoration (Clack spinners, logs, notes, intro/outro). Visible in terminal, invisible in pipes.
47
+
48
+Rules:
49
+
50
+1. All `TerminalUI` methods except `output()` write to stderr via `{ output: process.stderr }`.
51
+2. `ui.output(data)` writes to stdout only when piped — no-op in interactive mode.
52
+3. When stdout is piped, ALL decoration is suppressed. Only `ui.output()` writes.
53
+4. Never write data to stderr. Never write decoration to stdout.
54
+
55
+```typescript
56
+// Data command (e.g., whoami):
57
+yield* ui.note(apiKey, 'API Key'); // Decoration → stderr
58
+yield* ui.output(apiKey); // Data → stdout
59
+
60
+// Action command (e.g., login):
61
+yield* ui.intro('composio login'); // Decoration → stderr
62
+yield* ui.log.step('Redirecting'); // Decoration → stderr
63
+// No ui.output() — nothing for scripts to capture
64
+```
65
+
66
+When adding a command, ask: "Does this produce a value scripts should capture?"
67
+- **Yes** → `ui.output(value)` for data, `ui.log.*` / `ui.note()` for context.
68
+- **No** → Only `ui.log.*` / `ui.note()` / `ui.intro()` / `ui.outro()`.
69
+
70
+**Show state changes.** When a command modifies state, say what changed and the new state:
71
+
72
+```typescript
73
+// After logout:
74
+yield* ui.log.info('Removed API key from ~/.composio/user-config.json');
75
+
76
+// After generate:
77
+yield* ui.log.success('Generated 42 tools across 5 toolkits → src/generated/');
78
+```
79
+
80
+## Arguments & Flags
81
+
82
+Define options via `@effect/cli`:
83
+
84
+```typescript
85
+const toolkits = Options.text('toolkits').pipe(
86
+ Options.optional,
87
+ Options.withDescription('Comma-separated toolkit slugs'),
88
+);
89
+const force = Options.boolean('force').pipe(
90
+ Options.withAlias('f'),
91
+ Options.withDefault(false),
92
+);
93
+```
94
+
95
+Principles:
96
+- Prefer flags over positional args for clarity and extensibility.
97
+- Provide long versions of all flags; one-letter aliases only for the most common.
98
+- Default values should be right for most users.
99
+- Never accept secrets via flags — they leak to `ps` output and shell history. Use `--password-file`, stdin, or a secret manager instead.
100
+- Support `-` for stdin/stdout when input/output is a file path.
101
+
102
+Standard flag names:
103
+
104
+| Flag | Short | Purpose |
105
+| ---- | ----- | ------- |
106
+| `--help` | `-h` | Show help (built-in via @effect/cli) |
107
+| `--version` | | Print version to stdout |
108
+| `--quiet` | `-q` | Less output |
109
+| `--verbose` | `-v` | More output (never use `-v` for version) |
110
+| `--debug` | `-d` | Debug output |
111
+| `--force` | `-f` | Skip confirmations |
112
+| `--dry-run` | `-n` | Preview only |
113
+| `--json` | | Structured output |
114
+| `--output` | `-o` | Output file path |
115
+| `--no-input` | | Disable prompts; fail if required input missing |
116
+| `--no-browser` | | Skip browser-open steps |
117
+| `--no-color` | | Disable color output |
118
+
119
+## Subcommands
120
+
121
+```typescript
122
+const login = Command.make('login', { noBrowser }, handler);
123
+const generate = Command.make('generate', { toolkits, typeTools }, handler);
124
+const root = Command.make('composio').pipe(
125
+ Command.withSubcommands([login, generate, /* ... */]),
126
+);
127
+```
128
+
129
+- Follow verb-noun pattern consistently: `composio login`, `composio generate`.
130
+- Share global flags via parent command composition.
131
+- Support `composio help <subcmd>` and `composio <subcmd> --help`.
132
+- Avoid ambiguous pairs (`update` vs `upgrade`) unless sharply differentiated.
133
+
134
+## Interactivity
135
+
136
+Use `@clack/prompts` for all interactive UI. All Clack output goes to stderr via `{ output: process.stderr }`.
137
+
138
+| Prompt | When to use |
139
+| ------ | ----------- |
140
+| `text()` | Free-form text input |
141
+| `password()` | Secret input (echo disabled) |
142
+| `confirm()` | Yes/no decisions |
143
+| `select()` | Choose one from a list |
144
+| `multiselect()` | Choose multiple from a list |
145
+| `spinner()` | Long-running operations |
146
+| `log.info/warn/error/step()` | Styled status messages |
147
+| `note()` | Boxed contextual info |
148
+| `intro()` / `outro()` | Session start/end markers |
149
+
150
+Rules:
151
+- Prompt only if stdin is a TTY.
152
+- `--no-input`: never prompt; fail with actionable message if required input missing.
153
+- Make escape hatches obvious (Ctrl-C).
154
+- Destructive operations: interactive confirmation + non-interactive requires `--force`.
155
+
156
+## Error Handling
157
+
158
+- Use the `effect-errors/` module for capture and formatting.
159
+- Catch and rewrite expected errors for humans; no stack traces by default.
160
+- Put the most important info last; use red intentionally.
161
+- For unexpected crashes: provide debug info path + bug report instructions.
162
+
163
+**Write actionable error messages.** Tell the user *what went wrong* and *how to fix it*:
164
+
165
+```
166
+// Bad:
167
+Error: EACCES
168
+
169
+// Good:
170
+Can't write to ~/.composio/user-config.json.
171
+You might need to fix permissions: chmod +w ~/.composio/user-config.json
172
+
173
+// Bad:
174
+Error: 401
175
+
176
+// Good:
177
+API key is invalid or expired.
178
+Run `composio login` to authenticate again.
179
+```
180
+
181
+**Suggest corrections** when the user mistypes a subcommand or flag. If they ran `composio genrate`, suggest `composio generate`.
182
+
183
+Exit codes:
184
+
185
+| Code | Meaning |
186
+| ---- | ------- |
187
+| `0` | Success |
188
+| `1` | Generic failure |
189
+| `2` | Invalid usage (parse/validation error) |
190
+
191
+## Help & Documentation
192
+
193
+- `@effect/cli` generates help text from Command/Options declarations.
194
+- If run with missing required args, show concise help + 1–2 examples + "use --help for more".
195
+- Lead with examples; show common flags first.
196
+- Link to docs URL per subcommand when applicable.
197
+- Provide both terminal help (offline, version-synced) and web docs (searchable, linkable).
198
+
199
+Good help text structure:
200
+
201
+```
202
+USAGE
203
+ $ composio generate [--toolkits <slugs>] [--type-tools]
204
+
205
+OPTIONS
206
+ --toolkits <slugs> Comma-separated toolkit slugs (default: all)
207
+ --type-tools Generate full type definitions
208
+ -o, --output <dir> Output directory (default: @composio/core/generated)
209
+
210
+EXAMPLES
211
+ $ composio generate
212
+ $ composio generate --toolkits github,slack --type-tools
213
+
214
+COMMANDS
215
+ composio ts generate Generate TypeScript stubs
216
+ composio py generate Generate Python stubs
217
+```
218
+
219
+**Suggest next commands** when it helps the user's flow:
220
+
221
+```
222
+✔ Logged in as user@example.com
223
+ Next: run `composio generate` to generate type stubs for your toolkits.
224
+```
225
+
226
+## Color & Formatting
227
+
228
+- Use `ansis` or `picocolors` for colored output.
229
+- Respect `NO_COLOR` env var and `TERM=dumb`.
230
+- Provide `--no-color` flag.
231
+- No animations or progress bars when stdout isn't a TTY.
232
+- Spinners only in interactive mode, always on stderr.
233
+
234
+## Configuration Precedence
235
+
236
+High to low: **flags > process env > project config > user config > system config**.
237
+
238
+- Composio prefixes: `COMPOSIO_*` for app config, `DEBUG_OVERRIDE_*` for debug.
239
+- User config stored in `~/.composio/`.
240
+- Respect common env vars: `NO_COLOR`, `DEBUG`, `EDITOR`, `PAGER`, `TERM`, `TMPDIR`, `HOME`.
241
+
242
+## Naming
243
+
244
+- Subcommand names: simple, lowercase, single word when possible.
245
+- Avoid too-generic names that collide with system tools.
246
+- Keep names short but not cryptic — easy to type matters.
247
+- Never create implicit catch-all subcommands that prevent future expansion.
248
+- Don't allow arbitrary abbreviations (reserving `g` for `generate` blocks future `g`-commands).
249
+- Use explicit aliases only when there's a clear, stable mapping.
250
+
251
+## Robustness & Performance
252
+
253
+- Validate early; fail fast with good error messages.
254
+- Print something within ~100ms (especially before network I/O). Start a Clack spinner immediately before any network call.
255
+- Show progress for long tasks (interactive only) via Clack spinners.
256
+- Use timeouts for network calls; allow configuration.
257
+- Make reruns safe: idempotent where possible; recoverable on failure.
258
+- **Crash-only design**: assume cleanup might not run. Defer cleanup to the next invocation rather than relying on shutdown hooks. If a cache file is half-written, the next run should detect and rebuild it.
259
+
260
+## Future-Proofing
261
+
262
+- Interfaces are contracts: args, flags, subcommands, env vars, output modes.
263
+- Keep changes additive; deprecate loudly + early; provide migration paths.
264
+- Human output can evolve; keep scripts stable via `--json`/`--plain`.
265
+
266
+## Signals
267
+
268
+- Ctrl-C: exit quickly; say something immediately; bounded cleanup.
269
+- Use Effect's interrupt handling (`Effect.scoped`, fiber interruption).
270
+- Design for crash-only recovery; assume cleanup might not run.
271
+
272
+## CLI Spec Template
273
+
274
+When designing a new command, produce this spec:
275
+
276
+```
277
+1. Name: `composio <subcommand>`
278
+2. One-liner: Brief description
279
+3. USAGE: `composio [global flags] <subcommand> [args]`
280
+4. Options (via @effect/cli Options.*):
281
+ - Flag table (name, type, default, required, description)
282
+5. I/O contract:
283
+ - stdout: what data is emitted
284
+ - stderr: what decoration is shown
285
+6. Exit codes: 0/1/2 + command-specific
286
+7. Env/config: COMPOSIO_* vars, ~/.composio/ files
287
+8. Examples: 5–10 invocations (interactive + piped)
288
+```
289
+
290
+## Example Invocations
291
+
292
+```bash
293
+# Interactive — user sees Clack decoration on stderr
294
+composio login
295
+composio generate --toolkits github,slack
296
+
297
+# Piped — only data on stdout, no decoration
298
+composio whoami | pbcopy
299
+API_KEY=$(composio whoami)
300
+composio version | cat
301
+
302
+# Non-interactive with force
303
+composio logout --force --no-input
304
+
305
+# Debug mode
306
+composio generate --debug --verbose
307
+```
308
+
309
+## Telemetry
310
+
311
+- Never phone home without explicit user consent.
312
+- Prefer opt-in. If opt-out, make it obvious and easy to disable (`COMPOSIO_DISABLE_TELEMETRY=true`).
313
+- Clearly explain what is collected, why, how, and retention period.
314
+- Consider alternatives: docs site analytics, download metrics, direct user feedback.
315
+
316
+## References
317
+
318
+- Community CLI Guidelines: https://clig.dev/
319
+- @effect/cli source: `ts/vendor/effect/packages/cli/src/`
320
+- @clack/prompts source: `ts/vendor/clack/packages/prompts/src/`
321
+- CLI architecture: `ts/packages/cli/AGENTS.md`
ts/packages/cli/AGENTS.md
+11
@@ -278,3 +278,14 @@ When working on CLI code, reference the Effect source for accurate patterns:
278
279
- The submodule is for **read-only reference only**. Do not modify files in `ts/vendor/effect/`.
280
- The CLI's actual dependencies come from npm via `pnpm install`.
281
+
282
+---
283
+
284
+## CLI Design Guidelines
285
+
286
+For principles on how to design CLI interactions (arguments, flags, help text, output, errors, interactivity, config precedence), see:
287
+
288
+- **Full guidelines**: `ts/packages/cli/.cursor/rules/cli-design-guidelines.mdc`
289
+- **Also available as**: `.claude/skills/create-cli/SKILL.md` (symlink)
290
+
291
+Use these guidelines when adding new commands, designing flag interfaces, or making UX decisions for the CLI.