midudev/autoskills/adev-writing-guide

Claude Code and agent skill by midudev/autoskills

Trust tier 2
  • community
LLM review pending
Source check pending

Checking that the SKILL.md file is still in the repository.

Comprehensive writing guide for Angular documentation (adev). Covers Google Technical Writing standards, Angular-specific markdown extensions, code blocks, and components. You MUST use this skill any time you plan to create, edit, or review documentation files in `adev/` or `adev/src/content`.

Install

npx vskill@latest install midudev/autoskills/adev-writing-guide

SKILL.md

The same SKILL.md was published earlier as midudev/autoskills/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 a mermaid fenced block. <docs-code language="mermaid"> is not supported and fails the build.
Attributes

You can enhance code blocks with attributes in curly braces {} after the language identifier. header and highlight take a value after a colon; the rest are bare flags, and writing one as flag: true fails the build with Invalid code block metadata, as does an unrecognized key:

  • header: "Title": Adds a title to the code block.
  • linenums: Enables line numbering.
  • highlight: [2]: Highlights specific lines. An ascending two-number array is a range, so [12, 19] highlights lines 12 through 19. One number, or three or more, is a literal list. Nest one level to mix the two: [[3,7], 9].
  • hideCopy: Hides the copy button.
  • hideDollar: Hides the $ prompt in shell examples.
  • prefer: Marks code as a preferred example (green border/check).
  • avoid: Marks code as an example to avoid (red border/cross).

Example:

`markdown

@Component({ selector: 'my-app', template: '<h1>Hello</h1>', }) export class App {}

<docs-code> Component

For more advanced code block features, use the <docs-code> component. Its attributes use HTML syntax, attr="value" with double quotes, and bare names for the boolean ones. It validates nothing, so an unrecognized attribute and a single-quoted value are both ignored without an error:

  • path: Path to a source file (e.g., adev/src/content/examples/...).
  • header: Custom header text.
  • language: Language identifier (e.g., angular-ts). When omitted, it is inferred from the file extension, and an extension it does not recognize falls back to angular-ts, so set it for shell, markdown and scss files.
  • linenums: Boolean attribute.
  • highlight: Array of line numbers/ranges, with the same semantics as the fenced form (e.g., [[3,7], 9]).
  • visibleLines: Range of lines to show initially (collapsible).
  • region: Region to extract from source file.
  • preview: Boolean. Renders the example as a running component below the code. _Only works with standalone examples._
  • hideCode: Boolean. Collapses code by default.
  • hideDollar: Hides the $ prompt in shell examples.
  • prefer / avoid: Mark the example as preferred or as one to avoid.

Multifile Example:

html
<docs-code-multifile path="..." preview>
<docs-code path="..." />
<docs-code path="..." />
</docs-code-multifile>
Alerts / Admonitions

Use specific keywords followed by a colon for alerts. These render as styled blocks.

  • NOTE: For ancillary information.
  • TIP: For helpful hints or shortcuts.
  • IMPORTANT: For crucial information.
  • CRITICAL: For warnings about potential data loss or severe issues.
  • TODO: For incomplete documentation.
  • QUESTION: To pose a question to the reader.
  • SUMMARY: For section summaries.
  • TLDR: For concise summaries.
  • HELPFUL: For best practices.

Example:

markdown
TIP: Use `ng serve` to run your application locally.
Custom Components
  • Cards (`<docs-card>`):
  • Usually inside <docs-card-container>; a single card also renders on its own.
  • Attributes: title, href, link, imgSrc, iconImgSrc, titleInline.
  • href is the destination and link only replaces the default "Learn more" label, so a URL written in link renders as text and a card without href is not clickable.
  • Callouts (`<docs-callout>`):
  • Attributes: title, important, critical.
  • Pills (`<docs-pill>`):
  • Must be inside <docs-pill-row>.
  • Attributes: title, href.
  • Steps / Workflow (`<docs-step>`):
  • Must be inside <docs-workflow>.
  • Attributes: title.
  • Tabs (`<docs-tab>`):
  • Must be inside <docs-tab-group>.
  • Attributes: label.
  • Videos (`<docs-video>`):
  • Attributes: src (YouTube embed URL), title (names the video in the play link's label).
Images

Use standard markdown syntax with optional attributes for sizing and loading behavior.

  • #small, #medium: Append to image URL for sizing.
  • {loading: 'lazy'}: Add attribute for lazy loading.

Example:

markdown
![Alt Text](path/to/image.png#medium {loading: 'lazy'})
Headers
  • Use markdown headers (#, ##, ###).
  • Ensure a logical hierarchy (don't skip levels).
  • h2 and h3 are most common for content structure.

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewNot runA model review is scheduled for the next rescan.

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
6,974
Repository forks
631
7-day trend score
44

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/midudev/autoskills/adev-writing-guide/badge)](https://verified-skill.com/skills/midudev/autoskills/adev-writing-guide)

Something wrong with this skill or its page? Tell us.