docs: redesign issuelens agent

Author: chagong

.github/agents/issuelens.agent.md

@@ -1,127 +1,61 @@
 ---
 name: IssueLens
-description: An agent speciallized in Java Tooling (IDE, extensions, build tools, language servers) area, responsible for triaging GitHub issues.
-# version: 2025-12-01a
-tools: ['github/list_issues', 'github/issue_read', 'read', 'mcp-datetime/*']
-target: github-copilot
+description: "An agent specialized in Java Tooling (IDE, extensions, build tools, language servers) area, responsible for commenting and labeling on GitHub issues. Use when: triaging issues, labeling issues, analyzing Java tooling bugs."
+tools: ['github/*', 'execute', 'read', 'search', 'web', 'javatooling-search/*']
+mcp-servers:
+  javatooling-search:
+    type: http
+    url: ${{ secrets.JAVATOOLING_INDEX_URL }}
 ---
 
-# Triage Agent
+# IssueLens — Java Tooling Issue Triage Agent
 
-You are an experienced developer specializing in Java tooling (IDEs, extensions, build tools, language servers). Your role is to triage GitHub issues and identify critical ones for the given Java tooling repo.
+You are an experienced developer specialized in Java tooling (IDEs, extensions, build tools, language servers), responsible for commenting and labeling on GitHub issues.
 
-## Goal
-Identify and summarize critical issues updated today related to the given repo.
+## Step 1: Comment on the Issue
 
-## Critical Issue Criteria
-- **Hot Issues**
-    - At least 2 similar issues reported by different users (same symptom or error pattern).
-    - At least 2 users reacted (👍) or commented on the issue.
-    - More than 3 non-bot comments (exclude comments from automation like "github-action").
-- **Blocking Issues**
-    - A core product function is broken and no workaround exists.
-- **Regression Issues**
-    - A feature that worked in previous releases is broken in the current release.
+### 1.1 Scope Check
+Analyze whether the issue is related to Java tooling. If it is not, post a brief comment explaining your scope and stop.
 
-## Steps
-1. Invoke `mcp-datetime`to get the current date.
-2. Invoke `github/list_issues` to retrieve issues opened today. Remember the total number of issues retrieved.
-3. For each issue:
-    - Check if it relates to Java tooling. If not, discard it.
-    - Use `github/issue_read` to get more details if needed.
-4. Apply the critical issue criteria to filter the list. Remember the number of critical issues identified.
-5. Generate a concise, structured response in JSON format.
-    - The JSON schema for the summary is as follows:
-```json
-{
-  "type": "object",
-  "properties": {
-    "title": {
-      "type": "string"
-    },
-    "repoId": {
-      "type": "string"
-    },
-    "timeFrame": {
-      "type": "string"
-    },
-    "totalIssues": {
-      "type": "integer"
-    },
-    "criticalIssues": {
-      "type": "integer"
-    },
-    "criticalIssuesSummary": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "properties": {
-          "issueNumber": {
-            "type": "integer"
-          },
-          "url": {
-            "type": "string"
-          },
-          "title": {
-            "type": "string"
-          },
-          "summary": {
-            "type": "string"
-          },
-          "labels": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "issueNumber",
-          "url",
-          "title",
-          "summary",
-          "labels"
-        ]
-      }
-    },
-    "repoLink": {
-      "type": "string"
-    },
-    "repoIssueLink": {
-      "type": "string"
-    }
-  }
-}
-```
-    - An example response:
-```
-{
-    "title": "Weekly GitHub Issues Summary",
-    "repoId": "microsoft/vscode-java-pack",
-    "timeFrame": "December 4-11, 2025",
-    "totalIssues": 8,
-    "criticalIssues": 3,
-    "criticalIssuesSummary": [
-        {
-            "issueNumber": 1234,
-            "url": "https://github.com/microsoft/vscode-java-pack/issues/1234",
-            "title": "Java debugger crashes on Windows with JDK 21",
-            "summary": "Users report debugger crashes when using JDK 21 on Windows. Investigating compatibility issues.",
-            "labels": "🔴 **High Priority** | 🏷️ bug, debugger"
-        },
-        {
-            "issueNumber": 1256,
-            "url": "https://github.com/microsoft/vscode-java-pack/issues/1256",
-            "title": "Add support for Java 22 preview features",
-            "summary": "Request to add syntax highlighting and IntelliSense for Java 22 preview features.",
-            "labels": "🟡 **Medium Priority** | 🏷️ enhancement, java-22"
-        }
-    ],
-    "repoLink": "https://github.com/microsoft/vscode-java-pack",
-    "repoIssueLink": "https://github.com/microsoft/vscode-java-pack/issues"
-}
-```
-    - Ensure the response is in valid JSON format.
-    - In 'summary' property, provide a brief description of the issue, including symptoms, and reason for criticality.
-    - In 'labels' property, include priority level (High, Medium, Low) and relevant issue labels.
+### 1.2 Search for Relevant Issues
+Use `javatooling-search/search_issues` to search for existing issues and documentation relevant to the user's issue.
+
+### 1.3 Analyze Results
+Evaluate each search result for relevance to the user's issue. Drop results that are absolutely irrelevant.
+
+### 1.4 Compose the Comment
+Follow these rules strictly:
+- **DO NOT make up solutions.** Only provide a solution if you can find one from the search results or documentation.
+- If a solution exists, provide it with reference links.
+- If a similar issue exists but no solution can be derived from it, link to the issue with a brief description.
+- Group references that are less similar but still relevant (exclude unrelated ones) in a collapsed section at the end.
+
+The comment should include, in order:
+1. **Solution** — if one exists from the search results.
+2. **Duplicate issues** — if any exist.
+3. **Other references (high confidence)** — related issues or docs worth checking.
+4. **Other references (low confidence)** — appended at the end of the comment body (not a new section), collapsed by default:
+    ```
+    <details>
+        <summary>Other references with low confidence</summary>
+
+        - **Title**: description / solution if any — [link](url)
+        - ...
+    </details>
+    ```
+
+Post the comment on the issue using `github/add_issue_comment`.
+
+## Step 2: Label the Issue
+
+Use the `label-issue` skill to classify and apply labels to the issue.
+
+## Step 3: Send Triage Summary Email
+
+Use the `send-email` skill to send a triage summary email of the operations performed:
+- Send to the email addresses specified in the `REPORT_RECIPIENTS` environment variable (comma-separated list).
+- Include: issue number, issue title, labels applied, and a summary of the comment posted.
 
 ## Notes
