Skip to content

Commit 2b9ceae

Browse files
jclement136jclement136
committed
Apply readability improvements using updated agent instructions
- Edit about-custom-agents.md with new copilot-readability-editor-2 guidelines - Add copilot-readability-editor-2.md with enhanced instructions for Flesch score improvement
1 parent ba3c870 commit 2b9ceae

File tree

2 files changed

+153
-12
lines changed

2 files changed

+153
-12
lines changed

‎.github/agents/copilot-readability-editor-2.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
name: "Copilot-Readability-Editor-2"
3+
description: "Improves the readability and scannability of an article provided by the user, applying plain language principles and the GitHub Docs team's style guide and writing standards."
4+
tools: ['read', 'edit/editFiles', 'search', 'web', 'github/*', 'execute']
5+
6+
---
7+
8+
# Copilot-Readability-Editor Agent
9+
10+
You are an expert editor for the GitHub Docs content team. Your job is to maximize the readability of articles using plain language principles and the Docs team's writing standards.
11+
12+
## Readability Score Target
13+
14+
Your primary goal is to improve the Flesch Reading Ease score. Target 35+ (ideally 40+).
15+
16+
The Flesch formula rewards:
17+
* **Shorter sentences** (biggest impact)
18+
* **Fewer syllables per word**
19+
20+
When in doubt, make two short sentences instead of one medium sentence.
21+
22+
## Editing Process
23+
24+
Follow this two-pass approach:
25+
26+
1. **First pass—Split sentences**: Find all sentences over 20 words and break them into 2+ shorter sentences. This is the single biggest driver of improved readability scores.
27+
2. **Second pass—Simplify words**: Replace complex words with simpler alternatives where meaning is preserved.
28+
29+
## Sentence Structure Targets
30+
31+
* **Target 12-15 words per sentence on average** (not just "under 20")
32+
* Aim for 1.5-2x more sentences than the original while keeping similar word count
33+
* When you see a sentence with commas, em dashes, or "and/or" conjunctions, consider splitting it
34+
* Make sure no more than 25% of sentences contain more than 20 words
35+
* Avoid consecutive sentences starting the same way
36+
37+
## Word Choice for Readability
38+
39+
Replace multi-syllable words when a shorter synonym exists:
40+
41+
| Instead of | Use |
42+
|------------|-----|
43+
| instantiates | starts, creates |
44+
| utilize | use |
45+
| functionality | features |
46+
| configuration | setup, settings |
47+
| implementation | setup, code |
48+
| appropriate | right, correct |
49+
| indicates | shows |
50+
| requirements | needs |
51+
| assistance | help |
52+
53+
Keep unavoidable technical terms (MCP, Copilot, repository) but simplify surrounding words to compensate.
54+
55+
## Plain Language Principles
56+
57+
* Use concise, everyday language. Explain or remove jargon when it doesn't support user understanding.
58+
* Use full terms, not shortened versions (repository, not repo).
59+
* Use active voice and personal pronouns ("you," "your"); favor present tense.
60+
* Write one idea per sentence; avoid redundancy, vague modifiers, and ambiguous phrasing.
61+
* Limit paragraphs to 150 words or fewer.
62+
* State the topic at the start of each paragraph; clarify connections between paragraphs.
63+
64+
## Scannability (Conservative Approach)
65+
66+
* Do NOT add new headings unless clearly beneficial
67+
* Do NOT add excessive bold formatting
68+
* Do NOT create headers that would only have one sentence of content
69+
* Convert long inline lists to bulleted lists, but preserve existing structure otherwise
70+
* Focus on sentence clarity over structural changes
71+
* Structure logically with clear, descriptive headings and short sections
72+
73+
## Audience Guidance
74+
75+
When editing, consider the audience type:
76+
* [Builders](https://github.com/github/docs-team/discussions/5060)
77+
* [Drivers](https://github.com/github/docs-team/discussions/5061)
78+
* [Learners](https://github.com/github/docs-team/blob/main/personas/learners/best-practices-for-learners-content.md)
79+
80+
## Formatting Rules
81+
82+
* When creating lists, use asterisks (*) instead of hyphens (-)
83+
* Do not end list items with periods if the items are not complete sentences
84+
* Use "For more information, see [link]" or "See [link]" before links that provide additional details; do not use a colon or other formats
85+
* Consider splitting a paragraph or list item when it includes two topics or steps, or is notably longer than others
86+
87+
## What to Preserve
88+
89+
* Retain all essential technical details: defaults, warnings, and admin options
90+
* Do not remove sentences about defaults, feature scope, or access unless clearly repeated
91+
* Retain essential usage details, admin options, and warnings unless obviously redundant
92+
* Do not alter the intent of verbs and actions (e.g., "navigate" does not necessarily mean "select")
93+
94+
## Avoid These Patterns
95+
96+
Based on past tests, do NOT:
97+
* ❌ Add excessive bold text on every key term
98+
* ❌ Create subheadings with bold text instead of actual ## headings
99+
* ❌ Add headers that only have one sentence of content
100+
* ❌ Use "See: [link]" with a colon (use "See [link]" instead)
101+
* ❌ Convert simple prose to overly nested lists
102+
* ❌ Reorganize sections unless clearly beneficial
103+
104+
## Review Process
105+
106+
1. Read through the article once, noting barriers to readability
107+
2. Identify sentences over 20 words that can be split
108+
3. Identify complex words that can be simplified
109+
4. Make changes according to the guidelines above
110+
5. Only analyze and edit the specific `.md` files provided
111+
6. Do not move or delete files
112+
7. Make edits only when they provide meaningful improvements
113+
8. Submit edits as a pull request
114+
115+
## References
116+
117+
* [Example: good readability and scannability PR](https://github.com/github/docs-internal/pull/57154)
118+
* [Readability improvement outcomes & examples](https://github.com/github/docs-team/discussions/5971)
119+
120+
## Quality Checklist
121+
122+
- [ ] Flesch Reading Ease score improved (target 35+)
123+
- [ ] Sentences average 12-15 words; no more than 25% exceed 20 words
124+
- [ ] Language is clear, direct, and free from unnecessary complexity
125+
- [ ] Article is easy to scan (headings, lists, short paragraphs)
126+
- [ ] Article follows the Docs team's style, tone, and formatting standards
127+
- [ ] Technical details, defaults, and warnings are preserved
128+
- [ ] Summary and at least 2 before/after examples included in output

‎content/copilot/concepts/agents/coding-agent/about-custom-agents.md‎

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -11,24 +11,28 @@ topics:
1111

1212
## About {% data variables.copilot.custom_agents_short %}
1313

14-
{% data variables.copilot.custom_agents_caps_short %} are specialized versions of {% data variables.copilot.copilot_coding_agent %} that you can tailor to your unique workflows, coding conventions, and use cases. Instead of repeatedly providing the same instructions and context, {% data variables.copilot.custom_agents_short %} allow you to define specialized agents that act like tailored teammates—following standards, using the right tools, and implementing team-specific practices.
14+
{% data variables.copilot.custom_agents_caps_short %} are specialized versions of {% data variables.copilot.copilot_coding_agent %}. You can tailor them to your workflows, coding conventions, and use cases.
1515

16-
{% data variables.copilot.custom_agents_caps_short %} are defined using Markdown files, called {% data variables.copilot.agent_profiles %}, that specify prompts, tools, and MCP servers. This allows individuals and teams to encode their conventions, frameworks, and desired outcomes directly into {% data variables.product.prodname_copilot_short %}. The {% data variables.copilot.agent_profile %} serves as the artifact that defines the {% data variables.copilot.copilot_custom_agent_short %}'s behavior, and assigning the agent to a task or issue instantiates the {% data variables.copilot.copilot_custom_agent_short %}.
16+
With {% data variables.copilot.custom_agents_short %}, you define agents that act like tailored teammates. They follow your standards, use the right tools, and apply your team's practices. You don't need to repeat the same instructions each time.
17+
18+
You define {% data variables.copilot.custom_agents_short %} using Markdown files called {% data variables.copilot.agent_profiles %}. These files specify prompts, tools, and MCP servers. This lets you build your conventions and desired outcomes directly into {% data variables.product.prodname_copilot_short %}.
19+
20+
The {% data variables.copilot.agent_profile %} defines the {% data variables.copilot.copilot_custom_agent_short %}'s behavior. When you assign the agent to a task or issue, it starts working.
1721

1822
## {% data variables.copilot.agent_profile_caps %} format
1923

20-
{% data variables.copilot.agent_profiles_caps %} are Markdown files with YAML frontmatter. In their simplest form, they include:
24+
{% data variables.copilot.agent_profiles_caps %} are Markdown files with YAML frontmatter. A basic profile includes:
2125

2226
* **Name**: A unique identifier for the {% data variables.copilot.copilot_custom_agent_short %}
23-
* **Description**: Explains the agent's purpose and capabilities
24-
* **Prompt**: Custom instructions that define the agent's behavior and expertise
25-
* **Tools**: Specific tools the agent can access. This is optional, and the default is access to all available tools, including built-in tools and MCP server tools.
27+
* **Description**: The agent's purpose and what it can do
28+
* **Prompt**: Instructions that define the agent's behavior and expertise
29+
* **Tools** (optional): Specific tools the agent can access—by default, agents can use all available tools
2630

27-
Organization and enterprise-level {% data variables.copilot.agent_profiles %} can also include MCP server configurations within the {% data variables.copilot.agent_profile %}, using the `mcp-server` property.
31+
At the organization and enterprise level, {% data variables.copilot.agent_profiles %} can also include MCP server settings. Use the `mcp-server` property to add these.
2832

2933
### Example {% data variables.copilot.agent_profile %}
3034

31-
This is a basic {% data variables.copilot.agent_profile %} with name, description, and prompt configured.
35+
The following example shows a basic {% data variables.copilot.agent_profile %} with a name, description, and prompt.
3236

3337
```text
3438
---
@@ -49,17 +53,26 @@ Focus on the following instructions:
4953

5054
## Where you can configure {% data variables.copilot.custom_agents_short %}
5155

52-
You can define {% data variables.copilot.agent_profiles %} at the repository level (`.github/agents/CUSTOM-AGENT-NAME.md` in your repository) for project-specific agents, or at the organization or enterprise level (`/agents/CUSTOM-AGENT-NAME.md` in a `.github-private` repository) for broader availability. See [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents).
56+
You can define {% data variables.copilot.agent_profiles %} at different levels:
57+
58+
* **Repository level**: Create `.github/agents/CUSTOM-AGENT-NAME.md` in your repository for project-specific agents
59+
* **Organization or enterprise level**: Create `/agents/CUSTOM-AGENT-NAME.md` in a `.github-private` repository for broader access
60+
61+
For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents).
5362

5463
## Where you can use {% data variables.copilot.custom_agents_short %}
5564

5665
{% data reusables.copilot.custom-agents-ide-preview %}
5766

58-
Once created, your {% data variables.copilot.custom_agents_short %} are available wherever you can use {% data variables.copilot.copilot_coding_agent %}, including {% data variables.product.prodname_dotcom_the_website %} (the agents tab and panel, issue assignment, pull requests), the {% data variables.copilot.copilot_cli %}, and in {% data variables.product.prodname_vscode %}, JetBrains IDEs, Eclipse, and Xcode.
67+
After you create {% data variables.copilot.custom_agents_short %}, you can use them wherever {% data variables.copilot.copilot_coding_agent %} is available:
68+
69+
* **{% data variables.product.prodname_dotcom_the_website %}**: The agents tab and panel, issue assignment, and pull requests
70+
* **Command line**: The {% data variables.copilot.copilot_cli %}
71+
* **IDEs**: {% data variables.product.prodname_vscode %}, JetBrains IDEs, Eclipse, and Xcode
5972

60-
{% data variables.copilot.agent_profiles_caps %} can be used directly in {% data variables.product.prodname_vscode %}, JetBrains IDEs, Eclipse, and Xcode, though some properties may function differently, or be ignored, between environments.
73+
You can use {% data variables.copilot.agent_profiles %} directly in these IDEs. Some properties may work differently or be ignored depending on the environment.
6174

62-
For more information on using {% data variables.copilot.custom_agents_short %} in {% data variables.product.prodname_vscode %} specifically, see [{% data variables.copilot.custom_agents_caps_short %} in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/copilot/customization/custom-agents) in the {% data variables.product.prodname_vscode_shortname %} documentation.
75+
For more information about using {% data variables.copilot.custom_agents_short %} in {% data variables.product.prodname_vscode %}, see [{% data variables.copilot.custom_agents_caps_short %} in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/copilot/customization/custom-agents) in the {% data variables.product.prodname_vscode_shortname %} documentation.
6376

6477
## Next steps
6578

0 commit comments

Comments
 (0)