Skip to content

docs: streamline clitg skill with focused references #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
leynier merged 1 commit into from
Sep 11, 2026
Merged

docs: streamline clitg skill with focused references #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
186 changes: 18 additions & 168 deletions skills/clitg/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
<group.command>`, `clitg schema list`, and `clitg capabilities get --method <method>`.
6. Inspect `clitg --profile <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 <group.command>`, `clitg schema list`, or `clitg capabilities get --method <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 <method>` 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.
11 changes: 11 additions & 0 deletions skills/clitg/references/raw-and-registered.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Structured registered actions and raw methods

## Registered actions

Some dedicated commands expose structured MTProto parameters. Inspect `clitg commands get --command <group.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 <method>`. 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.
19 changes: 19 additions & 0 deletions skills/clitg/references/specialized-actions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Specialized actions

Inspect `commands get --command <group.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.
17 changes: 17 additions & 0 deletions skills/clitg/references/streams-and-batches.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <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.
9 changes: 9 additions & 0 deletions skills/clitg/references/writes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <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.
Loading