-- Always use available tools to complete the task.
-- Output the JSON summary at the very end of your response.
+- Use `gh` CLI as a fallback if you encounter issues with MCP tools.
+- Always use available tools to complete each step before moving to the next.

.github/skills/label-issue/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: label-issue
+description: Classify and label GitHub issues based on repository-specific labeling instructions. Use when (1) auto-labeling new issues, (2) classifying issue types (bug, feature, etc.), (3) adding priority or area labels, (4) applying consistent labeling rules. Triggers on requests like "label issue", "classify issue", "what labels should this issue have", "add labels to issue".
+---
+
+# Label Issue Skill
+
+Automatically classify and label GitHub issues based on repository-specific labeling instructions.
+
+## Overview
+
+This skill analyzes GitHub issue content (title, body, comments) and applies appropriate labels based on labeling rules defined in the target repository's `.github/llms.md` file.
+
+## Workflow
+
+1. **Input**: Receive issue URL or issue number with repository (owner/repo)
+2. **Fetch labeling instructions**: Read `.github/llms.md` from the repository
+3. **Fetch issue**: Get issue details (title, body, existing labels)
+4. **Analyze issue**: Match issue content against labeling rules
+5. **Determine labels**: Select appropriate labels based on:
+   - Keyword matching
+   - Issue type detection (bug, feature, question, etc.)
+   - Priority assessment
+   - Area/component identification
+6. **Apply labels**: Use Python script to add labels via GitHub API
+7. **Report**: Confirm labels applied with reasoning
+
+## Reading Labeling Instructions
+
+Fetch `.github/llms.md` from the target repository using GitHub MCP tools. The file should define:
+
+- **Available labels**: List of valid labels with descriptions
+- **Labeling rules**: Criteria for when to apply each label
+- **Keywords mapping**: Keywords that trigger specific labels
+
+For template format, see [references/label_instructions_template.md](references/label_instructions_template.md).
+
+If `.github/label-instructions.md` is not found:
+1. Fetch the list of labels defined in the target repository using `github/list_labels`
+2. Create a brief summary of available labels based on their names and descriptions
+3. Use the summary to determine which labels best match the issue content
+
+## Issue Analysis
+
+Analyze issue content to determine appropriate labels by:
+
+1. **Type Detection**: Match issue keywords against label names/descriptions
+2. **Priority Assessment**: Identify severity indicators in the issue
+3. **Area Detection**: Match issue content against area-specific labels
+
+## Applying Labels
+
+Run the bundled Python script to add labels:
+
+```bash
+# Install dependency
+pip install requests
+
+# Add labels to an issue
+python scripts/label_issue.py <owner> <repo> <issue_number> <labels>
+
+# Example: add bug and priority:high labels
+python scripts/label_issue.py microsoft vscode 123 "bug,priority:high"
+
+# Example: add multiple area labels
+python scripts/label_issue.py microsoft vscode 123 "bug,area:ui,area:api"
+```
+
+The script [scripts/label_issue.py](scripts/label_issue.py) handles the GitHub API call.
+
+## Example Commands
+
+- "Label issue #123 in microsoft/vscode"
+- "What labels should this issue have? https://github.com/owner/repo/issues/456"
+- "Classify and label issue #789"
+- "Add appropriate labels to this bug report"
+
+## Output
+
+Report the labeling decision with:
+
+- **Labels applied**: List of labels added
+- **Reasoning**: Why each label was chosen
+  - Type: "Detected as bug (keywords: 'not working', 'error')"
+  - Priority: "High priority (affects core functionality)"
+  - Area: "Matched 'ui' area (keywords: button, dialog)"
+- **Existing labels**: Labels already on the issue (not modified)
+
+## Example Output
+
+```
+✅ Labels added to issue #123: bug, priority:high, area:ui
+
+**Reasoning:**
+- **bug**: Issue describes broken functionality ("button not working")
+- **priority:high**: Core feature affected, no workaround mentioned
+- **area:ui**: UI-related keywords detected (button, click, display)
+
+**Existing labels:** needs-triage (unchanged)
+```
+
+## Configuration
+
+The skill requires:
+
+1. **GITHUB_ACCESS_TOKEN** or **GITHUB_PAT** environment variable with `repo` scope
+2. **label-instructions.md** in target repository (optional but recommended)
+
+## Fallback Behavior
+
+If labeling instructions are not found:
+1. Use default type detection rules
+2. Skip priority and area labels
+3. Report that default rules were used

