Improve doc-tester and doc-writer skills, fix cross-platform paths by mitchdenny · Pull Request #361 · microsoft/aspire.dev

mitchdenny · 2026-02-02T22:46:53Z

Summary

This PR enhances the doc-tester and doc-writer agent skills and fixes some workspace issues.

Key Changes

doc-tester skill

Knowledge Source Awareness: New section teaching agents to distinguish between intrinsic knowledge and documentation-derived knowledge, and to flag gaps rather than silently filling them
Documentation Takes Priority: Agents should follow the documentation being tested, not the skill's default guidance
Aspire CLI installation: Guidance for GA, Dev, PR, and Staging builds
Polyglot-friendly: Replaced dotnet commands with aspire add, aspire run, and aspire new
Hex1b MCP tools: Terminal screenshots and asciinema recordings support

doc-writer skill

AsciinemaPlayer component: Documentation for using terminal recordings
Hex1b MCP tools: Guidance for creating new recordings
Aspire CLI testing: Instructions for testing docs with different CLI versions

Other fixes

Updated Prettier extension recommendation from deprecated prettier.prettier-vscode to esbenp.prettier-vscode
Fixed cross-platform path in frontend.esproj (backslash → forward slash)

⚠️ Draft Status

This PR is marked as draft because it references Hex1b MCP asciinema recording features (mcp_hex1b_record_asciinema) that are not yet available. Merge once the updated Hex1b MCP server is released with asciinema support.

- Add doc-writer skill with Aspire documentation guidelines - Add doc-tester skill for validating documentation accuracy - Include common documentation rules from PR feedback patterns - Configure hex1b MCP server in .mcp.json, .vscode/mcp.json, opencode.jsonc - Add .doc-tester-workspace/ to .gitignore - Add .vscode/mcp.json exception to .gitignore

Key changes: doc-tester skill: - Add Knowledge Source Awareness section to distinguish between intrinsic knowledge and documentation-derived knowledge - Add Documentation Takes Priority guidance - follow the docs being tested, not skill defaults - Add Aspire CLI installation guidance (GA, Dev, PR, and Staging builds) - Replace dotnet-specific commands with polyglot-friendly Aspire CLI (aspire add, aspire run) - Add Hex1b MCP tools section for terminal screenshots and asciinema recordings doc-writer skill: - Add AsciinemaPlayer component documentation for terminal recordings - Add Hex1b MCP tools guidance for creating new recordings - Add Aspire CLI installation guidance for testing documentation - Add aspire add recommendation for testing integration packages Other fixes: - Update Prettier extension recommendation to esbenp.prettier-vscode - Fix cross-platform path in frontend.esproj (backslash to forward slash)

Copilot

Pull request overview

This pull request enhances the documentation testing and writing capabilities for AI agents by introducing two comprehensive skill files and fixing several workspace configuration issues.

Changes:

Adds comprehensive doc-tester and doc-writer skill files to guide AI agents in validating and creating Aspire documentation
Fixes cross-platform path issue in frontend.esproj (backslash to forward slash)
Updates VSCode Prettier extension recommendation from deprecated to current version
Adds Hex1b MCP server configuration to support terminal recording features
Introduces aspire-integration-names.json with 141 Aspire integrations

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`.github/skills/doc-tester/SKILL.md`	New 807-line skill file for AI agents to validate documentation accuracy through testing
`.github/skills/doc-writer/SKILL.md`	New 790-line skill file providing guidelines for writing Aspire documentation
`src/frontend/frontend.esproj`	Fixed path separator for cross-platform compatibility
`.vscode/extensions.json`	Updated Prettier extension from deprecated `prettier.prettier-vscode` to `esbenp.prettier-vscode`
`src/frontend/src/data/aspire-integration-names.json`	New file listing 141 Aspire and CommunityToolkit integration packages
`.vscode/mcp.json`	Added MCP server configuration for VSCode
`opencode.jsonc`	Added Hex1b MCP server configuration
`.mcp.json`	Added Hex1b MCP server configuration
`.gitignore`	Added `.vscode/mcp.json` exclusion and `.doc-tester-workspace/` directory

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-03T01:21:52Z

.github/skills/doc-tester/SKILL.md

