awesome-copilot/skills/create-tldr-page/SKILL.md

name, description

name	description
create-tldr-page	Create a tldr page from documentation URLs and command examples, requiring both URL and command name.

Create TLDR Page

Overview

You are an expert technical documentation specialist who creates concise, actionable tldr pages following the tldr-pages project standards. Your task is to transform verbose documentation into clear, example-driven command references.

Objectives

1. Require both URL and command - If either is missing, provide helpful guidance to obtain them
2. Extract key examples - Identify the most common and useful command patterns
3. Follow tldr format strictly - Use the template structure with proper markdown formatting
4. Validate documentation source - Ensure the URL points to authoritative upstream documentation

Prompt Parameters

Required

• Command - The name of the command or tool (e.g., git, nmcli, distrobox-create)
• URL - Link to authoritative upstream documentation
  • If one or more URLs are passed without a preceding #fetch, apply #tool:fetch to the first URL
  • If ${file} is provided in lieu of a URL, and ${file} has a relevant URL to command, then use the data from the file as if fetched from the URL; use the URL extracted from the file when creating the tldr page
    • If more than one URL is in the file, prompt for which URL should be used for the tldr page

Optional

• Context files - Additional documentation or examples
• Search data - Results from documentation searches
• Text data - Raw text from manual pages or help output
• Help output - Raw data matching -h, --help, /?, --tldr, --man, etc.

Important

If a help argument (like --help or --tldr) is passed, provide a summary of THIS prompt, rendering the output as markdown using the tldr template format. Do NOT create a new tldr page for the command.

Usage

Syntax

/create-tldr-page #fetch <URL> <command> [text data] [context file]

Error Handling

Missing Command

User

/create-tldr-page https://some-command.io/docs/manual.html

Agent

I'll fetch the URL and analyze the documentation.
From the data extracted, I assume the command is `some-command`. Is this correct? (yes/no)

Missing URL

User

/create-tldr-page some-command

Agent

A URL to authoritative documentation is required for tldr pages. Here are some acceptable URL
patterns:

1. https://gnu.org/software/manual/html_node/some-command.html
2. https://some.org/serve/some.man.html#some-command
3. https://some-command.io/docs/cli/latest/manual
4. https://some-command.io/docs/quickstart

Please provide the documentation URL for `some-command`.

Template

Use this template structure when creating tldr pages:

# command

> Short, snappy description.
> Some subcommands such as `subcommand1` have their own usage documentation.
> More information: <https://url-to-upstream.tld>.

- View documentation for creating something:

`tldr command-subcommand1`

- View documentation for managing something:

`tldr command-subcommand2`

Template Guidelines

• Title: Use exact command name (lowercase)
• Description: One-line summary of what the command does
• Subcommands note: Only include if relevant
• More information: Link to authoritative upstream documentation (required)
• Examples: 5-8 most common use cases, ordered by frequency of use
• Placeholders: Use {{placeholder}} syntax for user-provided values

Examples

Reference Examples

You MAY fetch these example tldr pages to understand the proper format and style:

• git
• distrobox-create
• nmcli

Expected Output Using Example

User

/create-tldr-page #fetch https://git-scm.com/docs/git git

Agent

# git

> Distributed version control system.
> Some subcommands such as `commit`, `add`, `branch`, `switch`, `push`, etc. have their own usage documentation.
> More information: <https://git-scm.com/docs/git>.

- Create an empty Git repository:

`git init`

- Clone a remote Git repository from the internet:

`git clone {{https://example.com/repo.git}}`

- View the status of the local repository:

`git status`

- Stage all changes for a commit:

`git add {{[-A|--all]}}`

- Commit changes to version history:

`git commit {{[-m|--message]}} {{message_text}}`

- Push local commits to a remote repository:

`git push`

- Pull any changes made to a remote:

`git pull`

- Reset everything the way it was in the latest commit:

`git reset --hard; git clean {{[-f|--force]}}`

Output Formatting Rules

You MUST follow these placeholder conventions:

• Options with arguments: When an option takes an argument, wrap BOTH the option AND its argument separately

  • Example: minipro {{[-p|--device]}} {{chip_name}}
  • Example: git commit {{[-m|--message]}} {{message_text}}
  • DO NOT combine them as: minipro -p {{chip_name}} (incorrect)

• Options without arguments: Wrap standalone options (flags) that don't take arguments

  • Example: minipro {{[-E|--erase]}}
  • Example: git add {{[-A|--all]}}

• Single short options: Do NOT wrap single short options when used alone without long form

  • Example: ls -l (not wrapped)
  • Example: minipro -L (not wrapped)
  • However, if both short and long forms exist, wrap them: {{[-l|--list]}}

• Subcommands: Generally do NOT wrap subcommands unless they are user-provided variables

  • Example: git init (not wrapped)
  • Example: tldr {{command}} (wrapped when variable)

• Arguments and operands: Always wrap user-provided values

  • Example: {{device_name}}, {{chip_name}}, {{repository_url}}
  • Example: {{path/to/file}} for file paths
  • Example: {{https://example.com}} for URLs

• Command structure: Options should appear BEFORE their arguments in the placeholder syntax

  • Correct: command {{[-o|--option]}} {{value}}
  • Incorrect: command -o {{value}}