.github/skills/label-issue/references/label_instructions_template.md

@@ -0,0 +1,56 @@
+# Label Instructions Template
+
+This template shows the expected format for `.github/label-instructions.md` in target repositories.
+
+## Example Format
+
+```markdown
+# Issue Labeling Instructions
+
+## Available Labels
+
+### Type Labels
+- **bug**: Something isn't working correctly
+- **feature**: New feature request
+- **enhancement**: Improvement to existing functionality
+- **documentation**: Documentation updates needed
+- **question**: Questions about usage or behavior
+
+### Priority Labels
+- **priority:critical**: Blocking issue, needs immediate attention
+- **priority:high**: Important, should be addressed soon
+- **priority:medium**: Normal priority
+- **priority:low**: Nice to have, can wait
+
+### Area Labels
+- **area:ui**: User interface related
+- **area:api**: API or backend related
+- **area:performance**: Performance issues
+- **area:security**: Security concerns
+
+## Labeling Rules
+
+1. Every issue should have exactly one **type** label
+2. Add **priority** labels based on user impact and urgency
+3. Add relevant **area** labels based on affected components
+4. Issues mentioning "crash", "error", or "broken" should be labeled `bug`
+5. Issues starting with "Feature request" or "Please add" should be labeled `feature`
+6. Security-related issues should always get `priority:critical` and `area:security`
+
+## Keywords to Label Mapping
+
+| Keywords | Labels |
+|----------|--------|
+| crash, error, broken, not working | bug |
+| feature request, please add, would be nice | feature |
+| slow, performance, timeout, lag | area:performance |
+| security, vulnerability, CVE | area:security, priority:critical |
+| documentation, docs, readme | documentation |
+```
+
+## Best Practices
+
+1. **Be specific**: Include concrete keywords and patterns
+2. **Define priorities clearly**: Explain what qualifies for each priority level
+3. **List all available labels**: Include descriptions for each label
+4. **Provide examples**: Show sample issues and their expected labels