Skip to content

AGENTS.md

Latest commit

 

History

History
227 lines (151 loc) · 6.92 KB

AGENTS.md

File metadata and controls

227 lines (151 loc) · 6.92 KB
Raw

Copilot SDK docs style guide

This style guide applies to all documentation in the docs/ directory. These docs are synced to github/docs-internal via a normalization pipeline, so they must follow the conventions below to be compatible with docs.github.com.

Headings

Use sentence case for all headings. Capitalize only the first word and proper nouns.

  • ## Quick start: Microsoft Foundry — not ## Quick Start: Microsoft Foundry
  • # Custom agents and sub-agent orchestration — not # Custom Agents & Sub-Agent Orchestration

Use and instead of & in headings.

Do not use **bold** or *italic* markers inside headings. The heading level provides emphasis.

Proper nouns to always capitalize

  • Products/companies: GitHub, Copilot, Azure, OpenAI, Anthropic, Microsoft, Ollama, Slack, Foundry, Kubernetes, Docker
  • Languages/frameworks: TypeScript, JavaScript, Python, Java, Node.js, OpenTelemetry, Express
  • Platforms: macOS, Linux, Windows
  • Protocols/formats: OAuth, JSON-RPC, JSON, YAML, HTTP, TCP, SSE, REST
  • Acronyms: MCP, BYOK, MAF, SDK, CLI, API, HMAC, CI/CD, SaaS, ISV, FAQ, LLM, AI, EMU, ID, UI, PNG
  • Tools (keep canonical casing): npm, npx, stdio
  • Code identifiers in headings: SessionConfig, MessageOptions, TelemetryConfig, ProviderConfig, CopilotClient
  • Multi-word proper names: GitHub App, GitHub Actions, GitHub OAuth, Foundry Local, Managed Identity, Container Instances

Callouts

Use GitHub-flavored alert syntax:

> [!NOTE]
> This is a note.

> [!TIP]
> This is a tip.

> [!WARNING]
> This is a warning.

Never use > **Note:** or > **Tip:** style callouts.

When a callout applies to a specific language, put the qualifier as bold text in the body:

> [!TIP]
> **(Python / Go)** These SDKs use separate, per-event data types.

Lists

Unordered lists

Use * (asterisks) for unordered list markers, not - (hyphens).

Ordered lists

Use 1. for every item in ordered lists, not sequential numbering. This makes reordering easier.

1. First step
1. Second step
1. Third step

List item formatting

  • Capitalize the first letter of each list item.
  • Use periods only if the item is a complete sentence.
  • Introduce lists with a descriptive sentence, not vague phrases like "the following" in isolation.

Em dashes

For list items with a label and description, use a colon:

* **Ephemeral**: not persisted to disk, not replayed on session resume

For em dashes used mid-sentence, use no spaces:

The SDK is a transport layer—it sends your prompt to the CLI over JSON-RPC.

Horizontal rules

Do not use --- as a horizontal rule to visually separate sections in the body of an article. Use headings to separate sections instead. This does not apply to YAML frontmatter delimiters.

Index.md files

In the docs pipeline, index.md files become YAML-only category pages. Rich content (prose, code samples, diagrams) must live in standalone files.

If you are writing a new section with substantive content, create a named file (for example, choosing-a-setup-path.md) rather than putting the content in index.md.

Code snippets

  • Only modify code block contents when necessary. From <SDK_ROOT>, run the relevant npm run docs:<language> validator for Node.js, Python, Go, .NET, or Java. Rust has no docs:rust facade; validate its API documentation with cd rust && DOCS_RS=1 cargo doc --no-deps --all-features and follow rust/README.md. Keep using docs-validate: skip or docs-validate: hidden markers when appropriate.

Voice and tone

  • Use clear, simple language approachable for a wide range of readers.
  • Use active voice whenever possible.
  • Avoid idioms, slang, and region-specific phrases.
  • Avoid ambiguous modal verbs ("may", "might", "should", "could") when an action is required. Use definitive verbs instead.
  • Refer to people as "people" or "users", not "customers."

Emphasis

  • Use bold for UI elements and for emphasis, sparingly (no more than five contiguous words).
  • Do not bold text that already has other formatting (for example, all-caps placeholders).

Word choice

Use Avoid
terminal shell
sign in log in, login
sign up signup
email e-mail
press (a key) hit, tap
repository repo
administrator admin
for example e.g.
and similar etc.

What the pipeline handles

Authors do not need to worry about these — the normalization pipeline handles them automatically:

  • YAML frontmatter (added to files for docs.github.com)
  • Mermaid diagram → PNG conversion
  • Link rewriting for docs.github.com cross-references
  • Liquid variable substitution (product names)
  • [AUTOTITLE] link conversion

New article template

When creating a new docs article, use this structure:

# Article title in sentence case

A one- or two-sentence intro explaining what the reader will learn or accomplish.

## First section

Body text here.

## Second section

Body text here.

## Further reading

* [Link text](./relative-path.md): short description

Multi-language code examples

When showing the same concept in multiple programming languages, use consecutive <details> blocks. The docs-internal normalization pipeline converts these into tabbed language switchers on docs.github.com.

Rules

  • Only code inside <details> blocks. Shared prose, headings, and explanations must go outside the blocks. Each block should contain only a code fence (and optionally a <!-- docs-validate: skip --> comment).
  • Blocks must be consecutive. No content (headings, paragraphs) between <details> blocks in the same group. Blank lines between blocks are fine.
  • Use the exact <summary> format: <summary><strong>LANGUAGE</strong></summary>. Supported labels: .NET, Python, TypeScript, Go, Java, Rust, Node.js, Shell.
  • Need 2+ blocks to form a group. A single <details> block won't be converted and renders as raw HTML on docs.github.com.
  • Equal content across tabs. Each tab should show the same concept in a different language. Language-specific extras should be a separate section outside the tabs.

Correct

Shared prose goes above the group, then each <details> block contains only code:

Install the SDK:

<details open>
<summary><strong>.NET</strong></summary>

<!-- docs-validate: skip -->

```bash
dotnet add package GitHub.Copilot.SDK
Python 
pip install github-copilot-sdk
```

Incorrect

Do not put headings, prose, or multiple sections inside a <details> block:

<details>
<summary><strong>Python</strong></summary>

### Prerequisites           ← breaks TOC/anchors
Install the packages:       ← prose belongs outside

```bash
pip install github-copilot-sdk

Basic usage ← multiple sections in one tab

[code]
```