Create Tldr Page

---
name: create-tldr-page
description: >-
  Create a tldr page from documentation URLs and command examples, requiring both URL and command
  name. Use this skill when the user asks to generate a concise tldr-pages style command reference
  from official docs and examples.
---

<!-- Generated from harness/github-copilot/plugins/repo-documentation/skills/create-tldr-page/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->

# Create TLDR page

Create a concise tldr-pages style command reference from an authoritative documentation URL, a command name, and any supplied help text or examples; return a markdown page with validated placeholders and common use cases.

## When to invoke

- "Create a tldr page for this command from the docs URL."
- "Generate a concise command reference from this manual page."
- "Turn this --help output and upstream URL into a tldr page."
- "Write a tldr-pages style page for git from https://git-scm.com/docs/git."

## 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

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

### Error Handling

#### Missing Command

**User**

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

**Agent**

```text
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**

```bash
/create-tldr-page some-command
```

**Agent**

```text
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:

```markdown
# 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](https://raw.githubusercontent.com/jhauga/tldr/refs/heads/main/pages/common/git.md)
* [distrobox-create](https://raw.githubusercontent.com/jhauga/tldr/refs/heads/main/pages/linux/distrobox-create.md)
* [nmcli](https://raw.githubusercontent.com/jhauga/tldr/refs/heads/main/pages/linux/nmcli.md)

### Expected Output Using Example

**User**

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

**Agent**

````markdown
# 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}}`

## Output template

```markdown
# {{command}}

> {{short_snappy_description}}
> {{optional_subcommands_note}}
> More information: <{{authoritative_url}}>.

- {{common task description}}:

`{{command}} {{[-o|--option]}} {{value}}`

- {{another common task description}}:

`{{command}} {{subcommand}} {{argument}}`
```

## Quality gate

- [ ] Both command name and authoritative URL are present or the response asks for the missing item.
- [ ] The page uses exact tldr markdown style: H1, quote description, More information URL, and example bullets.
- [ ] The examples are the 5-8 most common user tasks and are ordered by practical frequency.
- [ ] Every user-supplied operand uses `{{placeholder}}` syntax.
- [ ] Option placeholders follow the separate option/value rules in this skill.

## References

- https://git-scm.com/docs/git
- https://raw.githubusercontent.com/jhauga/tldr/refs/heads/main/pages/common/git.md
- https://raw.githubusercontent.com/jhauga/tldr/refs/heads/main/pages/linux/distrobox-create.md
- https://raw.githubusercontent.com/jhauga/tldr/refs/heads/main/pages/linux/nmcli.md