Updates to agents #2155
Updates to agents #2155
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR reorganizes agent instruction files by standardizing agent naming conventions, removing an unused planner agent, and introducing comprehensive documentation writing guidelines.
- Agent names are standardized to remove spaces (e.g., "SnippetsMigration" instead of "Snippets Migration", "DocsEditor" instead of "Documentation Editor")
- The planner agent is removed entirely
- A new comprehensive documentation writing agent is added with detailed Microsoft Style Guide instructions
Reviewed Changes
Copilot reviewed 3 out of 4 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
.github/agents/snippets.migration.agent.md |
Updates agent name from "Snippets Migration" to "SnippetsMigration" for consistency |
.github/agents/planner.agent.md |
Removes the Issue Planner agent and its instructions completely |
.github/agents/docwriter.agent.md |
Adds new DocsWriter agent with extensive Microsoft Style Guide instructions for writing documentation |
.github/agents/doceditor.agent.md |
Updates agent name from "Documentation Editor" to "DocsEditor" for consistency |
| **Lists - NON-NEGOTIABLE:** | ||
| - ✅ **ALWAYS use Oxford comma: "item1, item2, and item3"** | ||
| - ✅ **ALWAYS number ordered lists with "1." for every item** | ||
| - ✅ **ALWAYS end list items with periods if more than 3 words** |
There was a problem hiding this comment.
The rule states "ALWAYS end list items with periods if more than 3 words" but this contradicts line 180 which shows "Prerequisites" (one word) shouldn't have a period, implying the guideline. However, the phrasing "if more than 3 words" is ambiguous - it should specify whether this applies to "complete sentences" or any list item. Consider clarifying to align with line 215: "ALWAYS end list items with periods for complete sentences (if more than 3 words)"
| - ✅ **ALWAYS end list items with periods if more than 3 words** | |
| - ✅ **ALWAYS end list items with periods for complete sentences (if more than 3 words)** |
| 3. **Code Examples**: Create code snippets following the repository's snippet structure and guidelines. | ||
| 4. **Technical Accuracy**: Ensure all technical information is correct and up-to-date. | ||
| 5. **Markdown Structure**: Use proper markdown formatting and document structure. | ||
| 6. **Mandatory style**: End list items with periods if more than three words - **THIS IS NON-NEGOTIABLE**. |
There was a problem hiding this comment.
This line duplicates the rule from line 42 with slightly different wording. Line 42 says "ALWAYS end list items with periods if more than 3 words" while line 64 says "End list items with periods if more than three words". The inconsistency in number format ("3" vs "three") and emphasis level creates confusion. Consider removing this duplication or consolidating the rules.
| 6. **Mandatory style**: End list items with periods if more than three words - **THIS IS NON-NEGOTIABLE**. |
| - [ ] Frontmatter includes `ai-usage: ai-generated` | ||
| - [ ] Used appropriate template from /.github/projects/article-templates/ | ||
| - [ ] **Oxford commas used in ALL lists** | ||
| - [ ] **Ordered lists use "1." for every item** |
There was a problem hiding this comment.
The instruction "Ordered lists use '1.' for every item" is repeated from line 212 with the same confusing wording. This creates maintenance issues and doesn't clarify the intent. Consider either removing this duplicate or cross-referencing the main rule.
| - [ ] **Ordered lists use "1." for every item** |
| - [ ] Code snippets follow repository structure | ||
| - [ ] Frontmatter includes `ai-usage: ai-generated` | ||
| - [ ] Used appropriate template from /.github/projects/article-templates/ | ||
| - [ ] **Oxford commas used in ALL lists** |
There was a problem hiding this comment.
The rule "Oxford commas used in ALL lists" is duplicated from line 211. This duplication in the validation checklist is redundant with the earlier detailed instruction and could lead to maintenance issues if one is updated but not the other.
| - [ ] **Oxford commas used in ALL lists** |
| - [ ] Used appropriate template from /.github/projects/article-templates/ | ||
| - [ ] **Oxford commas used in ALL lists** | ||
| - [ ] **Ordered lists use "1." for every item** | ||
| - [ ] **List items over 3 words end with periods** |
There was a problem hiding this comment.
The rule "List items over 3 words end with periods" is duplicated from lines 42, 64, and 215 with varying wording and emphasis. This repetition with inconsistent phrasing ("over 3" vs "more than 3" vs "if more than three") creates maintenance burden and potential confusion.
|
|
||
| ### Lists | ||
| - **CRITICAL: ALWAYS use Oxford comma: "Android, iOS, and Windows" - NO EXCEPTIONS** | ||
| - **MANDATORY: Number ordered lists using "1." for every item - NEVER use 1., 2., 3.** |
There was a problem hiding this comment.
The instruction states "Number ordered lists using '1.' for every item - NEVER use 1., 2., 3." This is confusing because both "1." and "1., 2., 3." use the same notation. The intent appears to be that Markdown should use "1." for every numbered item (letting Markdown auto-number), but the wording contradicts itself. Consider clarifying to: "NEVER manually increment numbers - use '1.' for all items and let Markdown auto-number"
| - **MANDATORY: Number ordered lists using "1." for every item - NEVER use 1., 2., 3.** | |
| - **MANDATORY: NEVER manually increment numbers - use "1." for all items and let Markdown auto-number.** |
|
|
||
| **ALWAYS use proper punctuation:** | ||
| - Remove colons from headings: ✅ "Next steps" NOT ❌ "Next steps:" | ||
| - Use periods in lists for complete sentences over 3 words |
There was a problem hiding this comment.
The example "Use periods in lists for complete sentences over 3 words" is vague. The guideline should clarify whether "3 words" includes articles and prepositions, and whether it's exactly 3 or "more than 3". Looking at line 215, it states "if more than 3 words", which provides the clarification. Consider making this consistent by changing line 179 to match: "Use periods in lists for complete sentences (if more than 3 words)"
| - Use periods in lists for complete sentences over 3 words | |
| - Use periods in lists for complete sentences (if more than 3 words) |
| ## LIST AND STRUCTURE RULES - REQUIRED FOR ALL WRITING | ||
|
|
||
| ### Lists | ||
| - **CRITICAL: ALWAYS use Oxford comma: "Android, iOS, and Windows" - NO EXCEPTIONS** |
There was a problem hiding this comment.
| - **CRITICAL: ALWAYS use Oxford comma: "Android, iOS, and Windows" - NO EXCEPTIONS** | |
| - **CRITICAL: ALWAYS use Oxford comma for lists of three or more items: "Android, iOS, and Windows" - NO EXCEPTIONS** |
There was a problem hiding this comment.
Do you want to tell it to add the new file to the appropriate TOC?
Tweak the agents instruction files around.
Internal previews