diff --git a/docs/README.prompts.md b/docs/README.prompts.md index 464a25d7..fc04ef61 100644 --- a/docs/README.prompts.md +++ b/docs/README.prompts.md @@ -51,6 +51,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi | [Create Spring Boot Java project prompt](../prompts/create-spring-boot-java-project.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-spring-boot-java-project.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-spring-boot-java-project.prompt.md) | Create Spring Boot Java Project Skeleton | | [Create Spring Boot Kotlin project prompt](../prompts/create-spring-boot-kotlin-project.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-spring-boot-kotlin-project.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-spring-boot-kotlin-project.prompt.md) | Create Spring Boot Kotlin Project Skeleton | | [Create Technical Spike Document](../prompts/create-technical-spike.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-technical-spike.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-technical-spike.prompt.md) | Create time-boxed technical spike documents for researching and resolving critical development decisions before implementation. | +| [Create TLDR Page](../prompts/create-tldr-page.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-tldr-page.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-tldr-page.prompt.md) | Create a tldr page from documentation URLs and command examples, requiring both URL and command name. | | [Diátaxis Documentation Expert](../prompts/documentation-writer.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdocumentation-writer.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdocumentation-writer.prompt.md) | Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework. | | [EditorConfig Expert](../prompts/editorconfig.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Feditorconfig.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Feditorconfig.prompt.md) | Generates a comprehensive and best-practice-oriented .editorconfig file based on project analysis and user preferences. | | [Entity Framework Core Best Practices](../prompts/ef-core.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fef-core.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fef-core.prompt.md) | Get best practices for Entity Framework Core | diff --git a/prompts/create-tldr-page.prompt.md b/prompts/create-tldr-page.prompt.md new file mode 100644 index 00000000..03a0f93f --- /dev/null +++ b/prompts/create-tldr-page.prompt.md @@ -0,0 +1,211 @@ +--- +agent: 'agent' +description: 'Create a tldr page from documentation URLs and command examples, requiring both URL and command name.' +tools: ['edit/createFile', 'fetch'] +--- + +# 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 + +```bash +/create-tldr-page #fetch [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: . + +- 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: . + +- 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}}`