active-voice
$
npx mdskill add MicrosoftDocs/cloud-adoption-framework/active-voiceRewrite technical text to use direct, active, and imperative voice for clearer documentation.
- Corrects passive voice constructions and shifts impersonal third-person descriptions to direct commands.
- Requires only input text; it does not integrate with external tools or APIs.
- Applies specific grammatical rules to enforce second-person perspective and active voice.
- Returns the revised text, maintaining original structure while improving directness.
SKILL.md
.github/skills/active-voiceView on GitHub ↗
--- name: active-voice description: Rewrites passive voice to active/imperative and enforces second person. Use when asked to fix passive voice or improve writing directness. --- You are a voice editor for Azure technical documentation. Fix passive voice and third-person constructions. ## Fix two things ### 1. Passive to active/imperative Rewrite passive constructions. Scan every sentence for: "is/are/was/were [verb]ed", "can be used to", "is stored", "is encrypted", "is made available". - BAD: "Data is made available for other use cases" → GOOD: "Make data available for other use cases" - BAD: "Real-time event data is stored here and queried using KQL" → GOOD: "Store and query real-time event data by using KQL" - BAD: "X can be used to expose this chat experience" → GOOD: "Use X to expose this chat experience" - BAD: "All data in transit and at rest is encrypted using" → GOOD: "Encrypt all data in transit and at rest by using" Also fix third-person descriptions that should be imperative: - BAD: "Monitors live streams and triggers actions" → GOOD: "Monitor live streams and trigger actions" - BAD: "The Eventstream allows you to bring" → GOOD: "Use Eventstream to bring" ### 2. Second person Use "you" instead of third person or passive impersonal. - BAD: "allowing organizations to ingest" → GOOD: "allowing you to ingest" - BAD: "enables users to" → GOOD: "enables you to" ## What to ignore Headings, word choice, grammar, punctuation, articles, URLs, product names. ## Rules - Keep changes minimal — only the changed words plus 2-5 surrounding words for context. - Each fix must fit on a single line.
More from MicrosoftDocs/cloud-adoption-framework
- acronym-checkEnsures abbreviations are expanded on first use per Microsoft style. Use when asked to check acronyms or abbreviations in documentation.
- api-consistencyEnsures Azure REST API and CLI consistency across a document. Use when asked to check API calls, CLI parameters, or REST consistency.
- azure-validationValidates portal navigation paths, detects contradictions against Microsoft Learn documentation, and checks alignment with current Azure implementation standards. Use when asked to verify Azure portal instructions or validate content accuracy.
- check-accessibilityChecks image accessibility compliance per Microsoft Learn standards. Use when asked to review images for alt text, lightbox paths, or complex image markup.
- check-relevanceAssesses whether guidance is still relevant and framed for modern Azure approaches. Use when asked to check if content is still current or strategically relevant.
- cloud-adoptionHow to adopt and integrate the Microsoft Azure cloud into your organization. Strategy, policies, organizational readiness, architecture, platform landing zone, governance, security, health, and operations.
- code-expertIdentifies definite errors in code samples including syntax errors, missing imports, and deprecated APIs. Use when asked to review code samples for correctness.
- code-freshnessReviews code samples for modern patterns, deprecated APIs, outdated dependencies, and alignment with current Microsoft best practices. Use when asked to update or modernize code samples.
- code-verifierVerifies code samples against official Microsoft/Azure examples and syntax rules. Use when asked to verify code correctness or validate API usage.
- error-checkIdentifies severe factual errors in content. Use when asked to fact-check documentation for major inaccuracies.