Agents.MD + style guide

[ralph-mcteggart]

Added an agents.md which is really a style guide for agents:

• It's a combo of Google style guide principles, Cloudsmith UX writing guidelines, and Cloudsmith specific conventions in one place with a clear precedence order.
• Should help us reduce common issues we're seeing in our docs and doc PRs
• Kept it quite succinct so that it doesn't eat up too much model context
• Tells the agent to ask for feedback if what's being asked isn't clear or is going to create a contradiction in docs

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
cloudsmith-docs	Ready	Preview, Comment	Dec 23, 2025 5:18pm

[Copilot]

Pull request overview

This PR introduces a comprehensive technical writing style guide specifically designed for agents and LLMs to use when creating or reviewing Cloudsmith documentation. The guide consolidates Google style guide principles, Cloudsmith UX writing guidelines, and company-specific conventions into a single reference document.

Key changes:

• Establishes a clear precedence hierarchy for documentation standards (Cloudsmith-specific → Google → third-party references)
• Defines core principles including task-orientation, clarity, active voice, and scannability
• Provides extensive UX writing guidelines with before/after examples demonstrating best practices

Comments suppressed due to low confidence (1)

docs/agents.md:295

• The file ends with two blank lines (lines 294 and 295). According to the coding guidelines, files should typically end with a single newline character. This creates unnecessary whitespace.

---

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

[Copilot]

Missing comma after "e.g." - it should be "e.g.," as per standard American English punctuation rules.

Suggested change

	- Write as simply as possible while remaining accurate e.g. "use" instead of "utilize".
	- Write as simply as possible while remaining accurate, e.g., "use" instead of "utilize".

[Copilot]

The heading "Code Examples" uses title case capitalization but should use sentence case according to the style guide's own recommendation (section 6) that headings should "Capitalize only the first word and proper nouns in headings (sentence case)". It should be "Code examples".

Suggested change

	### Code Examples
	### Code examples

[Copilot]

This file is missing a copyright notice. According to the coding guidelines, most new source files should have a copyright comment near the top of the file in the format "Copyright 2025 Cloudsmith Ltd".