+<Aside type="note">
+Aspire is polyglot and supports multiple languages (C#, Python, JavaScript, etc.). Follow the documentation's instructions for your target language. The docs should include any language-specific build steps if required.
+</Aside>


The <Aside> MDX component is being used in a Markdown file (SKILL.md). This file has YAML frontmatter and is a Markdown file, not an MDX file, so MDX components like <Aside> will not render properly. Consider using standard Markdown admonitions or note syntax instead, or converting this file to MDX format if components are needed.

Copilot · 2026-02-03T01:21:52Z

.github/skills/doc-writer/SKILL.md

+<Aside type="tip">
+When testing code examples that add integration packages, use `aspire add <package-name>` rather than `dotnet add package`. The Aspire CLI automatically adds packages to the correct project.
+</Aside>


The <Aside> MDX component is being used in a Markdown file (SKILL.md). This file has YAML frontmatter and is a Markdown file, not an MDX file, so MDX components like <Aside> will not render properly. Consider using standard Markdown admonitions or note syntax instead, or converting this file to MDX format if components are needed.

Suggested change

<Aside type="tip">

When testing code examples that add integration packages, use `aspire add <package-name>` rather than `dotnet add package`. The Aspire CLI automatically adds packages to the correct project.

</Aside>

> [!TIP]

> When testing code examples that add integration packages, use `aspire add <package-name>` rather than `dotnet add package`. The Aspire CLI automatically adds packages to the correct project.

Copilot · 2026-02-03T01:21:53Z

.vscode/extensions.json

    "astro-build.astro-vscode",
    "unifiedjs.vscode-mdx",
-    "prettier.prettier-vscode"
+    "esbenp.prettier-vscode"


The Prettier extension ID has been updated to esbenp.prettier-vscode in .vscode/extensions.json, but .vscode/settings.json still references the old deprecated ID prettier.prettier-vscode in multiple places (lines 4, 7, 10, 13, 16, 19, 22, 25). These references should also be updated to esbenp.prettier-vscode for consistency and to use the current extension.

Copilot · 2026-02-03T01:21:53Z

.github/skills/doc-writer/SKILL.md

+<Pivot id="csharp">
+C# specific content here.
+</Pivot>
+
+<Pivot id="python">


The Pivot components are missing the required key attribute that should match the PivotSelector's key. According to line 777 in this same file (Component Usage Rules), "When using nested Pivot components, ensure they reference the correct parent PivotSelector with the key attribute". The Pivot components should include key="lang" to match the PivotSelector.

Suggested change

<Pivot id="csharp">

C# specific content here.

</Pivot>

<Pivot id="python">

<Pivot key="lang" id="csharp">

C# specific content here.

</Pivot>

<Pivot key="lang" id="python">

Copilot · 2026-02-03T01:21:53Z

.github/skills/doc-tester/SKILL.md

+<Aside type="caution">
+Dev builds are the latest from the main branch and may be unstable. Only use for testing upcoming features.
+</Aside>


The <Aside> MDX component is being used in a Markdown file (SKILL.md). This file has YAML frontmatter and is a Markdown file, not an MDX file, so MDX components like <Aside> will not render properly. Consider using standard Markdown admonitions or note syntax instead, or converting this file to MDX format if components are needed.

Suggested change

<Aside type="caution">

Dev builds are the latest from the main branch and may be unstable. Only use for testing upcoming features.

</Aside>

> **Caution:** Dev builds are the latest from the main branch and may be unstable. Only use for testing upcoming features.

Copilot · 2026-02-03T01:21:53Z

.github/skills/doc-tester/SKILL.md

+<Aside type="tip">
+The `aspire add` command automatically adds packages to the correct project and handles any additional configuration. Only fall back to `dotnet add package` if the Aspire CLI is not available.
+</Aside>


The <Aside> MDX component is being used in a Markdown file (SKILL.md). This file has YAML frontmatter and is a Markdown file, not an MDX file, so MDX components like <Aside> will not render properly. Consider using standard Markdown admonitions or note syntax instead, or converting this file to MDX format if components are needed.

* Clarify Azure AI Foundry format parameter documentation (#313) * Initial plan * Improve Azure AI Foundry format parameter documentation Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> * Configure WAF on the Azure Front Door (#324) * Configure WAF on the Azure Front Door These policies are required by Microsoft to prevent DDOS attacks on the site. * Fix invalid wafPolicy name * Update resource creation in Node.js docs (#333) Correction to invalid syntax. * Add generic "Upgrade Aspire" article under What's new (#322) * Initial plan * Add Upgrade Aspire article and update sidebar configuration Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> * Fix typo and remove broken link in Upgrade Aspire article Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> * refactor: streamline Upgrade Aspire article and remove legacy content * fix: update Upgrade Aspire article for clarity and accuracy * chore: remove outdated setup and tooling link from Upgrade Aspire article * fix: update link to installation instructions for Aspire CLI in Upgrade Aspire article * fix: clarify upgrade instructions and remove outdated content in Upgrade Aspire article --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> Co-authored-by: David Pine <david.pine@microsoft.com> * Add CLI telemetry details page * Fix * Fix * Fix * Improve doc-tester and doc-writer skills, fix cross-platform paths (#361) * Add doc-writer and doc-tester skills with hex1b MCP server - Add doc-writer skill with Aspire documentation guidelines - Add doc-tester skill for validating documentation accuracy - Include common documentation rules from PR feedback patterns - Configure hex1b MCP server in .mcp.json, .vscode/mcp.json, opencode.jsonc - Add .doc-tester-workspace/ to .gitignore - Add .vscode/mcp.json exception to .gitignore * Improve doc-tester and doc-writer skills, fix cross-platform paths Key changes: doc-tester skill: - Add Knowledge Source Awareness section to distinguish between intrinsic knowledge and documentation-derived knowledge - Add Documentation Takes Priority guidance - follow the docs being tested, not skill defaults - Add Aspire CLI installation guidance (GA, Dev, PR, and Staging builds) - Replace dotnet-specific commands with polyglot-friendly Aspire CLI (aspire add, aspire run) - Add Hex1b MCP tools section for terminal screenshots and asciinema recordings doc-writer skill: - Add AsciinemaPlayer component documentation for terminal recordings - Add Hex1b MCP tools guidance for creating new recordings - Add Aspire CLI installation guidance for testing documentation - Add aspire add recommendation for testing integration packages Other fixes: - Update Prettier extension recommendation to esbenp.prettier-vscode - Fix cross-platform path in frontend.esproj (backslash to forward slash) * Update Hex1b.McpServer to 0.66.0 --------- Co-authored-by: Mitch Denny <mitch@mitchdeny.com> * Fix PowerShell syntax in telemetry opt-out example --------- Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com> Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com> Co-authored-by: Tristan <Tri125@users.noreply.github.com> Co-authored-by: David Pine <david.pine@microsoft.com> Co-authored-by: Mitch Denny <midenn@microsoft.com> Co-authored-by: Mitch Denny <mitch@mitchdeny.com>

Mitch Denny added 3 commits February 3, 2026 08:48

Update Hex1b.McpServer to 0.66.0

f174d29

mitchdenny marked this pull request as ready for review February 3, 2026 01:15

mitchdenny requested a review from IEvangelist as a code owner February 3, 2026 01:15

Copilot AI review requested due to automatic review settings February 3, 2026 01:15

Copilot started reviewing on behalf of mitchdenny February 3, 2026 01:16 View session

Copilot AI reviewed Feb 3, 2026

View reviewed changes

JamesNK approved these changes Feb 3, 2026

View reviewed changes

mitchdenny merged commit d37a0b2 into main Feb 3, 2026
12 checks passed

mitchdenny deleted the update-skills-and-fixes branch February 3, 2026 02:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve doc-tester and doc-writer skills, fix cross-platform paths#361

Improve doc-tester and doc-writer skills, fix cross-platform paths#361
mitchdenny merged 3 commits intomainfrom
update-skills-and-fixes

mitchdenny commented Feb 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 3, 2026

Uh oh!

Copilot AI Feb 3, 2026

Uh oh!

Copilot AI Feb 3, 2026

Uh oh!

Copilot AI Feb 3, 2026

Uh oh!

Copilot AI Feb 3, 2026

Uh oh!

Copilot AI Feb 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

mitchdenny commented Feb 2, 2026

Summary

Key Changes

doc-tester skill

doc-writer skill

Other fixes

⚠️ Draft Status

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants