[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M69B82ZB3VA80DTJ37XMESXB":3,"skill-same:01M69B82ZB3VA80DTJ37XMESXB":69},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":26,"publishedAt":40,"linkOnly":41,"markdownContent":42,"markdownBody":43,"frontMatter":44,"refName":45,"commitSha":46,"skillDirectory":47,"forksCount":48,"repositoryHtmlUrl":49,"repositoryHomepageUrl":50,"ownerHtmlUrl":51,"ownerBlogUrl":52,"ownerDescription":53,"updatedAt":54,"install":55,"resources":68},"01M69B82ZB3VA80DTJ37XMESXB","doc-tester",null,"Agent for validating Aspire documentation against actual behavior. Use when auditing documentation accuracy, testing examples, or identifying discrepancies between documentation and implementation.","microsoft\u002Faspire.dev","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M69B7HZWV2YNDYYCP5G712FG",206,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire.dev\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fdoc-tester\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[27,28,29,30,31,32,33,34,35,36,37,38,39],"doc tester","doc","tester","testing","aspire","documentation","examples","behavior","use","implementation","for","accuracy","when","2026-11-10 10:12:30",false,"---\nname: doc-tester\ndescription: Agent for validating Aspire documentation against actual behavior. Use when auditing documentation accuracy, testing examples, or identifying discrepancies between documentation and implementation.\n---\n\n# Documentation Tester Skill\n\nThis skill provides guidelines for AI agents to systematically validate the aspire.dev documentation site against the actual behavior of Aspire. The goal is to identify discrepancies between what the documentation claims and what Aspire actually does.\n\n## ⚠️ CRITICAL: User-Centric Testing Approach\n\n**You are testing the documentation as if you were a new user learning Aspire.**\n\n### Core Principles\n\n1. **Use `playwright-cli` exclusively** to browse and interact with the documentation site\n2. **Never read source code** to understand how things work - rely only on what the docs tell you\n3. **Follow the documentation literally** - copy code examples exactly as shown\n4. **Evaluate teaching effectiveness** - can you learn from this documentation?\n\n### What This Means\n\n❌ **DO NOT:**\n- Read Aspire source code to understand behavior\n- Check implementation details in the microsoft\u002Faspire repository\n- Look at test files to understand expected behavior\n- Use internal knowledge of the codebase\n- Silently fill gaps with your built-in knowledge - flag them instead\n\n✅ **DO:**\n- Use `playwright-cli` commands to navigate the documentation site\n- Read documentation content as displayed in the browser\n- Copy code examples and run them in test projects\n- Evaluate if explanations make sense without prior knowledge\n- Flag when you use intrinsic knowledge to fill documentation gaps\n\n### When You Get Stuck\n\nIf documentation is insufficient to proceed:\n\n1. **Document the blocker** - What were you trying to do? What information was missing?\n2. **Describe the gap** - What would a user need to know to succeed?\n3. **Hand off to doc-writer** - Create a task for the doc-writer skill to fix it\n4. **Move on** - Continue testing other areas\n\nThis is valuable feedback! Gaps in documentation are exactly what we're trying to find.\n\n### Knowledge Source Awareness\n\n**Be critical of the documentation by distinguishing between what you know and where that knowledge came from.**\n\nAs an AI agent, you have built-in knowledge about programming concepts, frameworks, and common patterns. When testing documentation, constantly ask yourself:\n\n#### Documentation Takes Priority\n\nThe aspire.dev documentation covers the full spectrum of the Aspire experience - from installation and project creation to advanced scenarios. **When the documentation you're testing provides instructions for a task, follow those instructions exactly, even if this skill provides different guidance.**\n\nFor example:\n- If testing a \"Getting Started\" page that shows how to create a project, use the commands in that documentation - not the project creation steps in this skill\n- If an integration doc specifies how to add packages, follow those steps rather than the general guidance here\n- The skill's instructions are defaults; the documentation being tested overrides them\n\nThis ensures you're actually testing whether the documentation works, not whether this skill's instructions work.\n\n#### Questions to Ask\n\n1. **\"Did I learn this from the documentation, or did I already know it?\"**\n   - If you already knew it, would a new user know it too?\n   - Is it reasonable to assume this knowledge, or should the docs explain it?\n\n2. **\"Am I filling in gaps with my own knowledge?\"**\n   - If you had to use prior knowledge to complete a step, the documentation may be incomplete\n   - Document these gaps even if you were able to proceed\n\n3. **\"Would this make sense to someone unfamiliar with [concept]?\"**\n   - Aspire users come from diverse backgrounds (different languages, experience levels)\n   - Don't assume familiarity with .NET, containers, cloud concepts, etc.\n\n#### Examples\n\n| Situation | Question to Ask | Documentation Gap? |\n|-----------|-----------------|-------------------|\n| You know what a connection string is | Would a Python developer know this? | Maybe - consider if it needs explanation |\n| You understand dependency injection | Does the doc explain DI or assume it? | If assumed, should link to prerequisites |\n| You know `aspire run` starts all resources | Did the doc say this, or did you just know? | If not stated, it should be |\n| You recognize a Redis configuration pattern | Is this explained or assumed knowledge? | New users may not recognize it |\n\n#### Reporting Knowledge Gaps\n\nWhen you identify that you used intrinsic knowledge to proceed, flag it in your report:\n\n```markdown\n### Knowledge Gap: [Topic]\n\n**What I needed to know:** [Description]\n**Source of my knowledge:** Built-in\u002Fprior knowledge (NOT from documentation)\n**User impact:** [Who might struggle without this knowledge?]\n**Recommendation:** \n- [ ] Add explanation to this page\n- [ ] Link to prerequisite documentation\n- [ ] Reasonable to assume (explain why)\n```\n\n## Testing Goals\n\n### 1. Teaching Effectiveness\n\nCan someone learn Aspire from these docs alone?\n\n- Are concepts introduced in a logical order?\n- Are prerequisites clearly stated?\n- Do examples build on each other progressively?\n- Is terminology explained before being used?\n- Are common mistakes or gotchas addressed?\n\n### 2. Accuracy & Correctness\n\nDoes the documentation match reality?\n\n- Do code examples compile and run?\n- Are API signatures and parameters correct?\n- Do claimed features actually exist?\n- Are limitations and caveats documented?\n\n## Environment Setup\n\n### Installing the Aspire CLI\n\nBefore testing, ensure you have the appropriate version of the Aspire CLI installed. The version needed depends on what you're testing:\n\n#### GA\u002FStable Builds (Default)\n\nFor testing documentation of released features, use the stable release:\n\n```bash\n# Linux\u002FmacOS\ncurl -sSL https:\u002F\u002Faspire.dev\u002Finstall.sh | bash\n\n# Windows (PowerShell)\nirm https:\u002F\u002Faspire.dev\u002Finstall.ps1 | iex\n```\n\nFor complete installation instructions, see the [Install Aspire CLI](\u002Fget-started\u002Finstall-cli\u002F) page on the documentation site.\n\n#### Nightly\u002FDev Builds\n\nFor testing documentation of features being developed on the main branch, use the dev channel:\n\n```bash\n# Linux\u002FmacOS\ncurl -sSL https:\u002F\u002Faspire.dev\u002Finstall.sh | bash -s -- --quality dev\n\n# Windows (PowerShell)\niex \"& { $(irm https:\u002F\u002Faspire.dev\u002Finstall.ps1) } -Quality 'dev'\"\n```\n\nYou can also find the dev channel option by clicking the download icon on the aspire.dev site and selecting \"Dev\" from the Channel dropdown.\n\n\u003CAside type=\"caution\">\nDev builds are the latest from the main branch and may be unstable. Only use for testing upcoming features.\n\u003C\u002FAside>\n\n#### PR Builds\n\nFor testing documentation of features in specific pull requests (before they're merged), you need to install the CLI from the PR artifacts:\n\n1. Navigate to the PR in the [microsoft\u002Faspire](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire) repository\n2. Find the \"Checks\" or \"Actions\" section of the PR\n3. Look for the build artifacts that contain the CLI\n4. Download and install the CLI from the PR-specific build artifacts\n\nPR builds are useful when writing documentation ahead of feature merges.\n\n#### Staging Builds\n\nFor testing prerelease builds from the current release branch:\n\n```bash\n# Linux\u002FmacOS\ncurl -sSL https:\u002F\u002Faspire.dev\u002Finstall.sh | bash -s -- --quality staging\n\n# Windows (PowerShell)\niex \"& { $(irm https:\u002F\u002Faspire.dev\u002Finstall.ps1) } -Quality 'staging'\"\n```\n\n### Aspire App Model\n\nThe aspire.dev workspace uses Aspire to orchestrate local services. The app model in `apphost.cs` defines the documentation site resources. Use the Aspire CLI output or dashboard resource list to get the current resource states and URLs.\n\n### Starting the Local Environment\n\n⚠️ **CRITICAL: Terminal Isolation**\n\nAspire must run in an **isolated background process** to avoid interference with other terminal commands.\n\n**Start Aspire:**\n\n```bash\ncd \u002Fpath\u002Fto\u002Faspire.dev\naspire run\n```\n\nUse the Aspire CLI output or dashboard resource list to get the content URL. Look for the `frontend` resource endpoint URL, for example `http:\u002F\u002Ffrontend.dev.localhost:5000`.\n\n**IMPORTANT**: Use the local frontend URL for all testing, not https:\u002F\u002Faspire.dev\n\n### Creating Test Projects\n\nTo test code examples accurately, create test projects using the Aspire CLI.\n\n```bash\n# Create a test directory in the workspace\nmkdir -p .doc-tester-workspace\ncd .doc-tester-workspace\n\n# Create a new Aspire project using templates\naspire new aspire-starter -n DocTest -o DocTest\ncd DocTest\n```\n\nUse `aspire new --list` to see all available project templates. Choose a template that matches the documentation you're testing (e.g., Python, JavaScript, or .NET projects).\n\n## Purpose\n\nThe doc-tester agent produces actionable feedback that can:\n1. Trigger the **doc-writer** skill to correct documentation inaccuracies\n2. Identify product design issues that need to be addressed in Aspire\n3. Surface missing documentation for existing features\n4. Find broken examples or outdated instructions\n\n## Scope\n\n### What to Test\n\n| Area | Description |\n|------|-------------|\n| **Conceptual accuracy** | Do explanations match actual Aspire behavior? |\n| **Code examples** | Do code samples compile and run as described? |\n| **CLI commands** | Do Aspire CLI commands work as documented? |\n| **Integration docs** | Are integration configurations accurate? |\n| **Navigation & links** | Do internal links work? Are pages accessible? Do they follow link format conventions? |\n| **Feature coverage** | Are all significant features documented? |\n\n### Link Validation Rules\n\nWhen testing any page, verify that **all internal links** follow these conventions:\n\n1. **Site-relative paths**: Internal links must start with `\u002F` (not relative paths like `..\u002F` except within the same integration section)\n2. **Trailing slash required**: All internal links must end with `\u002F` (e.g., `\u002Fget-started\u002Ffirst-app\u002F` not `\u002Fget-started\u002Ffirst-app`)\n3. **Anchor links**: Hash links to sections on the same page (e.g., `#configuration`) are fine without a trailing slash\n4. **Valid targets**: Every internal link must point to a page that actually exists in the docs\n5. **No broken anchors**: Section anchor links (e.g., `\u002Fpage\u002F#section-name`) must reference an actual heading on the target page\n\n**How to validate links:**\n- Extract all `[text](url)` and `href=\"url\"` patterns from the page source\n- For site-relative links, verify the target `.mdx` file exists under `src\u002Ffrontend\u002Fsrc\u002Fcontent\u002Fdocs\u002F`\n- For links with anchors, verify the heading exists on the target page\n- Use Playwright to click links and verify they resolve (no 404s)\n\n### Documentation Structure\n\nThe documentation site includes:\n\n```\n\u002F                           # Landing page\n\u002Fget-started\u002F               # Getting started guides\n    prerequisites\n    install-cli\n    first-app\n    app-host\n    deploy-first-app\n    ...\n\u002Ffundamentals\u002F             # Core concepts\n    app-host\n    networking-overview\n    service-defaults\n    ...\n\u002Fintegrations\u002F             # Per-integration documentation\n    databases\u002F\n    caching\u002F\n    messaging\u002F\n    ai\u002F\n    ...\n\u002Fdeployment\u002F               # Deployment guides\n\u002Fdiagnostics\u002F              # Diagnostics and telemetry\n\u002Fdashboard\u002F                # Dashboard documentation\n\u002Ftesting\u002F                  # Testing guides\n\u002Freference\u002F                # API and CLI reference\n\u002Fwhats-new\u002F                # Release notes\n```\n\n## Testing Workflow\n\n**All browser-based testing uses `playwright-cli` to interact with the documentation site.**\n\n### Phase 0: Environment Preparation\n\n1. **Start Aspire**: Run `aspire run` from the repository root\n2. **Get frontend URL**: Use the Aspire CLI output or dashboard resource list to find the `frontend` endpoint\n3. **Note the URL**: The script outputs the local development URL\n\n### Phase 1: Navigate and Read Documentation (Playwright)\n\nUse `playwright-cli` to browse the documentation:\n\n```bash\n# Open the local docs site\nplaywright-cli open http:\u002F\u002Ffrontend.dev.localhost:5000\n\n# Take an accessibility snapshot to read page content\nplaywright-cli snapshot\n\n# Navigate to a page by clicking a ref from the snapshot\nplaywright-cli click e42\n\n# Read page content\nplaywright-cli snapshot\n```\n\nFor each documentation page:\n\n1. **Navigate to the page** using Playwright click actions\n2. **Take a snapshot** to read the page content\n3. **Evaluate the content** - Is it clear? Complete? Accurate?\n4. **Note any confusion** - What would a new user struggle with?\n5. **Inspect current-version references in the source MDX** - Rendered pages\n   show the replaced value, so confirm that current guidance uses the shared\n   placeholders rather than a hard-coded Aspire version:\n   - `%ASPIRE_VERSION%` for the full current stable version\n   - `%ASPIRE_VERSION_MAJOR_MINOR%` for the current major\u002Fminor version\n\nFlag hard-coded Aspire versions in current installation instructions, package\nreferences, AppHost SDK declarations, CLI output, and copy\u002Fpaste examples.\nKeep fixed versions when the exact version is intentional, such as release\nnotes, upgrade comparisons, minimum-version requirements, compatibility notes,\nor issue reproduction steps.\n\n### Phase 2: Test CLI Commands\n\nFor CLI commands shown in the documentation:\n\n1. **Copy the command exactly** as shown in the browser\n2. **Run the command** in the terminal\n3. **Verify output** - Does it match what the docs describe?\n4. **Test variations** - Do optional parameters work as documented?\n\n#### Example: Testing aspire new\n\n```bash\n# Create a test directory\ncd \u002Fpath\u002Fto\u002Faspire.dev\u002F.doc-tester-workspace\nmkdir -p cli-tests && cd cli-tests\n\n# Test the command from documentation\naspire new aspire-starter -n TestApp -o TestApp\n\n# Verify the output matches documentation claims\nls TestApp\u002F\n```\n\n### Phase 3: Test Code Examples\n\nFor each code example shown in the documentation:\n\n1. **Copy the code exactly** as shown in the browser\n2. **Create a test project** in the workspace directory\n3. **Build the code** - does it compile without errors?\n4. **Run and observe** - does it behave as documented?\n\n#### Step 1: Create Test Project\n\n```bash\n# Navigate to workspace\ncd \u002Fpath\u002Fto\u002Faspire.dev\u002F.doc-tester-workspace\n\n# Create a project using an appropriate Aspire template\naspire new aspire-starter -n ExampleTest -o ExampleTest\ncd ExampleTest\n```\n\nUse `aspire new --list` to view available templates. Choose a template that matches the language or framework in the documentation you're testing.\n\n#### Step 2: Add Required Packages\n\nBased on the documentation being tested, use the Aspire CLI to add integration packages:\n\n```bash\n# Add hosting packages using Aspire CLI (preferred)\naspire add Aspire.Hosting.Redis\n\n# Or add client packages\naspire add Aspire.StackExchange.Redis\n```\n\n\u003CAside type=\"tip\">\nThe `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.\n\u003C\u002FAside>\n\n#### Step 3: Apply Code Examples\n\nCopy the code examples from the documentation into your test project exactly as shown. This may involve:\n- Updating source files (e.g., `Program.cs`, `app.py`, `server.js`)\n- Adding configuration files\n- Any other steps the documentation specifies\n\n\u003CAside type=\"note\">\nAspire 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.\n\u003C\u002FAside>\n\n#### Step 4: Run and Verify\n\nUse `aspire run` to build and run the application:\n\n```bash\naspire run\n```\n\nAspire handles building and orchestrating all resources. If the documentation specifies additional build or run commands for specific languages, follow those instructions and verify they work as documented.\n\n### Phase 4: Test Integration Documentation\n\nFor integration documentation:\n\n1. **Verify package installation** - Does the documented package exist?\n2. **Test basic usage** - Does the minimal example work?\n3. **Test configuration** - Do configuration options work as described?\n4. **Check health checks** - Do documented health checks function?\n\n```bash\n# Verify package exists using Aspire CLI\naspire add Aspire.Hosting.Technology\n\n# If package not found, document as error\n```\n\n### Phase 5: Evaluate Teaching Effectiveness\n\nAs you navigate, evaluate:\n\n1. **Concept flow** - Are ideas introduced in a logical order?\n2. **Prerequisites** - Is prior knowledge clearly stated?\n3. **Completeness** - Can you accomplish tasks with just the docs?\n4. **Clarity** - Would a new user understand this?\n\n**When you get stuck:**\n- Document what you were trying to do\n- Note what information was missing\n- This becomes a doc-writer task\n\n## Focus Area Templates\n\nWhen given a focus area, use these templates to guide testing:\n\n### Getting Started Focus\n\n```markdown\n## Focus: Getting Started Guide\n\n### Page: \u002Fget-started\u002F[page-name]\n\n#### Navigation (Playwright)\n- [ ] Page loads successfully\n- [ ] All sections visible in snapshot\n- [ ] Code examples readable\n- [ ] Links to related pages work\n- [ ] All internal links are site-relative with trailing slashes\n\n#### CLI Command Testing\n- [ ] `aspire new` commands work as shown\n- [ ] Template names are correct\n- [ ] Output matches documentation\n\n#### Content Clarity\n- [ ] Prerequisites are clearly stated\n- [ ] Steps are in logical order\n- [ ] New users can follow without prior knowledge\n\n#### Code Example Testing\n- [ ] Example 1: Compiles and runs as described\n- [ ] Example 2: Compiles and runs as described\n```\n\n### Integration Documentation Focus\n\n```markdown\n## Focus: [Integration Name] Integration\n\n### Page: \u002Fintegrations\u002F[category]\u002F[integration]\n\n#### Package Verification\n- [ ] Hosting package exists on NuGet\n- [ ] Client package exists on NuGet (if applicable)\n- [ ] Package names match documentation\n\n#### Hosting Integration\n- [ ] Basic example compiles\n- [ ] Resource is created correctly\n- [ ] Configuration options work\n- [ ] Health checks function (if documented)\n\n#### Client Integration (if applicable)\n- [ ] Client registration works\n- [ ] Keyed services work\n- [ ] Configuration providers work\n- [ ] Connection strings work\n\n#### Cross-References\n- [ ] Links to official docs work\n- [ ] Links to related Aspire docs work\n- [ ] All internal links are site-relative with trailing slashes\n- [ ] See also section is complete\n```\n\n### Fundamentals Focus\n\n```markdown\n## Focus: [Concept Name]\n\n### Page: \u002Ffundamentals\u002F[concept]\n\n#### Conceptual Accuracy\n- [ ] Explanations match actual behavior\n- [ ] Diagrams are accurate\n- [ ] Terminology is consistent\n\n#### Code Examples\n- [ ] All examples compile\n- [ ] All examples run as described\n- [ ] Edge cases are addressed\n\n#### Completeness\n- [ ] All major features covered\n- [ ] Common use cases addressed\n- [ ] Gotchas and limitations noted\n```\n\n## Output Format\n\nAfter testing a focus area, produce a structured report:\n\n```markdown\n# Documentation Test Report\n\n**Focus Area:** [Description]\n**Date:** [ISO Date]\n**Tester:** doc-tester agent\n\n## Summary\n\n| Category | Passed | Failed | Warnings |\n|----------|--------|--------|----------|\n| Content Accuracy | X | Y | Z |\n| Code Examples | X | Y | Z |\n| CLI Commands | X | Y | Z |\n| Links | X | Y | Z |\n\n## Critical Issues\n\nIssues that make documentation misleading or incorrect.\n\n### Issue 1: [Brief Title]\n\n**Location:** [Page URL and section]\n**Type:** [Content\u002FExample\u002FCLI\u002FLink]\n**Severity:** Critical\n\n**What the documentation says:**\n> [Quote from documentation]\n\n**What actually happens:**\n> [Description of actual behavior]\n\n**Evidence:**\n[Code snippet, error message, or screenshot description]\n\n**Recommended Action:**\n- [ ] Update documentation to match behavior\n- [ ] Fix implementation to match documentation\n- [ ] Add clarifying note\n\n---\n\n## Warnings\n\nIssues that may confuse readers but aren't strictly incorrect.\n\n### Warning 1: [Brief Title]\n\n**Location:** [Page URL and section]\n**Issue:** [Description]\n**Suggestion:** [How to improve]\n\n---\n\n## Passed Checks\n\n[List of items that passed validation - brief summary]\n\n## Recommendations\n\n1. **Priority fixes:** [List critical issues to address first]\n2. **Documentation gaps:** [Missing documentation to add]\n3. **Product issues:** [Implementation bugs discovered]\n```\n\n## Test Workspace Management\n\n### Workspace Location\n\nUse `.doc-tester-workspace\u002F` in the repository root for all test projects. This directory is gitignored.\n\n```bash\n# Standard workspace structure\n.doc-tester-workspace\u002F\n├── cli-tests\u002F           # CLI command testing\n├── integration-tests\u002F   # Integration testing\n├── example-tests\u002F       # Code example testing\n└── screenshots\u002F         # Captured screenshots\n```\n\n### Cleanup\n\nAfter testing, clean up test projects:\n\n```bash\n# Remove test workspace contents\nrm -rf .doc-tester-workspace\u002F*\n```\n\nKeep the workspace directory but remove contents to avoid cluttering the repository.\n\n## Common Testing Scenarios\n\n### Testing a New Integration Doc\n\n1. Navigate to the integration page with Playwright\n2. Verify package names are correct\n3. Create a test AppHost project\n4. Add the hosting package using `aspire add \u003Cpackage-name>`\n5. Copy the basic usage example\n6. Build and run with `aspire run`\n7. Verify the resource appears in the dashboard\n8. If client integration exists, add using `aspire add` and test client registration\n\n### Testing CLI Documentation\n\n1. Navigate to the CLI reference page\n2. Copy each command example\n3. Run in a fresh directory\n4. Verify output matches documentation\n5. Test documented options and flags\n\n### Testing Getting Started Guide\n\n1. Start from a completely fresh environment (new directory)\n2. Follow every step exactly as written\n3. Do not use prior knowledge to fill gaps\n4. Document any place where you got stuck\n5. Verify final result matches what's promised\n\n## Using CLI Tools\n\n### Aspire CLI\n\nUse for checking resource status:\n\n```bash\naspire run                 # Start the app and print resource URLs\naspire ps --include-hidden # List running resources and URLs when using aspire start\naspire describe            # Inspect AppHost resources and endpoints\n```\n\n### `playwright-cli`\n\nUse for navigating and reading documentation:\n\n```bash\nplaywright-cli open \u003Curl>          # Open a browser at a URL\nplaywright-cli goto \u003Curl>          # Navigate to a URL\nplaywright-cli snapshot            # Read page content\nplaywright-cli click \u003Cref>         # Click an element from the snapshot\nplaywright-cli type \"text\"         # Type text into the active element\nplaywright-cli screenshot          # Capture a screenshot\n```\n\n### Hex1b CLI Tools\n\nThe Hex1b CLI tool provides terminal automation for interacting with terminal sessions and capturing terminal output. This is particularly useful for:\n\n- **Capturing terminal screenshots** for documentation evidence\n- **Recording terminal sessions** for documentation\n\n#### Installation\n\nInstall Hex1b.Tool if not already available:\n\n```bash\ndotnet tool install -g Hex1b.Tool\n```\n\nRefer to the **hex1b skill** for the full command reference.\n\n#### Common Commands\n\n```bash\ndotnet hex1b terminal list                              # List active terminal sessions\ndotnet hex1b terminal start -- bash                     # Start a new bash session\ndotnet hex1b terminal start -- pwsh                     # Start a new PowerShell session\ndotnet hex1b keys \u003Cid> --text \"command\"                 # Send text to terminal\ndotnet hex1b keys \u003Cid> --key Enter                      # Send a keypress\ndotnet hex1b assert \u003Cid> --text-present \"...\"           # Wait for specific output\ndotnet hex1b capture screenshot \u003Cid> --format svg       # Capture terminal as SVG\ndotnet hex1b capture screenshot \u003Cid> --format text      # Capture terminal text content\ndotnet hex1b capture recording start \u003Cid> --output \u003Cfile>.cast  # Start asciinema recording\ndotnet hex1b capture recording stop \u003Cid>                # Stop asciinema recording\ndotnet hex1b terminal stop \u003Cid>                         # Stop a terminal session\n```\n\n#### Asciinema Recordings\n\nThe aspire.dev documentation uses asciinema recordings (`.cast` files) to show terminal interactions. These provide a better user experience than static screenshots.\n\n**Existing recordings location**: `src\u002Ffrontend\u002Fpublic\u002Fcasts\u002F`\n\n**Examples of existing recordings**:\n- `aspire-version.cast` - Shows `aspire --version` command\n- `aspire-new.cast` - Shows project creation\n- `aspire-run.cast` - Shows running an Aspire app\n- `agent-init.cast` - Shows agent init command\n\nWhen testing CLI documentation, consider whether an asciinema recording would better demonstrate the command output than a static code block.\n\n## Reporting Guidelines\n\n### Issue Severity Levels\n\n| Severity | Description | Examples |\n|----------|-------------|----------|\n| **Critical** | Documentation is wrong\u002Fmisleading | Incorrect API signature, broken example |\n| **High** | Major functionality undocumented | Missing required configuration step |\n| **Medium** | Minor inaccuracy or unclear | Typo in package name, unclear explanation |\n| **Low** | Enhancement suggestion | Could add more examples, better formatting |\n\n### Evidence Requirements\n\nFor each issue, provide:\n\n1. **Exact quote** from documentation\n2. **Steps to reproduce** the discrepancy\n3. **Actual result** observed\n4. **Expected result** based on documentation\n5. **Screenshot or error message** when applicable\n\n### Hand-off to doc-writer\n\nWhen creating a task for doc-writer, include:\n\n```markdown\n## Documentation Fix Required\n\n**Page:** \u002Fpath\u002Fto\u002Fpage\n**Section:** Section heading\n\n**Current Content:**\n> [Quoted text from docs]\n\n**Problem:**\n[Description of what's wrong]\n\n**Suggested Fix:**\n[What the documentation should say]\n\n**Verification:**\n[How to verify the fix is correct]\n```\n\n## Common Issues Checklist\n\nBased on patterns from PR feedback, actively look for these common documentation issues:\n\n### Writing Quality Issues\n\n| Issue | What to Check |\n|-------|---------------|\n| **Grammatical errors** | \"Now, that you have...\" should be \"Now that you have...\" |\n| **Spelling errors** | Watch for typos like \"volumme\", \"dependenceies\", \"follwing\" |\n| **Unused imports** | Components imported but never used in the document |\n| **Casual language** | Informal phrases like \"treat yourself to a coffee\" |\n| **Duplicate content** | Similar Asides or explanations appearing multiple times |\n\n### Link Verification\n\n| Issue | What to Check |\n|-------|---------------|\n| **Broken internal links** | Links pointing to non-existent pages |\n| **Outdated paths** | `\u002Fget-started\u002Fsetup-and-tooling\u002F` should be `\u002Fget-started\u002Fprerequisites\u002F` |\n| **Anchor links** | Links to `#section-name` where the section doesn't exist |\n| **Missing redirects** | Old page paths that should redirect to new locations |\n\n### Code Example Issues\n\n| Issue | What to Check |\n|-------|---------------|\n| **Syntax errors** | `main.app` instead of `main:app` for Python uvicorn |\n| **Duplicate language identifiers** | `csharp csharp` instead of just `csharp` |\n| **Undefined variables** | Variables used in code but not defined earlier |\n| **Wrong indentation style** | Aligned indentation instead of standard 4-space |\n| **Incorrect technical descriptions** | Calling `process.env` a \"method\" (it's an object) |\n| **Deprecated APIs** | Using deprecated APIs as primary examples |\n| **Insecure defaults** | `TrustServerCertificate=true` without dev-only warnings |\n\n### Component Issues\n\n| Issue | What to Check |\n|-------|---------------|\n| **Mismatched Pivot\u002FPivotSelector** | Pivot components missing correct `key` attribute |\n| **Card text overflow** | LinkCard descriptions too long for the UI |\n| **Incorrect health check links** | Links pointing to wrong technology's health check |\n\n### Cross-Language Documentation\n\n| Issue | What to Check |\n|-------|---------------|\n| **Inconsistent resource names** | Different names used across C#\u002FPython\u002FJavaScript examples |\n| **Missing variable definitions** | Removing a section that defines variables used later |\n| **Wrong environment variable format** | Using `:` vs `__` separator for different languages |\n\n## Testing Code Examples\n\nWhen testing code examples, verify:\n\n1. **All imports\u002Fusings are present** - Code should compile without adding missing imports\n2. **Variable names match** - The connection name in client code matches the resource name in AppHost\n3. **Complete examples** - Code blocks show runnable examples, not just fragments\n4. **Correct package names** - NuGet package names are spelled correctly\n5. **Working links** - Links to external resources (GitHub, NuGet) are valid\n","# Documentation Tester Skill\n\nThis skill provides guidelines for AI agents to systematically validate the aspire.dev documentation site against the actual behavior of Aspire. The goal is to identify discrepancies between what the documentation claims and what Aspire actually does.\n\n## ⚠️ CRITICAL: User-Centric Testing Approach\n\n**You are testing the documentation as if you were a new user learning Aspire.**\n\n### Core Principles\n\n1. **Use `playwright-cli` exclusively** to browse and interact with the documentation site\n2. **Never read source code** to understand how things work - rely only on what the docs tell you\n3. **Follow the documentation literally** - copy code examples exactly as shown\n4. **Evaluate teaching effectiveness** - can you learn from this documentation?\n\n### What This Means\n\n❌ **DO NOT:**\n- Read Aspire source code to understand behavior\n- Check implementation details in the microsoft\u002Faspire repository\n- Look at test files to understand expected behavior\n- Use internal knowledge of the codebase\n- Silently fill gaps with your built-in knowledge - flag them instead\n\n✅ **DO:**\n- Use `playwright-cli` commands to navigate the documentation site\n- Read documentation content as displayed in the browser\n- Copy code examples and run them in test projects\n- Evaluate if explanations make sense without prior knowledge\n- Flag when you use intrinsic knowledge to fill documentation gaps\n\n### When You Get Stuck\n\nIf documentation is insufficient to proceed:\n\n1. **Document the blocker** - What were you trying to do? What information was missing?\n2. **Describe the gap** - What would a user need to know to succeed?\n3. **Hand off to doc-writer** - Create a task for the doc-writer skill to fix it\n4. **Move on** - Continue testing other areas\n\nThis is valuable feedback! Gaps in documentation are exactly what we're trying to find.\n\n### Knowledge Source Awareness\n\n**Be critical of the documentation by distinguishing between what you know and where that knowledge came from.**\n\nAs an AI agent, you have built-in knowledge about programming concepts, frameworks, and common patterns. When testing documentation, constantly ask yourself:\n\n#### Documentation Takes Priority\n\nThe aspire.dev documentation covers the full spectrum of the Aspire experience - from installation and project creation to advanced scenarios. **When the documentation you're testing provides instructions for a task, follow those instructions exactly, even if this skill provides different guidance.**\n\nFor example:\n- If testing a \"Getting Started\" page that shows how to create a project, use the commands in that documentation - not the project creation steps in this skill\n- If an integration doc specifies how to add packages, follow those steps rather than the general guidance here\n- The skill's instructions are defaults; the documentation being tested overrides them\n\nThis ensures you're actually testing whether the documentation works, not whether this skill's instructions work.\n\n#### Questions to Ask\n\n1. **\"Did I learn this from the documentation, or did I already know it?\"**\n   - If you already knew it, would a new user know it too?\n   - Is it reasonable to assume this knowledge, or should the docs explain it?\n\n2. **\"Am I filling in gaps with my own knowledge?\"**\n   - If you had to use prior knowledge to complete a step, the documentation may be incomplete\n   - Document these gaps even if you were able to proceed\n\n3. **\"Would this make sense to someone unfamiliar with [concept]?\"**\n   - Aspire users come from diverse backgrounds (different languages, experience levels)\n   - Don't assume familiarity with .NET, containers, cloud concepts, etc.\n\n#### Examples\n\n| Situation | Question to Ask | Documentation Gap? |\n|-----------|-----------------|-------------------|\n| You know what a connection string is | Would a Python developer know this? | Maybe - consider if it needs explanation |\n| You understand dependency injection | Does the doc explain DI or assume it? | If assumed, should link to prerequisites |\n| You know `aspire run` starts all resources | Did the doc say this, or did you just know? | If not stated, it should be |\n| You recognize a Redis configuration pattern | Is this explained or assumed knowledge? | New users may not recognize it |\n\n#### Reporting Knowledge Gaps\n\nWhen you identify that you used intrinsic knowledge to proceed, flag it in your report:\n\n```markdown\n### Knowledge Gap: [Topic]\n\n**What I needed to know:** [Description]\n**Source of my knowledge:** Built-in\u002Fprior knowledge (NOT from documentation)\n**User impact:** [Who might struggle without this knowledge?]\n**Recommendation:** \n- [ ] Add explanation to this page\n- [ ] Link to prerequisite documentation\n- [ ] Reasonable to assume (explain why)\n```\n\n## Testing Goals\n\n### 1. Teaching Effectiveness\n\nCan someone learn Aspire from these docs alone?\n\n- Are concepts introduced in a logical order?\n- Are prerequisites clearly stated?\n- Do examples build on each other progressively?\n- Is terminology explained before being used?\n- Are common mistakes or gotchas addressed?\n\n### 2. Accuracy & Correctness\n\nDoes the documentation match reality?\n\n- Do code examples compile and run?\n- Are API signatures and parameters correct?\n- Do claimed features actually exist?\n- Are limitations and caveats documented?\n\n## Environment Setup\n\n### Installing the Aspire CLI\n\nBefore testing, ensure you have the appropriate version of the Aspire CLI installed. The version needed depends on what you're testing:\n\n#### GA\u002FStable Builds (Default)\n\nFor testing documentation of released features, use the stable release:\n\n```bash\n# Linux\u002FmacOS\ncurl -sSL https:\u002F\u002Faspire.dev\u002Finstall.sh | bash\n\n# Windows (PowerShell)\nirm https:\u002F\u002Faspire.dev\u002Finstall.ps1 | iex\n```\n\nFor complete installation instructions, see the [Install Aspire CLI](\u002Fget-started\u002Finstall-cli\u002F) page on the documentation site.\n\n#### Nightly\u002FDev Builds\n\nFor testing documentation of features being developed on the main branch, use the dev channel:\n\n```bash\n# Linux\u002FmacOS\ncurl -sSL https:\u002F\u002Faspire.dev\u002Finstall.sh | bash -s -- --quality dev\n\n# Windows (PowerShell)\niex \"& { $(irm https:\u002F\u002Faspire.dev\u002Finstall.ps1) } -Quality 'dev'\"\n```\n\nYou can also find the dev channel option by clicking the download icon on the aspire.dev site and selecting \"Dev\" from the Channel dropdown.\n\n\u003CAside type=\"caution\">\nDev builds are the latest from the main branch and may be unstable. Only use for testing upcoming features.\n\u003C\u002FAside>\n\n#### PR Builds\n\nFor testing documentation of features in specific pull requests (before they're merged), you need to install the CLI from the PR artifacts:\n\n1. Navigate to the PR in the [microsoft\u002Faspire](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire) repository\n2. Find the \"Checks\" or \"Actions\" section of the PR\n3. Look for the build artifacts that contain the CLI\n4. Download and install the CLI from the PR-specific build artifacts\n\nPR builds are useful when writing documentation ahead of feature merges.\n\n#### Staging Builds\n\nFor testing prerelease builds from the current release branch:\n\n```bash\n# Linux\u002FmacOS\ncurl -sSL https:\u002F\u002Faspire.dev\u002Finstall.sh | bash -s -- --quality staging\n\n# Windows (PowerShell)\niex \"& { $(irm https:\u002F\u002Faspire.dev\u002Finstall.ps1) } -Quality 'staging'\"\n```\n\n### Aspire App Model\n\nThe aspire.dev workspace uses Aspire to orchestrate local services. The app model in `apphost.cs` defines the documentation site resources. Use the Aspire CLI output or dashboard resource list to get the current resource states and URLs.\n\n### Starting the Local Environment\n\n⚠️ **CRITICAL: Terminal Isolation**\n\nAspire must run in an **isolated background process** to avoid interference with other terminal commands.\n\n**Start Aspire:**\n\n```bash\ncd \u002Fpath\u002Fto\u002Faspire.dev\naspire run\n```\n\nUse the Aspire CLI output or dashboard resource list to get the content URL. Look for the `frontend` resource endpoint URL, for example `http:\u002F\u002Ffrontend.dev.localhost:5000`.\n\n**IMPORTANT**: Use the local frontend URL for all testing, not https:\u002F\u002Faspire.dev\n\n### Creating Test Projects\n\nTo test code examples accurately, create test projects using the Aspire CLI.\n\n```bash\n# Create a test directory in the workspace\nmkdir -p .doc-tester-workspace\ncd .doc-tester-workspace\n\n# Create a new Aspire project using templates\naspire new aspire-starter -n DocTest -o DocTest\ncd DocTest\n```\n\nUse `aspire new --list` to see all available project templates. Choose a template that matches the documentation you're testing (e.g., Python, JavaScript, or .NET projects).\n\n## Purpose\n\nThe doc-tester agent produces actionable feedback that can:\n1. Trigger the **doc-writer** skill to correct documentation inaccuracies\n2. Identify product design issues that need to be addressed in Aspire\n3. Surface missing documentation for existing features\n4. Find broken examples or outdated instructions\n\n## Scope\n\n### What to Test\n\n| Area | Description |\n|------|-------------|\n| **Conceptual accuracy** | Do explanations match actual Aspire behavior? |\n| **Code examples** | Do code samples compile and run as described? |\n| **CLI commands** | Do Aspire CLI commands work as documented? |\n| **Integration docs** | Are integration configurations accurate? |\n| **Navigation & links** | Do internal links work? Are pages accessible? Do they follow link format conventions? |\n| **Feature coverage** | Are all significant features documented? |\n\n### Link Validation Rules\n\nWhen testing any page, verify that **all internal links** follow these conventions:\n\n1. **Site-relative paths**: Internal links must start with `\u002F` (not relative paths like `..\u002F` except within the same integration section)\n2. **Trailing slash required**: All internal links must end with `\u002F` (e.g., `\u002Fget-started\u002Ffirst-app\u002F` not `\u002Fget-started\u002Ffirst-app`)\n3. **Anchor links**: Hash links to sections on the same page (e.g., `#configuration`) are fine without a trailing slash\n4. **Valid targets**: Every internal link must point to a page that actually exists in the docs\n5. **No broken anchors**: Section anchor links (e.g., `\u002Fpage\u002F#section-name`) must reference an actual heading on the target page\n\n**How to validate links:**\n- Extract all `[text](url)` and `href=\"url\"` patterns from the page source\n- For site-relative links, verify the target `.mdx` file exists under `src\u002Ffrontend\u002Fsrc\u002Fcontent\u002Fdocs\u002F`\n- For links with anchors, verify the heading exists on the target page\n- Use Playwright to click links and verify they resolve (no 404s)\n\n### Documentation Structure\n\nThe documentation site includes:\n\n```\n\u002F                           # Landing page\n\u002Fget-started\u002F               # Getting started guides\n    prerequisites\n    install-cli\n    first-app\n    app-host\n    deploy-first-app\n    ...\n\u002Ffundamentals\u002F             # Core concepts\n    app-host\n    networking-overview\n    service-defaults\n    ...\n\u002Fintegrations\u002F             # Per-integration documentation\n    databases\u002F\n    caching\u002F\n    messaging\u002F\n    ai\u002F\n    ...\n\u002Fdeployment\u002F               # Deployment guides\n\u002Fdiagnostics\u002F              # Diagnostics and telemetry\n\u002Fdashboard\u002F                # Dashboard documentation\n\u002Ftesting\u002F                  # Testing guides\n\u002Freference\u002F                # API and CLI reference\n\u002Fwhats-new\u002F                # Release notes\n```\n\n## Testing Workflow\n\n**All browser-based testing uses `playwright-cli` to interact with the documentation site.**\n\n### Phase 0: Environment Preparation\n\n1. **Start Aspire**: Run `aspire run` from the repository root\n2. **Get frontend URL**: Use the Aspire CLI output or dashboard resource list to find the `frontend` endpoint\n3. **Note the URL**: The script outputs the local development URL\n\n### Phase 1: Navigate and Read Documentation (Playwright)\n\nUse `playwright-cli` to browse the documentation:\n\n```bash\n# Open the local docs site\nplaywright-cli open http:\u002F\u002Ffrontend.dev.localhost:5000\n\n# Take an accessibility snapshot to read page content\nplaywright-cli snapshot\n\n# Navigate to a page by clicking a ref from the snapshot\nplaywright-cli click e42\n\n# Read page content\nplaywright-cli snapshot\n```\n\nFor each documentation page:\n\n1. **Navigate to the page** using Playwright click actions\n2. **Take a snapshot** to read the page content\n3. **Evaluate the content** - Is it clear? Complete? Accurate?\n4. **Note any confusion** - What would a new user struggle with?\n5. **Inspect current-version references in the source MDX** - Rendered pages\n   show the replaced value, so confirm that current guidance uses the shared\n   placeholders rather than a hard-coded Aspire version:\n   - `%ASPIRE_VERSION%` for the full current stable version\n   - `%ASPIRE_VERSION_MAJOR_MINOR%` for the current major\u002Fminor version\n\nFlag hard-coded Aspire versions in current installation instructions, package\nreferences, AppHost SDK declarations, CLI output, and copy\u002Fpaste examples.\nKeep fixed versions when the exact version is intentional, such as release\nnotes, upgrade comparisons, minimum-version requirements, compatibility notes,\nor issue reproduction steps.\n\n### Phase 2: Test CLI Commands\n\nFor CLI commands shown in the documentation:\n\n1. **Copy the command exactly** as shown in the browser\n2. **Run the command** in the terminal\n3. **Verify output** - Does it match what the docs describe?\n4. **Test variations** - Do optional parameters work as documented?\n\n#### Example: Testing aspire new\n\n```bash\n# Create a test directory\ncd \u002Fpath\u002Fto\u002Faspire.dev\u002F.doc-tester-workspace\nmkdir -p cli-tests && cd cli-tests\n\n# Test the command from documentation\naspire new aspire-starter -n TestApp -o TestApp\n\n# Verify the output matches documentation claims\nls TestApp\u002F\n```\n\n### Phase 3: Test Code Examples\n\nFor each code example shown in the documentation:\n\n1. **Copy the code exactly** as shown in the browser\n2. **Create a test project** in the workspace directory\n3. **Build the code** - does it compile without errors?\n4. **Run and observe** - does it behave as documented?\n\n#### Step 1: Create Test Project\n\n```bash\n# Navigate to workspace\ncd \u002Fpath\u002Fto\u002Faspire.dev\u002F.doc-tester-workspace\n\n# Create a project using an appropriate Aspire template\naspire new aspire-starter -n ExampleTest -o ExampleTest\ncd ExampleTest\n```\n\nUse `aspire new --list` to view available templates. Choose a template that matches the language or framework in the documentation you're testing.\n\n#### Step 2: Add Required Packages\n\nBased on the documentation being tested, use the Aspire CLI to add integration packages:\n\n```bash\n# Add hosting packages using Aspire CLI (preferred)\naspire add Aspire.Hosting.Redis\n\n# Or add client packages\naspire add Aspire.StackExchange.Redis\n```\n\n\u003CAside type=\"tip\">\nThe `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.\n\u003C\u002FAside>\n\n#### Step 3: Apply Code Examples\n\nCopy the code examples from the documentation into your test project exactly as shown. This may involve:\n- Updating source files (e.g., `Program.cs`, `app.py`, `server.js`)\n- Adding configuration files\n- Any other steps the documentation specifies\n\n\u003CAside type=\"note\">\nAspire 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.\n\u003C\u002FAside>\n\n#### Step 4: Run and Verify\n\nUse `aspire run` to build and run the application:\n\n```bash\naspire run\n```\n\nAspire handles building and orchestrating all resources. If the documentation specifies additional build or run commands for specific languages, follow those instructions and verify they work as documented.\n\n### Phase 4: Test Integration Documentation\n\nFor integration documentation:\n\n1. **Verify package installation** - Does the documented package exist?\n2. **Test basic usage** - Does the minimal example work?\n3. **Test configuration** - Do configuration options work as described?\n4. **Check health checks** - Do documented health checks function?\n\n```bash\n# Verify package exists using Aspire CLI\naspire add Aspire.Hosting.Technology\n\n# If package not found, document as error\n```\n\n### Phase 5: Evaluate Teaching Effectiveness\n\nAs you navigate, evaluate:\n\n1. **Concept flow** - Are ideas introduced in a logical order?\n2. **Prerequisites** - Is prior knowledge clearly stated?\n3. **Completeness** - Can you accomplish tasks with just the docs?\n4. **Clarity** - Would a new user understand this?\n\n**When you get stuck:**\n- Document what you were trying to do\n- Note what information was missing\n- This becomes a doc-writer task\n\n## Focus Area Templates\n\nWhen given a focus area, use these templates to guide testing:\n\n### Getting Started Focus\n\n```markdown\n## Focus: Getting Started Guide\n\n### Page: \u002Fget-started\u002F[page-name]\n\n#### Navigation (Playwright)\n- [ ] Page loads successfully\n- [ ] All sections visible in snapshot\n- [ ] Code examples readable\n- [ ] Links to related pages work\n- [ ] All internal links are site-relative with trailing slashes\n\n#### CLI Command Testing\n- [ ] `aspire new` commands work as shown\n- [ ] Template names are correct\n- [ ] Output matches documentation\n\n#### Content Clarity\n- [ ] Prerequisites are clearly stated\n- [ ] Steps are in logical order\n- [ ] New users can follow without prior knowledge\n\n#### Code Example Testing\n- [ ] Example 1: Compiles and runs as described\n- [ ] Example 2: Compiles and runs as described\n```\n\n### Integration Documentation Focus\n\n```markdown\n## Focus: [Integration Name] Integration\n\n### Page: \u002Fintegrations\u002F[category]\u002F[integration]\n\n#### Package Verification\n- [ ] Hosting package exists on NuGet\n- [ ] Client package exists on NuGet (if applicable)\n- [ ] Package names match documentation\n\n#### Hosting Integration\n- [ ] Basic example compiles\n- [ ] Resource is created correctly\n- [ ] Configuration options work\n- [ ] Health checks function (if documented)\n\n#### Client Integration (if applicable)\n- [ ] Client registration works\n- [ ] Keyed services work\n- [ ] Configuration providers work\n- [ ] Connection strings work\n\n#### Cross-References\n- [ ] Links to official docs work\n- [ ] Links to related Aspire docs work\n- [ ] All internal links are site-relative with trailing slashes\n- [ ] See also section is complete\n```\n\n### Fundamentals Focus\n\n```markdown\n## Focus: [Concept Name]\n\n### Page: \u002Ffundamentals\u002F[concept]\n\n#### Conceptual Accuracy\n- [ ] Explanations match actual behavior\n- [ ] Diagrams are accurate\n- [ ] Terminology is consistent\n\n#### Code Examples\n- [ ] All examples compile\n- [ ] All examples run as described\n- [ ] Edge cases are addressed\n\n#### Completeness\n- [ ] All major features covered\n- [ ] Common use cases addressed\n- [ ] Gotchas and limitations noted\n```\n\n## Output Format\n\nAfter testing a focus area, produce a structured report:\n\n```markdown\n# Documentation Test Report\n\n**Focus Area:** [Description]\n**Date:** [ISO Date]\n**Tester:** doc-tester agent\n\n## Summary\n\n| Category | Passed | Failed | Warnings |\n|----------|--------|--------|----------|\n| Content Accuracy | X | Y | Z |\n| Code Examples | X | Y | Z |\n| CLI Commands | X | Y | Z |\n| Links | X | Y | Z |\n\n## Critical Issues\n\nIssues that make documentation misleading or incorrect.\n\n### Issue 1: [Brief Title]\n\n**Location:** [Page URL and section]\n**Type:** [Content\u002FExample\u002FCLI\u002FLink]\n**Severity:** Critical\n\n**What the documentation says:**\n> [Quote from documentation]\n\n**What actually happens:**\n> [Description of actual behavior]\n\n**Evidence:**\n[Code snippet, error message, or screenshot description]\n\n**Recommended Action:**\n- [ ] Update documentation to match behavior\n- [ ] Fix implementation to match documentation\n- [ ] Add clarifying note\n\n---\n\n## Warnings\n\nIssues that may confuse readers but aren't strictly incorrect.\n\n### Warning 1: [Brief Title]\n\n**Location:** [Page URL and section]\n**Issue:** [Description]\n**Suggestion:** [How to improve]\n\n---\n\n## Passed Checks\n\n[List of items that passed validation - brief summary]\n\n## Recommendations\n\n1. **Priority fixes:** [List critical issues to address first]\n2. **Documentation gaps:** [Missing documentation to add]\n3. **Product issues:** [Implementation bugs discovered]\n```\n\n## Test Workspace Management\n\n### Workspace Location\n\nUse `.doc-tester-workspace\u002F` in the repository root for all test projects. This directory is gitignored.\n\n```bash\n# Standard workspace structure\n.doc-tester-workspace\u002F\n├── cli-tests\u002F           # CLI command testing\n├── integration-tests\u002F   # Integration testing\n├── example-tests\u002F       # Code example testing\n└── screenshots\u002F         # Captured screenshots\n```\n\n### Cleanup\n\nAfter testing, clean up test projects:\n\n```bash\n# Remove test workspace contents\nrm -rf .doc-tester-workspace\u002F*\n```\n\nKeep the workspace directory but remove contents to avoid cluttering the repository.\n\n## Common Testing Scenarios\n\n### Testing a New Integration Doc\n\n1. Navigate to the integration page with Playwright\n2. Verify package names are correct\n3. Create a test AppHost project\n4. Add the hosting package using `aspire add \u003Cpackage-name>`\n5. Copy the basic usage example\n6. Build and run with `aspire run`\n7. Verify the resource appears in the dashboard\n8. If client integration exists, add using `aspire add` and test client registration\n\n### Testing CLI Documentation\n\n1. Navigate to the CLI reference page\n2. Copy each command example\n3. Run in a fresh directory\n4. Verify output matches documentation\n5. Test documented options and flags\n\n### Testing Getting Started Guide\n\n1. Start from a completely fresh environment (new directory)\n2. Follow every step exactly as written\n3. Do not use prior knowledge to fill gaps\n4. Document any place where you got stuck\n5. Verify final result matches what's promised\n\n## Using CLI Tools\n\n### Aspire CLI\n\nUse for checking resource status:\n\n```bash\naspire run                 # Start the app and print resource URLs\naspire ps --include-hidden # List running resources and URLs when using aspire start\naspire describe            # Inspect AppHost resources and endpoints\n```\n\n### `playwright-cli`\n\nUse for navigating and reading documentation:\n\n```bash\nplaywright-cli open \u003Curl>          # Open a browser at a URL\nplaywright-cli goto \u003Curl>          # Navigate to a URL\nplaywright-cli snapshot            # Read page content\nplaywright-cli click \u003Cref>         # Click an element from the snapshot\nplaywright-cli type \"text\"         # Type text into the active element\nplaywright-cli screenshot          # Capture a screenshot\n```\n\n### Hex1b CLI Tools\n\nThe Hex1b CLI tool provides terminal automation for interacting with terminal sessions and capturing terminal output. This is particularly useful for:\n\n- **Capturing terminal screenshots** for documentation evidence\n- **Recording terminal sessions** for documentation\n\n#### Installation\n\nInstall Hex1b.Tool if not already available:\n\n```bash\ndotnet tool install -g Hex1b.Tool\n```\n\nRefer to the **hex1b skill** for the full command reference.\n\n#### Common Commands\n\n```bash\ndotnet hex1b terminal list                              # List active terminal sessions\ndotnet hex1b terminal start -- bash                     # Start a new bash session\ndotnet hex1b terminal start -- pwsh                     # Start a new PowerShell session\ndotnet hex1b keys \u003Cid> --text \"command\"                 # Send text to terminal\ndotnet hex1b keys \u003Cid> --key Enter                      # Send a keypress\ndotnet hex1b assert \u003Cid> --text-present \"...\"           # Wait for specific output\ndotnet hex1b capture screenshot \u003Cid> --format svg       # Capture terminal as SVG\ndotnet hex1b capture screenshot \u003Cid> --format text      # Capture terminal text content\ndotnet hex1b capture recording start \u003Cid> --output \u003Cfile>.cast  # Start asciinema recording\ndotnet hex1b capture recording stop \u003Cid>                # Stop asciinema recording\ndotnet hex1b terminal stop \u003Cid>                         # Stop a terminal session\n```\n\n#### Asciinema Recordings\n\nThe aspire.dev documentation uses asciinema recordings (`.cast` files) to show terminal interactions. These provide a better user experience than static screenshots.\n\n**Existing recordings location**: `src\u002Ffrontend\u002Fpublic\u002Fcasts\u002F`\n\n**Examples of existing recordings**:\n- `aspire-version.cast` - Shows `aspire --version` command\n- `aspire-new.cast` - Shows project creation\n- `aspire-run.cast` - Shows running an Aspire app\n- `agent-init.cast` - Shows agent init command\n\nWhen testing CLI documentation, consider whether an asciinema recording would better demonstrate the command output than a static code block.\n\n## Reporting Guidelines\n\n### Issue Severity Levels\n\n| Severity | Description | Examples |\n|----------|-------------|----------|\n| **Critical** | Documentation is wrong\u002Fmisleading | Incorrect API signature, broken example |\n| **High** | Major functionality undocumented | Missing required configuration step |\n| **Medium** | Minor inaccuracy or unclear | Typo in package name, unclear explanation |\n| **Low** | Enhancement suggestion | Could add more examples, better formatting |\n\n### Evidence Requirements\n\nFor each issue, provide:\n\n1. **Exact quote** from documentation\n2. **Steps to reproduce** the discrepancy\n3. **Actual result** observed\n4. **Expected result** based on documentation\n5. **Screenshot or error message** when applicable\n\n### Hand-off to doc-writer\n\nWhen creating a task for doc-writer, include:\n\n```markdown\n## Documentation Fix Required\n\n**Page:** \u002Fpath\u002Fto\u002Fpage\n**Section:** Section heading\n\n**Current Content:**\n> [Quoted text from docs]\n\n**Problem:**\n[Description of what's wrong]\n\n**Suggested Fix:**\n[What the documentation should say]\n\n**Verification:**\n[How to verify the fix is correct]\n```\n\n## Common Issues Checklist\n\nBased on patterns from PR feedback, actively look for these common documentation issues:\n\n### Writing Quality Issues\n\n| Issue | What to Check |\n|-------|---------------|\n| **Grammatical errors** | \"Now, that you have...\" should be \"Now that you have...\" |\n| **Spelling errors** | Watch for typos like \"volumme\", \"dependenceies\", \"follwing\" |\n| **Unused imports** | Components imported but never used in the document |\n| **Casual language** | Informal phrases like \"treat yourself to a coffee\" |\n| **Duplicate content** | Similar Asides or explanations appearing multiple times |\n\n### Link Verification\n\n| Issue | What to Check |\n|-------|---------------|\n| **Broken internal links** | Links pointing to non-existent pages |\n| **Outdated paths** | `\u002Fget-started\u002Fsetup-and-tooling\u002F` should be `\u002Fget-started\u002Fprerequisites\u002F` |\n| **Anchor links** | Links to `#section-name` where the section doesn't exist |\n| **Missing redirects** | Old page paths that should redirect to new locations |\n\n### Code Example Issues\n\n| Issue | What to Check |\n|-------|---------------|\n| **Syntax errors** | `main.app` instead of `main:app` for Python uvicorn |\n| **Duplicate language identifiers** | `csharp csharp` instead of just `csharp` |\n| **Undefined variables** | Variables used in code but not defined earlier |\n| **Wrong indentation style** | Aligned indentation instead of standard 4-space |\n| **Incorrect technical descriptions** | Calling `process.env` a \"method\" (it's an object) |\n| **Deprecated APIs** | Using deprecated APIs as primary examples |\n| **Insecure defaults** | `TrustServerCertificate=true` without dev-only warnings |\n\n### Component Issues\n\n| Issue | What to Check |\n|-------|---------------|\n| **Mismatched Pivot\u002FPivotSelector** | Pivot components missing correct `key` attribute |\n| **Card text overflow** | LinkCard descriptions too long for the UI |\n| **Incorrect health check links** | Links pointing to wrong technology's health check |\n\n### Cross-Language Documentation\n\n| Issue | What to Check |\n|-------|---------------|\n| **Inconsistent resource names** | Different names used across C#\u002FPython\u002FJavaScript examples |\n| **Missing variable definitions** | Removing a section that defines variables used later |\n| **Wrong environment variable format** | Using `:` vs `__` separator for different languages |\n\n## Testing Code Examples\n\nWhen testing code examples, verify:\n\n1. **All imports\u002Fusings are present** - Code should compile without adding missing imports\n2. **Variable names match** - The connection name in client code matches the resource name in AppHost\n3. **Complete examples** - Code blocks show runnable examples, not just fragments\n4. **Correct package names** - NuGet package names are spelled correctly\n5. **Working links** - Links to external resources (GitHub, NuGet) are valid\n",{"name":5,"description":7},"main","f05f5561b1b858344124cd848ff06469627d7e6e",".agents\u002Fskills\u002Fdoc-tester",99,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire.dev","https:\u002F\u002Faspire.dev","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-14 02:36:13",{"source":8,"skillName":5,"commands":56,"prompt":66,"zipAvailable":67},[57,60,63],{"tool":58,"command":59},"npx","npx skills add microsoft\u002Faspire.dev --skill doc-tester",{"tool":61,"command":62},"bunx","bunx skills add microsoft\u002Faspire.dev --skill doc-tester",{"tool":64,"command":65},"pnpm","pnpm dlx skills add microsoft\u002Faspire.dev --skill doc-tester","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire.dev\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fdoc-tester\u002FSKILL.md",true,[],[70,100,139,159,175,192],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":81,"publishedAt":40},"01M69B8W7K62DJP002TEBRZDTC","getting-started-with-aspire","Use this skill when a developer asks how to begin using Aspire — installing the Aspire CLI, creating a new Aspire app, running it locally, or finding the authoritative docs, integration catalog, or API reference on aspire.dev. Use it for questions like \"how do I install aspire?\", \"how do I create a new aspire app?\", \"how do I run my aspire app?\", or \"where is the documentation for aspire?\". Do not use it for operating an existing Aspire AppHost (use the official `aspire` skill at github.com\u002Fmicrosoft\u002Faspire\u002Ftree\u002Fmain\u002F.agents\u002Fskills\u002Faspire), authoring AppHost code, or adding integrations to an existing app.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire.dev\u002Fblob\u002Fmain\u002Fsrc\u002Ffrontend\u002Fpublic\u002F.well-known\u002Fagent-skills\u002Fgetting-started-with-aspire\u002FSKILL.md",[76],{"categoryNo":77,"categoryName":78,"taxonomyType":79,"taxonomyTypeDesc":80},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[31,82,83,84,85,86,87,9,88,32,89,90,91,92,93,94,45,95,96,97,98,39,99],"getting started with aspire","getting started","with","cli","docs","github","official","create","run","code","api","how","install","app","how to","operating","at","new",{"skillNo":101,"name":102,"nameZh":6,"description":103,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":104,"categories":105,"keywords":118,"publishedAt":40},"01M69B8R4MPE6HAYDV46VBB40J","whatsnew","Step-argument skill that formalizes writing an Aspire \"What's new in N.N\" release-notes page (src\u002Ffrontend\u002Fsrc\u002Fcontent\u002Fdocs\u002Fwhats-new\u002Faspire-N-N.mdx) as a repeatable lifecycle. Invoke as `\u002Fwhatsnew {modality}` where modality is one of: draft\u002Fscaffold (init), research, critique, validate, polish, review. USE FOR: start\u002Fscaffold a new what's-new page for a release, research a release's changes into a dossier and author the draft prose, critique a draft, fact-check\u002Fvalidate the diff, polish and run data ingestion, or sign off the PR. DO NOT USE FOR: general docs pages (use doc-writer), reviewing an arbitrary docs PR (use doc-pr-reviewer), or product-repo changes. ORCHESTRATES: doc-writer, doc-pr-reviewer, doc-tester, twoslash-validator, update-integrations, update-samples, container-images.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire.dev\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwhatsnew\u002FSKILL.md",[106,109,112,115],{"categoryNo":107,"categoryName":108,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":110,"categoryName":111,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":113,"categoryName":114,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000021","资料检索与研究",{"categoryNo":116,"categoryName":117,"taxonomyType":79,"taxonomyTypeDesc":80},"01JBSEEDCAT000000000000036","内容创作者",[102,119,120,121,86,122,123,124,125,31,126,127,90,128,129,130,131,132,133,134,135,136,137,138,99],"frontend","writing","review","research","init","validate","scaffold","notes","pr","update","release-notes","product","critique","reviewer","ingestion","images","writer","argument","validator","invoke",{"skillNo":140,"name":141,"nameZh":6,"description":142,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":143,"categories":144,"keywords":148,"publishedAt":40},"01M69B8ND3PR8M9EEKC2TQ94G2","update-samples","Update the samples data file by fetching sample metadata from the microsoft\u002Faspire-samples GitHub repository. Use when adding new samples, refreshing sample data, or ensuring samples.json stays in sync with the upstream repo.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire.dev\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fupdate-samples\u002FSKILL.md",[145],{"categoryNo":146,"categoryName":147,"taxonomyType":79,"taxonomyTypeDesc":80},"01JBSEEDCAT000000000000033","数据分析师",[149,128,87,9,150,31,151,152,153,154,155,156,35,157,158,84,39,99],"update samples","sync","metadata","file","repository","data","json","repo","upstream","sample",{"skillNo":160,"name":161,"nameZh":6,"description":162,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":163,"categories":164,"keywords":166,"publishedAt":40},"01M69B8JC3YJKYZFC0BX9N47SC","update-integrations","Update integration documentation links and API reference data by synchronizing NuGet package names with their documentation URLs and generating per-package API schemas. Use when adding new integrations, refreshing package data, ensuring integration-docs.json stays in sync with aspire-integrations.json, or regenerating API reference JSON files.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire.dev\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fupdate-integrations\u002FSKILL.md",[165],{"categoryNo":146,"categoryName":147,"taxonomyType":79,"taxonomyTypeDesc":80},[167,128,168,86,150,31,32,169,170,171,154,92,155,35,172,173,84,174,39,99],"update integrations","integrations","nuget","package","integration","reference","files","links",{"skillNo":176,"name":177,"nameZh":6,"description":178,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":179,"categories":180,"keywords":181,"publishedAt":40},"01M69B8F4MQJEG381FDZZ32AW4","twoslash-validator","Validate and fix two-slash TypeScript examples for aspire.dev. Use when adding or editing `twoslash` code fences, TypeScript AppHost samples, generated TypeScript API data, or failures from `bun run test:unit:twoslash-blocks`.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire.dev\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Ftwoslash-validator\u002FSKILL.md",[],[182,137,183,184,124,31,90,91,185,33,92,186,187,188,35,189,190,191,37,39],"twoslash validator","typescript","test","dev","editing","generated","fix","bun","unit","blocks",{"skillNo":193,"name":194,"nameZh":6,"description":195,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":196,"categories":197,"keywords":199,"publishedAt":40},"01M69B8CEPDW2FFXZ89YE4F4T3","playwright-cli","Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire.dev\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fplaywright-cli\u002FSKILL.md",[198],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[85,200,201,30,202,184,203,204,154,205,35,206,207,208,209,210,211,84,37,212,39],"playwright","playwright cli","screenshots","web","browser","applications","take","test web","forms","pages","form","information","navigate"]