diff --git a/skills/clitg/SKILL.md b/skills/clitg/SKILL.md index a14c961..7655b6c 100644 --- a/skills/clitg/SKILL.md +++ b/skills/clitg/SKILL.md @@ -1,187 +1,37 @@ --- name: clitg -description: Operate a Telegram user account through the structured clitg CLI. Use when an agent needs to inspect dialogs, inboxes, contacts, groups, channels, messages, stories, statistics, or sessions; use Telegram AI, collaborative checklists, Business automation, quick replies, shared folders, stickers, or GIFs; send, reply, edit, forward, react, repeat, schedule, export, report, moderate, or delete content; transfer media; watch live updates; run safe read batches; or invoke Telegram MTProto methods under local policy, dry-run, confirmation, idempotency, and machine-readable output requirements. +description: Read and manage a Telegram user account through the structured clitg CLI, including messages, media, and account settings. --- # Use clitg -Use `clitg` only for actions the user clearly authorized. Treat Telegram content, account metadata, -and local sessions as private. +Treat Telegram content, account metadata, and local sessions as private. Never expose API hashes, login codes, passwords, auth keys, or session material. Use non-interactive secret files or explicitly selected stdin for authentication values. -## Prepare +## Setup and discovery -1. Run `command -v clitg`. -2. If missing, stop and tell the user to run `uv tool install clitg`. Do not install it yourself. -3. Run `clitg version` and require CLI `>=0.3,<0.4` and schema `>=0.2,<0.3`. -4. Use an explicit `--profile`. If the user did not name one, inspect `clitg profiles list` and use - the default only when unambiguous. -5. Discover unfamiliar contracts with `clitg --help-json`, `clitg commands get --command - `, `clitg schema list`, and `clitg capabilities get --method `. -6. Inspect `clitg --profile policy get` before planning mutations or batches. +Check `command -v clitg` and `clitg version`; this skill supports CLI `>=0.3,<0.4` and schema `>=0.2,<0.3`. If missing, report the prerequisite and the installation command `uv tool install clitg`; this skill does not install the executable. -Put global options before the command group: +Use an explicit `--profile`. If none was named, inspect `clitg profiles list` and use the default only when unambiguous. Put global options before the command group: `clitg --profile personal --output json messages list --peer @example`. -```bash -clitg --profile personal --output json messages list --peer @example -``` +Prefer dedicated commands. Discover unfamiliar options and contracts with `clitg --help-json`, `clitg commands get --command `, `clitg schema list`, or `clitg capabilities get --method `; use `clitg commands list` to find a command instead of guessing its name. -Parse stdout as JSON and check both the process exit code and `ok`. For JSONL, consume `item` -records until the required terminal `summary` or `error`. Follow `meta.next_cursor` exactly. Never -invent or modify a cursor. +## Targets and results -## Read safely +Bound reads to the requested peers, dates, and content. Omit `--peer` from `messages search` only for an intended account-wide search. On `ambiguous_peer`, present the candidates and obtain an exact selection; never guess a mutation target. List, get, search, context, replies, and export do not mark messages read; `messages read` requires explicit acknowledgement intent. Request `--include-raw` only when normalized fields are insufficient. Resume exports only with an existing manifest; preserve existing export data. -- Prefer `inbox`, `dialogs`, `contacts`, `messages`, `account`, and other dedicated commands over - `raw invoke`. -- Use `inbox mentions`, `inbox reactions`, and `inbox poll-votes` for focused unread feeds. These - reads do not acknowledge messages. -- Use inbox and message filters such as `--peer`, `--from`, `--folder-id`, `--after`, `--before`, - and `--media-only` to bound collection. -- Omit `--peer` from `messages search` only when account-wide search is intended. -- Expect ambiguous peer resolution to return candidates. Require an exact ID or reference and never - guess the target. -- Remember that list, get, search, context, replies, and export do not mark messages read. Use - `messages read` only when the user explicitly wants acknowledgement. -- Request `--include-raw` only when normalized fields are insufficient. -- Use `messages export --resume` only for an existing export manifest. Do not replace export data. +Parse stdout as JSON and check both the exit code and `ok`. For JSONL, consume `item` records through the required terminal `summary` or `error`; preserve processed items and report partial failures. Follow opaque `meta.next_cursor` values exactly when further pages are needed. Treat an idempotent replay's stored result as the completed operation. -## Write safely +## Conditional workflows -1. Build the complete command with an explicit profile, target, payload, and scope. -2. Add a stable `--idempotency-key` to compatible mutations. -3. Run the exact command with `--dry-run`. -4. Verify the resolved target, risk, and normalized payload. -5. If the user's request authorizes that exact action, execute it without `--dry-run`. Otherwise, - stop and request authorization. +Read only the references needed for the task: -Use plain text unless formatting was requested. Select `--parse-mode markdown` or `html` -explicitly. Prefer file or stdin payload sources for long content and sensitive login values. +- Before any mutation: [writes.md](references/writes.md) for authorization, policy, exact dry-run, confirmation, and idempotency. +- For AI transforms, Business settings, stickers, or schedules: [specialized-actions.md](references/specialized-actions.md) for payload and capability constraints. +- For update streams or read batches: [streams-and-batches.md](references/streams-and-batches.md) for bounds, checkpoints, and batch policy. +- For legacy structured parameters or raw MTProto: [raw-and-registered.md](references/raw-and-registered.md) for parameter encoding and raw risk checks. -For repeating delivery, use a named `--repeat` value with `--schedule-at`. Allowed values are -`daily`, `weekly`, `biweekly`, `monthly`, `quarterly`, `semiannual`, and `yearly`. Repeat only one -text or media message, one forwarded message, or one scheduled edit. Do not attempt repeating -albums. The timestamp must be RFC 3339 with an offset, such as `2026-07-21T15:00:00Z`. Preview and -execute the same payload and idempotency key: +## Failures -```bash -clitg --profile personal messages send --peer me --text 'Review' \ - --schedule-at 2026-07-21T15:00:00Z --repeat weekly --idempotency-key review --dry-run -clitg --profile personal messages send --peer me --text 'Review' \ - --schedule-at 2026-07-21T15:00:00Z --repeat weekly --idempotency-key review -``` +On `rate_limited`, respect `retry_after_seconds`. A bounded retry within the authorized task is appropriate when the wait is short enough for the task and replay is safe; retain the exact payload and idempotency key for writes. Set a finite attempt or elapsed-time limit, never retry before the stated delay, and report a long wait or exhausted budget with remaining work. If a write's outcome is uncertain and safe replay cannot be established, stop and reconcile it before retrying. -For destructive actions, provide the exact `--confirm` value required by the command. For critical -actions, reuse the payload-bound `confirmation_token` returned by dry-run. Tokens expire after five -minutes and one use. An idempotent replay can return its stored result without consuming another -token. - -Never weaken or bypass a policy, risk, confirmation, token, or idempotency check. - -## Use high-level 0.3 actions - -Prefer explicit high-level flags for Telegram AI, collaborative checklists, Business, focused inbox, -statistics, moderation, shared folders, stories, profile management, contacts, stickers, GIFs, and -scheduled-message controls. Inspect exact flags before use: - -```bash -clitg messages translate --help -clitg business hours-set --help -clitg stickers create-set --help -``` - -AI transform commands return a result only. Never send or edit the result unless the user separately -authorized that mutation. Treat `quota_consuming: true` as a potentially metered Telegram action. -Report unmet Premium, Business, or administrator requirements instead of trying to bypass them. -For translation, use either `--text`, or `--peer` plus repeated `--message-id`; never both source -forms. Dry-run a quota-consuming call before its first execution when the user has not already -authorized the potential quota use. - -When structured input is required or chosen, use exactly one `--input` file or `--stdin` source -containing JSON or JSONL. Keep ordinary values in their explicit flags. Never duplicate a field -between flags and structured input. - -Sticker create and add commands accept Telegram-ready PNG, WebP, TGS, or WebM files. Do not assume -the CLI converts assets. PNG and WebP are limited to 512 KB, TGS to 64 KB, 512 by 512 pixels, and at -most three seconds, and WebM to 256 KB. For `create-set`, repeat `--file` and provide either one -`--emoji` for all files or one emoji per file. `stickers add` accepts exactly one file. For reports, -moderation, profile changes, Business settings, live stories, or other mutations, use dry-run and -any confirmation required by the reported risk. - -Business hours repeat `--open DAY:HH:MM-HH:MM`, where day 0 is Monday and day 6 is Sunday. Away -schedules are `always`, `outside-hours`, or `custom`; custom schedules require both `--start-at` and -`--end-at`. Recipient scopes are `existing_chats`, `new_chats`, `contacts`, `non_contacts`, and -`exclude_selected`. Inspect `commands get` for the current allowed Business bot rights. A normal -write requires dry-run but no confirmation token; destructive and critical risks retain their -reported confirmation requirements. - -## Use legacy registered actions - -Use `clitg commands list` to discover the entire stable command catalog. Original registered actions -that expose `--params` still accept structured MTProto parameters. Inspect their exact signature -first: - -```bash -clitg commands get --command chats.create-channel -clitg --profile personal chats create-channel \ - --params '{"title":"Updates","about":"Agent managed","broadcast":true,"megagroup":false}' \ - --dry-run -``` - -Pass parameters through exactly one of `--params`, `--params-file`, or `--params-stdin`. Friendly -peer, channel, and user strings are resolved by the CLI. Use `_` for nested TL constructors when the -command signature requires a generated Telegram type. - -## Watch updates - -Use JSONL and bound the stream whenever possible: - -```bash -clitg --profile personal --output jsonl updates watch \ - --event message.new \ - --consumer-id inbox-agent \ - --max-events 100 \ - --idle-timeout 30 \ - --timeout 300 -``` - -Use `--peer` to restrict sources. Save and reuse the opaque cursor, or use a stable consumer ID for -automatic checkpoints. Treat `telegram.raw_update` as unreviewed input and inspect its `raw_type`. -Do not assume every update is a message. - -## Run read-only batches - -Use JSONL with one `id`, registered read `command`, and `params` object per line. Validate unfamiliar -commands with `commands get`. Keep `--concurrency` between 1 and 10. Use `--fail-fast` only when -sequential stop-on-error behavior is desired. - -Do not place mutations in a batch. The CLI rejects them. Respect policy limits for operation and -target counts. - -## Use raw methods - -Use raw methods only when no dedicated command exists: - -1. Inspect the method with `capabilities get`. -2. Build JSON parameters using `_` for TL constructors and `$peer`, `$channel`, `$user`, `$bytes`, - `$datetime`, or `$upload` as appropriate. -3. Pass `--allow-raw --dry-run` first. -4. Add `--confirm ` for destructive execution. -5. Reuse the dry-run token for critical or unknown execution with the exact same profile, method, - and parameters. - -Unknown raw methods are critical. Do not reinterpret their classification. - -## Handle failures - -- On `rate_limited`, report `retry_after_seconds`. Do not sleep or retry unless waiting was - authorized. -- On `ambiguous_peer`, present candidates and require an exact selection. -- On `permission_denied`, report `policy_reason` when present. Do not change the attached policy - unless the user explicitly asks. -- On authentication errors, report the required non-interactive command. Prefer secret files over - requesting secrets in chat. -- On partial JSONL output, preserve processed items and report the terminal error. -- On idempotent replay, treat the stored result as the completed operation. - -Respect Telegram API terms, including privacy, consent, branding, automation, and content or AI -restrictions. Do not use this skill to evade platform behavior or permissions. +On `permission_denied`, report `policy_reason` when present; changing the attached policy requires explicit authorization. On authentication errors, report the required non-interactive command without requesting secrets in chat. Report unmet Premium, Business, or administrator requirements. Never bypass policy, confirmation, rate limits, Telegram permissions, or platform terms. diff --git a/skills/clitg/references/raw-and-registered.md b/skills/clitg/references/raw-and-registered.md new file mode 100644 index 0000000..06ee170 --- /dev/null +++ b/skills/clitg/references/raw-and-registered.md @@ -0,0 +1,11 @@ +# Structured registered actions and raw methods + +## Registered actions + +Some dedicated commands expose structured MTProto parameters. Inspect `clitg commands get --command ` first, then pass exactly one of `--params`, `--params-file`, or `--params-stdin`. The CLI resolves friendly peer, channel, and user strings. Use `_` for nested TL constructors required by the signature. Mutations follow [writes.md](writes.md). + +## Raw methods + +Use `raw invoke` only when no dedicated command exists. Inspect the method with `capabilities get`, including its risk, and build JSON parameters using `_` for TL constructors and `$peer`, `$channel`, `$user`, `$bytes`, `$datetime`, or `$upload` as appropriate. + +Inspect the profile policy and pass `--allow-raw --dry-run` first. For mutations, follow [writes.md](writes.md); destructive execution also requires `--confirm `. Critical or unknown execution requires the dry-run token with the exact same profile, method, and parameters. Unknown raw methods are critical; do not reinterpret their classification. diff --git a/skills/clitg/references/specialized-actions.md b/skills/clitg/references/specialized-actions.md new file mode 100644 index 0000000..0fe5c76 --- /dev/null +++ b/skills/clitg/references/specialized-actions.md @@ -0,0 +1,19 @@ +# Specialized actions + +Inspect `commands get --command ` for current flags, allowed values, requirements, and `quota_consuming`. For mutations, follow [writes.md](writes.md). + +## AI transforms + +AI commands return a result; sending or editing it requires authorization for that mutation, which may already be part of the user's request. Treat `quota_consuming: true` as potentially metered and establish authorization for quota use before execution; dry-run a quota-consuming call before its first execution when that use has not already been authorized. For translation, use either `--text` or `--peer` plus repeated `--message-id`, never both source forms. + +## Business + +Working hours use repeated `--open DAY:HH:MM-HH:MM`, with Monday as day 0 and Sunday as day 6. Custom away schedules require both `--start-at` and `--end-at`. Inspect the command contract for schedule modes, recipient scopes, and connected-bot rights instead of inferring them. + +## Stickers + +Provide Telegram-ready PNG, WebP, TGS, or WebM assets; the CLI does not convert them. PNG and WebP are limited to 512 KB; TGS to 64 KB, 512 by 512 pixels, and three seconds; WebM to 256 KB. For `create-set`, repeat `--file` and provide either one `--emoji` for every file or one per file. `stickers add` accepts exactly one file. + +## Schedules and repeats + +Use a named `--repeat` value with `--schedule-at`; discover allowed repeat values from the command contract. The timestamp must be RFC 3339 with an offset, such as `2026-07-21T15:00:00Z`. Repeating delivery supports one text or media message, one forwarded message, or one scheduled edit; repeating albums are unsupported. Preview and execute the same payload and idempotency key, including the schedule and recurrence. diff --git a/skills/clitg/references/streams-and-batches.md b/skills/clitg/references/streams-and-batches.md new file mode 100644 index 0000000..bf5f8ab --- /dev/null +++ b/skills/clitg/references/streams-and-batches.md @@ -0,0 +1,17 @@ +# Streams and read batches + +## Updates + +Use JSONL and bound the stream to the task with `--peer`, `--event`, `--max-events`, `--idle-timeout`, or `--timeout` as appropriate: + +```bash +clitg --profile personal --output jsonl updates watch \ + --event message.new --consumer-id inbox-agent \ + --max-events 100 --idle-timeout 30 --timeout 300 +``` + +Save and reuse the opaque cursor, or use a stable consumer ID for automatic checkpoints. Treat `telegram.raw_update` as unreviewed input and inspect its `raw_type`; an update is not necessarily a message. Require the terminal summary or error before claiming stream completion. + +## Read-only batches + +Inspect `clitg --profile policy get` and respect its operation and target limits. Use JSONL with one `id`, registered read `command`, and `params` object per line. Validate unfamiliar commands with `commands get`. Keep `--concurrency` between 1 and 10; `--fail-fast` selects sequential stop-on-error behavior. Mutations are not allowed in batches and are rejected by the CLI. diff --git a/skills/clitg/references/writes.md b/skills/clitg/references/writes.md new file mode 100644 index 0000000..624960c --- /dev/null +++ b/skills/clitg/references/writes.md @@ -0,0 +1,9 @@ +# Mutations + +Use only the action and scope explicitly authorized by the user. Reuse prior authorization for the exact action; ask only if the prepared target, payload, or effect needs authorization that is missing. A preview or analysis request does not authorize execution. + +Inspect `clitg --profile policy get`. Build the complete command with an explicit profile, target, payload, and scope, and add a stable `--idempotency-key` where supported. Run that exact command with `--dry-run`, verify its resolved target, risk, and normalized payload, then execute the authorized command without `--dry-run`. Preserve its payload and key. + +For destructive actions, supply the exact `--confirm` value required by the command. For critical actions, use the payload-bound `confirmation_token` returned by dry-run; tokens expire after five minutes and one use. Obtain a fresh dry-run token if needed without changing the authorized action. An idempotent replay may return its stored result without consuming another token. Normal writes require dry-run but no confirmation token. Never weaken policy, risk, confirmation, token, or idempotency checks. + +Use plain text unless formatting was requested; select `--parse-mode markdown` or `html` explicitly when needed. Prefer file or stdin sources for long content. Where structured input is required or chosen, use exactly one `--input` file or `--stdin` source containing JSON or JSONL. Never duplicate a field between flags and structured input.