Adev Writing Guide
Author or review Angular `adev` docs so agents follow Google technical writing standards and Angular-specific markdown and components.
Overview
adev-writing-guide is an agent skill for the Build phase that authors and reviews Angular adev documentation using Google technical writing standards and Angular-specific markdown.
Install
npx skills add https://github.com/angular/angular --skill adev-writing-guideWhat is this skill?
- Enforces Google Technical Writing tone, accessibility, and American English grammar for global readers
- Requires second person, active voice, audience-first task focus, and descriptive link text
- Covers Angular-specific markdown extensions, code blocks, and documentation components
- Mandatory whenever creating, editing, or reviewing files under `adev/` or `adev/src/content`
Adoption & trust: 903 installs on skills.sh; 100k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are editing Angular adev content and need consistent tone, grammar, and component usage instead of generic LLM prose.
Who is it for?
Contributors or agents editing `adev/src/content` for Angular in a git-backed docs repo.
Skip if: Non-Angular product docs, marketing copy outside adev, or code-only changes with no documentation files.
When should I use this skill?
Any time you plan to create, edit, or review documentation files in `adev/` or `adev/src/content`.
What do I get? / Deliverables
Documentation drafts and reviews align with Google style and Angular adev conventions before merge.
- Revised adev Markdown pages
- Doc review feedback aligned to Google and Angular rules
Recommended Skills
Journey fit
Documentation for the Angular dev site is produced during the build phase as part of shipping framework guides and reference content. The skill is scoped to `adev/` and `adev/src/content`—pure documentation authoring and review, not app code.
How it compares
Use instead of generic “write good docs” prompts when the target is Angular’s adev site.
Common Questions / FAQ
Who is adev-writing-guide for?
Solo builders, doc contributors, and agents that create or review Markdown and components under Angular’s adev content directory.
When should I use adev-writing-guide?
Use it in the Build phase whenever you plan, draft, or review documentation in `adev/` or `adev/src/content`, including tutorial rewrites and PR review of doc-only changes.
Is adev-writing-guide safe to install?
It is editorial guidance only—review the Security Audits panel on this skill’s Prism page before adding any skill to your agent workflow.
SKILL.md
READMESKILL.md - Adev Writing Guide
# Angular Documentation (adev) Writing Guide This skill provides comprehensive guidelines for authoring content in `adev/src/content`. It combines Google's technical writing standards with Angular-specific markdown conventions, components, and best practices. ## I. Google Technical Writing Guidelines ### Tone and Content - **Be conversational and friendly:** Maintain a helpful yet professional tone. Avoid being overly casual. - **Write accessibly:** Ensure documentation is understandable to a diverse global audience, including non-native English speakers. - **Audience-first:** Focus on what the user needs to do, not just what the system does. - **Avoid pre-announcing:** Do not mention unreleased features or make unsupported claims. - **Use descriptive link text:** Link text should clearly indicate the destination (e.g., avoid "click here"). ### Language and Grammar - **Use second person ("you"):** Address the reader directly. - **Prefer active voice:** Clearly state who or what is performing the action (e.g., "The system generates a token" vs "A token is generated"). - **Standard American English:** Use standard American spelling and punctuation. - **Conditional clauses first:** Place "if" or "when" clauses before the instruction (e.g., "If you encounter an error, check the logs"). - **Define terms:** Introduce new or unfamiliar terms/acronyms upon first use. - **Consistent terminology:** Use the same term for the same concept throughout the document. - **Conciseness:** Aim for one idea per sentence. Keep sentences short. ### Formatting and Organization - **Sentence case for headings:** Capitalize only the first word and proper nouns in titles and headings. - **Lists:** - **Numbered lists:** Use for sequential steps or prioritized items. - **Bulleted lists:** Use for unordered collections of items. - **Description lists:** Use for term-definition pairs. - **Serial commas:** Use the Oxford comma (comma before the last item in a list of three or more). - **Code formatting:** Use code font for code-related text (filenames, variables, commands). - **UI Elements:** formatting user interface elements in **bold**. - **Date formatting:** Use unambiguous formats (e.g., "September 4, 2024" rather than "9/4/2024"). - **Structure:** Use logical hierarchy with clear introductions and navigation. Headings should be task-based where possible. ### Images and Code Samples - **Images:** Use simple, clear illustrations to enhance understanding. - **Captions:** Write captions that support the image. - **Code Samples:** - Ensure code is correct and builds without errors. - Follow language-specific conventions. - **Comments:** Focus on _why_, not _what_. Avoid commenting on obvious code. ### Reference Hierarchy 1. Project-specific style guidelines (if any exist in `CONTRIBUTING.md` or similar). 2. Google Developer Documentation Style Guide. 3. Merriam-Webster (spelling). 4. Chicago Manual of Style (non-technical). 5. Microsoft Writing Style Guide (technical). --- ## II. Angular Documentation Specifics ### Code Blocks Use the appropriate language identifier for syntax highlighting: - **TypeScript (Angular):** Use `angular-ts` when TypeScript code examples contain inline templates. - **HTML (Angular):** Use `angular-html` for Angular templates. - **TypeScript (Generic):** Use `ts` for plain TypeScript. - **HTML (Generic):** Use `html` for plain HTML. - **Shell/Terminal:** Use `shell` or `bash`. - **Mermaid Diagrams:** Use `mermaid`. #### Attributes You can enhance code blocks with attributes in curly braces `{}` after the language identifier: - `header="Title"`: Adds a title to