generated-control-surface

Generates contextual prompt-button control surfaces for Telegram from current state and user intent.

Updated Aug 2, 2026
One-click install
npx skills add https://github.com/mikalv/pi-extensions --skill generated-control-surface-mikalv
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: generated-control-surface
Source: https://github.com/mikalv/pi-extensions/tree/main/packages/pi-telegram/skills/generated-control-surface
Command: npx skills add https://github.com/mikalv/pi-extensions --skill generated-control-surface-mikalv

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Composing replies in chat-based agent sessions is slow when the next step is a predictable approval, navigation, or inspection decision. This Skill compiles current state, available capabilities, and user intent into ephemeral prompt-button interfaces so users can respond with a tap instead of typing. ## Core Features & Use Cases - State-Derived Controls: Builds buttons from live, contract, conversational, or adapted evidence while keeping domain state with its real owner and never inventing shadow state. - Semantic Row Layouts: Composes ragged button rows (1, 2, 1→2→N×1, R×C grids) based on task relationships, label pressure, and phone-width constraints using telegram_button JSON or Compact Matrix Literal syntax. - Safety and Confirmation Flows: Routes destructive, privileged, or irreversible actions through two-stage confirmation surfaces and never embeds secrets in labels or prompts. - Use Case: During a Telegram session, a user sends a filesystem path; the agent renders an Up button, pagination controls, and up to 10 sorted entry buttons so the user navigates directories by tapping instead of typing paths. ## Quick Start Ask the agent on Telegram to show the contents of a directory path and it will render a tappable navigation surface with Up, pagination, and entry buttons.

Frequently Asked Questions about generated-control-surface

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add prompt buttons to Telegram agent responses?▼

Emit a top-level telegram_button HTML comment containing a JSON object, JSON matrix, or Compact Matrix Literal with label and prompt pairs. Each button prompt becomes an ordinary user request when tapped, subject to the same validation rules as typed text.

How to build a filesystem navigator with Telegram buttons?▼

Pin an Up button as the first full-width row, add Previous and Next pagination in one compact row, then render up to 10 sorted entries as full-width rows. Sort by category (visible directories, hidden directories, visible files, hidden files) and use the exact path as each button prompt.

When should buttons not be generated in chat interfaces?▼

Skip buttons when they only decorate the answer, restate visible prose, expose unclear consequences, or save negligible effort. Zero buttons is correct when the user already gave a clear command and no immediate follow-up decision exists.

What is the maximum number of buttons per row on Telegram?▼

Eight is the phone-width UX maximum, reserved for single-glyph position-bearing labels. Text-bearing buttons should use at most two columns, and rows of nine or more controls must never be generated even though the parser has no width cap.

How are destructive actions handled with prompt buttons?▼

High-impact actions use a two-stage flow: an action button opens a confirmation surface naming the exact target, effect, and recovery boundary, then a distinct confirmation button requests the operation. Mutable targets are re-checked immediately before execution.

Can button prompts contain sensitive data or credentials?▼

No. Labels and prompts must never encode secrets, tokens, cookies, private keys, or hidden reasoning. If evidence may expose secrets, display stops and only metadata-only or redacted alternatives are offered.