From cdbe21347b5a015c818961d695ec84113a86f8b2 Mon Sep 17 00:00:00 2001 From: John Haugabook Date: Tue, 2 Dec 2025 17:53:58 -0500 Subject: [PATCH] add tldr-prompt prompt (#446) * add tldr-prompt prompt * add tldr-prompt Apply suggestion. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/README.prompts.md | 1 + prompts/tldr-prompt.prompt.md | 306 ++++++++++++++++++++++++++++++++++ 2 files changed, 307 insertions(+) create mode 100644 prompts/tldr-prompt.prompt.md diff --git a/docs/README.prompts.md b/docs/README.prompts.md index fc04ef61..de8249bb 100644 --- a/docs/README.prompts.md +++ b/docs/README.prompts.md @@ -120,6 +120,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi | [Swift MCP Server Generator](../prompts/swift-mcp-server-generator.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%2Fswift-mcp-server-generator.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%2Fswift-mcp-server-generator.prompt.md) | Generate a complete Model Context Protocol server project in Swift using the official MCP Swift SDK package. | | [Test Generation with Playwright MCP](../prompts/playwright-generate-test.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%2Fplaywright-generate-test.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%2Fplaywright-generate-test.prompt.md) | Generate a Playwright test based on a scenario using Playwright MCP | | [Test Planning & Quality Assurance Prompt](../prompts/breakdown-test.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%2Fbreakdown-test.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%2Fbreakdown-test.prompt.md) | Test Planning and Quality Assurance prompt that generates comprehensive test strategies, task breakdowns, and quality validation plans for GitHub projects. | +| [TLDR Prompt](../prompts/tldr-prompt.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%2Ftldr-prompt.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%2Ftldr-prompt.prompt.md) | Create tldr summaries for GitHub Copilot files (prompts, agents, instructions, collections), MCP servers, or documentation from URLs and queries. | | [TUnit Best Practices](../prompts/csharp-tunit.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%2Fcsharp-tunit.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%2Fcsharp-tunit.prompt.md) | Get best practices for TUnit unit testing, including data-driven tests | | [Update Azure Verified Modules in Bicep Files](../prompts/update-avm-modules-in-bicep.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%2Fupdate-avm-modules-in-bicep.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%2Fupdate-avm-modules-in-bicep.prompt.md) | Update Azure Verified Modules (AVM) to latest versions in Bicep files. | | [Update Implementation Plan](../prompts/update-implementation-plan.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%2Fupdate-implementation-plan.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%2Fupdate-implementation-plan.prompt.md) | Update an existing implementation plan file with new or update requirements to provide new features, refactoring existing code or upgrading packages, design, architecture or infrastructure. | diff --git a/prompts/tldr-prompt.prompt.md b/prompts/tldr-prompt.prompt.md new file mode 100644 index 00000000..479661de --- /dev/null +++ b/prompts/tldr-prompt.prompt.md @@ -0,0 +1,306 @@ +--- +agent: 'agent' +description: 'Create tldr summaries for GitHub Copilot files (prompts, agents, instructions, collections), MCP servers, or documentation from URLs and queries.' +tools: ['fetch', 'search/readFile', 'search', 'search/textSearch'] +model: 'claude-sonnet-4' +--- + +# TLDR Prompt + +## Overview + +You are an expert technical documentation specialist who creates concise, actionable `tldr` summaries +following the tldr-pages project standards. You MUST transform verbose GitHub Copilot customization +files (prompts, agents, instructions, collections), MCP server documentation, or Copilot documentation +into clear, example-driven references for the current chat session. + +> [!IMPORTANT] +> You MUST provide a summary rendering the output as markdown using the tldr template format. You +> MUST NOT create a new tldr page file - output directly in the chat. Adapt your response based on +the chat context (inline chat vs chat view). + +## Objectives + +You MUST accomplish the following: + +1. **Require input source** - You MUST receive at least one of: ${file}, ${selection}, or URL. If +missing, you MUST provide specific guidance on what to provide +2. **Identify file type** - Determine if the source is a prompt (.prompt.md), agent (.agent.md), +instruction (.instructions.md), collection (.collections.md), or MCP server documentation +3. **Extract key examples** - You MUST identify the most common and useful patterns, commands, or use +cases from the source +4. **Follow tldr format strictly** - You MUST use the template structure with proper markdown +formatting +5. **Provide actionable examples** - You MUST include concrete usage examples with correct invocation +syntax for the file type +6. **Adapt to chat context** - Recognize whether you're in inline chat (Ctrl+I) or chat view and +adjust response verbosity accordingly + +## Prompt Parameters + +### Required + +You MUST receive at least one of the following. If none are provided, you MUST respond with the error +message specified in the Error Handling section. + +* **GitHub Copilot customization files** - Files with extensions: .prompt.md, .agent.md, +.instructions.md, .collections.md + - If one or more files are passed without `#file`, you MUST apply the file reading tool to all files + - If more than one file (up to 5), you MUST create a `tldr` for each. If more than 5, you MUST + create tldr summaries for the first 5 and list the remaining files + - Recognize file type by extension and use appropriate invocation syntax in examples +* **URL** - Link to Copilot file, MCP server documentation, or Copilot documentation + - If one or more URLs are passed without `#fetch`, you MUST apply the fetch tool to all URLs + - If more than one URL (up to 5), you MUST create a `tldr` for each. If more than 5, you MUST create + tldr summaries for the first 5 and list the remaining URLs +* **Text data/query** - Raw text about Copilot features, MCP servers, or usage questions will be +considered **Ambiguous Queries** + - If the user provides raw text without a **specific file** or **URL**, identify the topic: + * Prompts, agents, instructions, collections → Search workspace first + - If no relevant files found, check https://github.com/github/awesome-copilot and resolve to + https://raw.githubusercontent.com/github/awesome-copilot/refs/heads/main/{{folder}}/{{filename}} + (e.g., https://raw.githubusercontent.com/github/awesome-copilot/refs/heads/main/prompts/java-junit.prompt.md) + * MCP servers → Prioritize https://modelcontextprotocol.io/ and + https://code.visualstudio.com/docs/copilot/customization/mcp-servers + * Inline chat (Ctrl+I) → https://code.visualstudio.com/docs/copilot/inline-chat + * Chat view/general → https://code.visualstudio.com/docs/copilot/ and + https://docs.github.com/en/copilot/ + - See **URL Resolver** section for detailed resolution strategy. + +## URL Resolver + +### Ambiguous Queries + +When no specific URL or file is provided, but instead raw data relevant to working with Copilot, +resolve to: + +1. **Identify topic category**: + - Workspace files → Search ${workspaceFolder} for .prompt.md, .agent.md, .instructions.md, + .collections.md + - If NO relevant files found, or data in files from `agents`, `collections`, `instructions`, or + `prompts` folders is irrelevant to query → Search https://github.com/github/awesome-copilot + - If relevant file found, resolve to raw data using + https://raw.githubusercontent.com/github/awesome-copilot/refs/heads/main/{{folder}}/{{filename}} + (e.g., https://raw.githubusercontent.com/github/awesome-copilot/refs/heads/main/prompts/java-junit.prompt.md) + - MCP servers → https://modelcontextprotocol.io/ or + https://code.visualstudio.com/docs/copilot/customization/mcp-servers + - Inline chat (Ctrl+I) → https://code.visualstudio.com/docs/copilot/inline-chat + - Chat tools/agents → https://code.visualstudio.com/docs/copilot/chat/ + - General Copilot → https://code.visualstudio.com/docs/copilot/ or + https://docs.github.com/en/copilot/ + +2. **Search strategy**: + - For workspace files: Use search tools to find matching files in ${workspaceFolder} + - For GitHub awesome-copilot: Fetch raw content from https://raw.githubusercontent.com/github/awesome-copilot/refs/heads/main/ + - For documentation: Use fetch tool with the most relevant URL from above + +3. **Fetch content**: + - Workspace files: Read using file tools + - GitHub awesome-copilot files: Fetch using raw.githubusercontent.com URLs + - Documentation URLs: Fetch using fetch tool + +4. **Evaluate and respond**: + - Use the fetched content as the reference for completing the request + - Adapt response verbosity based on chat context + +### Unambiguous Queries + +If the user **DOES** provide a specific URL or file, skip searching and fetch/read that directly. + +### Optional + +* **Help output** - Raw data matching `-h`, `--help`, `/?`, `--tldr`, `--man`, etc. + +## Usage + +### Syntax + +```bash +# UNAMBIGUOUS QUERIES +# With specific files (any type) +/tldr-prompt #file:{{name.prompt.md}} +/tldr-prompt #file:{{name.agent.md}} +/tldr-prompt #file:{{name.instructions.md}} +/tldr-prompt #file:{{name.collections.md}} + +# With URLs +/tldr-prompt #fetch {{https://example.com/docs}} + +# AMBIGUOUS QUERIES +/tldr-prompt "{{topic or question}}" +/tldr-prompt "MCP servers" +/tldr-prompt "inline chat shortcuts" +``` + +### Error Handling + +#### Missing Required Parameters + +**User** + +```bash +/tldr-prompt +``` + +**Agent Response when NO Required Data** + +```text +Error: Missing required input. + +You MUST provide one of the following: +1. A Copilot file: /tldr-prompt #file:{{name.prompt.md | name.agent.md | name.instructions.md | name.collections.md}} +2. A URL: /tldr-prompt #fetch {{https://example.com/docs}} +3. A search query: /tldr-prompt "{{topic}}" (e.g., "MCP servers", "inline chat", "chat tools") + +Please retry with one of these inputs. +``` + +### AMBIGUOUS QUERIES + +#### Workspace Search + +> [!NOTE] +> First attempt to resolve using workspace files. If found, generate output. If no relevant files found, +> resolve using GitHub awesome-copilot as specified in **URL Resolver** section. + +**User** + +```bash +/tldr-prompt "Prompt files relevant to Java" +``` + +**Agent Response when Relevant Workspace Files Found** + +```text +I'll search ${workspaceFolder} for Copilot customization files (.prompt.md, .agent.md, .instructions.md, .collections.md) relevant to Java. +From the search results, I'll produce a tldr output for each file found. +``` + +**Agent Response when NO Relevant Workspace Files Found** + +```text +I'll check https://github.com/github/awesome-copilot +Found: +- https://github.com/github/awesome-copilot/blob/main/prompts/java-docs.prompt.md +- https://github.com/github/awesome-copilot/blob/main/prompts/java-junit.prompt.md + +Now let me fetch the raw content: +- https://raw.githubusercontent.com/github/awesome-copilot/refs/heads/main/prompts/java-docs.prompt.md +- https://raw.githubusercontent.com/github/awesome-copilot/refs/heads/main/prompts/java-junit.prompt.md + +I'll create a tldr summary for each prompt file. +``` + +### UNAMBIGUOUS QUERIES + +#### File Query + +**User** + +```bash +/tldr-prompt #file:typescript-mcp-server-generator.prompt.md +``` + +**Agent** + +```text +I'll read the file typescript-mcp-server-generator.prompt.md and create a tldr summary. +``` + +#### Documentation Query + +**User** + +```bash +/tldr-prompt "How do MCP servers work?" #fetch https://code.visualstudio.com/docs/copilot/customization/mcp-servers +``` + +**Agent** + +```text +I'll fetch the MCP server documentation from https://code.visualstudio.com/docs/copilot/customization/mcp-servers +and create a tldr summary of how MCP servers work. +``` + +## Workflow + +You MUST follow these steps in order: + +1. **Validate Input**: Confirm at least one required parameter is provided. If not, output the error +message from Error Handling section +2. **Identify Context**: + - Determine file type (.prompt.md, .agent.md, .instructions.md, .collections.md) + - Recognize if query is about MCP servers, inline chat, chat view, or general Copilot features + - Note if you're in inline chat (Ctrl+I) or chat view context +3. **Fetch Content**: + - For files: Read the file(s) using available file tools + - For URLs: Fetch content using `#tool:fetch` + - For queries: Apply URL Resolver strategy to find and fetch relevant content +4. **Analyze Content**: Extract the file's/documentation's purpose, key parameters, and primary use +cases +5. **Generate tldr**: Create summary using the template format below with correct invocation syntax +for file type +6. **Format Output**: + - Ensure markdown formatting is correct with proper code blocks and placeholders + - Use appropriate invocation prefix: `/` for prompts, `@` for agents, context-specific for + instructions/collections + - Adapt verbosity: inline chat = concise, chat view = detailed + +## Template + +Use this template structure when creating tldr pages: + +```markdown +# command + +> Short, snappy description. +> One to two sentences summarizing the prompt or prompt documentation. +> More information: | . + +- View documentation for creating something: + +`/file command-subcommand1` + +- View documentation for managing something: + +`/file command-subcommand2` +``` + +### Template Guidelines + +You MUST follow these formatting rules: + +- **Title**: You MUST use the exact filename without extension (e.g., `typescript-mcp-expert` for +.agent.md, `tldr-page` for .prompt.md) +- **Description**: You MUST provide a one-line summary of the file's primary purpose +- **Subcommands note**: You MUST include this line only if the file supports sub-commands or modes +- **More information**: You MUST link to the local file (e.g., ``, ``) +or source URL +- **Examples**: You MUST provide usage examples following these rules: + - Use correct invocation syntax: + * Prompts (.prompt.md): `/prompt-name {{parameters}}` + * Agents (.agent.md): `@agent-name {{request}}` + * Instructions (.instructions.md): Context-based (document how they apply) + * Collections (.collections.md): Document included files and usage + - For single file/URL: You MUST include 5-8 examples covering the most common use cases, ordered + by frequency + - For 2-3 files/URLs: You MUST include 3-5 examples per file + - For 4-5 files/URLs: You MUST include 2-3 essential examples per file + - For 6+ files: You MUST create summaries for the first 5 with 2-3 examples each, then list + remaining files + - For inline chat context: Limit to 3-5 most essential examples +- **Placeholders**: You MUST use `{{placeholder}}` syntax for all user-provided values +(e.g., `{{filename}}`, `{{url}}`, `{{parameter}}`) + +## Success Criteria + +Your output is complete when: + +- ✓ All required sections are present (title, description, more information, examples) +- ✓ Markdown formatting is valid with proper code blocks +- ✓ Examples use correct invocation syntax for file type (/ for prompts, @ for agents) +- ✓ Examples use `{{placeholder}}` syntax consistently for user-provided values +- ✓ Output is rendered directly in chat, not as a file creation +- ✓ Content accurately reflects the source file's/documentation's purpose and usage +- ✓ Response verbosity is appropriate for chat context (inline chat vs chat view) +- ✓ MCP server content includes setup and tool usage examples when applicable