Skip to content

Add skills/ documentation folder (usage guide + example workflows) #52

@chigwell

Description

@chigwell

Create skills/ folder with MCP server usage guide and practical Telegram automation examples (summarize unread, draft replies without sending, etc.)

As a developer or agent integrator, 
I would like a dedicated `skills/` documentation folder that explains how to use the `telegram-mcp` server 
and provides concrete example workflows 
(e.g., summarize latest unread messages and draft responses without sending) 
so that I can reliably adopt the server capabilities with minimal trial-and-error.

Background

The repository provides a Telegram MCP server but lacks a centralized, “skill-oriented” documentation set that:

  • explains end-to-end usage (setup, configuration, connecting an MCP client, and typical call patterns), and
  • offers ready-to-copy examples for common user workflows (summarization, drafting replies, triage, etc.), including safe patterns such as drafting responses without sending messages.

Adding a skills/ folder with standardized skill descriptions will improve onboarding, reduce integration friction, and provide canonical examples for agents.

Scope

Create a new folder containing skill-style markdown documents:

  1. one primary guide describing how to use this MCP server, and
  2. one or more example skill documents describing common use cases (including “draft but do not send”).

Proposed Folder Structure

  • skills/
    • README.md (index + quick navigation)
    • how-to-use-telegram-mcp.md (main “how to use” guide)
    • examples/
      • summarize-latest-unread.md
      • draft-replies-without-sending.md
      • triage-and-action-items.md (optional but recommended)
      • search-chat-and-summarize-context.md (optional but recommended)

Documentation Template (to apply per skill doc)

Each skill document must include:

  • Skill Name
  • Purpose
  • When to Use / Use Cases
  • Prerequisites / Configuration
  • MCP Tools Used (tool names + parameters + notes)
  • Inputs (what the agent/user provides)
  • Outputs (what the agent returns)
  • Step-by-step Example (prompt → tool calls → response)
  • Safety / Privacy Notes
  • Failure Modes & Recovery (e.g., auth expired, rate limit, missing chat id)

Acceptance Criteria

  • A new skills/ folder exists at the repository root.
  • skills/README.md provides:
    • a brief overview of what “skills” are in this repo,
    • links to the main guide and each example,
    • a short “pick a workflow” list (e.g., summarize unread, draft replies, triage).
  • skills/how-to-use-telegram-mcp.md includes, at minimum:
    • installation/run instructions consistent with the repo’s existing setup,
    • required configuration/env vars and where to place them,
    • how to connect a generic MCP client to this server,
    • a concise “capabilities overview” (what the server can/can’t do),
    • security/privacy guidance (e.g., sensitive chats, token handling).
  • skills/examples/summarize-latest-unread.md includes:
    • a workflow that fetches or identifies “latest unread messages,”
    • a summary output format (e.g., bullets + per-chat highlights),
    • clear assumptions/limitations if “unread” requires additional state.
  • skills/examples/draft-replies-without-sending.md includes:
    • an explicit “do not send” rule in the workflow,
    • drafted replies returned as text only (no send tool invocation),
    • an example showing how to reference message context when drafting.
  • All skill docs follow the shared template (sections listed above).
  • Root README.md (or equivalent primary docs entrypoint) links to skills/.
  • Markdown formatting is clean and consistent (headings, code blocks, lists, links).
  • Examples are “copy/paste-ready” for an agent integrator (clear prompts and expected outputs).

Implementation Notes

  • This issue is documentation-focused. No server behavior changes are required unless the current toolset lacks a safe way to support the documented examples (in which case, document the limitation and file a follow-up issue).
  • For the “draft replies without sending” example, ensure the steps explicitly avoid any tool/action that transmits messages. The example should return drafts for user review only.

Definition of Done

The skills/ folder is merged with the main usage guide and at least two example skill documents (summarize unread; draft without sending), referenced from the root documentation entrypoint, and written in a consistent, actionable format.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions