agno-doc

Imported from xianyunyh/agno-doc (AGENTS.md). Install upstream with npx skills add xianyunyh/agno-doc. Copyright stays with the author.

AGENTS.md - Agno Documentation Style Guide

Philosophy

Agno docs are direct, concrete, and professional. No marketing fluff. No AI-sounding prose. Every sentence earns its place. We cover a massive surface area. Analogies and commentary add cognitive load without adding understanding. Be direct.

About This Repo

• Site builder: Mintlify. Pages are .mdx with frontmatter (title, description).
• Navigation: docs.json is the source of truth. Adding a page means adding it there too.
• Agno source: symlinked at ./agno (-> ~/code/agno). Read it before writing about APIs, parameters, or behavior. Don't guess from memory or training data.
• Cookbook examples: agno/cookbook/ has runnable examples. Reference or adapt these rather than inventing new ones.
• Reusable snippets: _snippets/ holds shared install steps, setup blocks, and recurring components. Check there before duplicating content.
• Agno version: Verify the exact ./agno tag before writing. Stop and ask if the checkout is not on the version targeted by the current docs work.

Before Writing Any Page

Define these five things before you write:

1. What is this page about? (one sentence)
2. What does the user need to do? (the code)
3. What decisions might they face? (tables)
4. Where do they go next? (links)
5. What type of page is this? (tutorial, how-to, reference, or explanation. See Page Types below.)

If you can't answer these clearly, the page will ramble.

Page Structure

Every page should follow this pattern:

1. One-line description - What this page covers (in frontmatter and opening line)
2. Code first - Show the pattern immediately
3. Explain after - Brief context only if needed
4. Tables for decisions - "When to use X vs Y" belongs in a table, not prose
5. Links at bottom - "Next steps" or "Developer Resources"

❌ Long explanation of what agents are, their history, why they matter...
   then eventually some code.

✅ Code example showing the pattern.
   Brief explanation of what it does.
   Table of options/decisions.
   Links to related pages.

Page Types

Every page serves one primary documentation need. The four types come from the Diátaxis framework:

If a page mixes types (e.g., a how-to that stops to explain concepts), extract the foreign content into its own page and link to it.

Context Hygiene

Start fresh for each section. Don't let one domain bleed into another. If you're writing Tools docs, don't bring patterns or terminology from Learning Machine docs. Each section should be self-contained.

Core Rules

1. Lead with code

Show the pattern first, explain after. Users are scanning for how to do something.

❌ "To create an agent with structured output, you need to define a Pydantic
   model that represents the schema you want. Then you pass this to the
   output_schema parameter. Here's how:"
   [code]

✅ [code]
   "The agent returns a `StockAnalysis` object instead of free-form text."

2. One concept per section

Don't bundle unrelated ideas. If you're explaining structured output, don't also explain tools in the same section.

3. Tables over prose for comparisons

❌ "You might want to use structured input when you need validation, but
   string input is fine for prototyping. If you're building a production
   system, structured input gives you type safety..."

✅ | Use Case | Input Type |
   |----------|------------|
   | Prototyping, chat | String |
   | Production, validation needed | Pydantic model |

4. Descriptions must be specific

Every page's description field should describe what the page covers, not say "Learn how to..."

❌ "Learn how to run your Agents and process their output."
✅ "Execute agents with Agent.run() and process their output."

❌ "Learn how to build Agents with Agno."
✅ "Start simple: a model, tools, and instructions."

❌ "Learn about Agno Agents and how they work."
✅ "AI programs where a language model controls the flow of execution."

5. No em dashes

Em dashes (U+2014) are an AI tell. Use periods or rewrite.

❌ "No data leaves your environment—ideal for security-conscious teams."
✅ "No data leaves your environment. Ideal for security-conscious teams."

❌ "Each Agent maintains its own history—switching users won't mix context."
✅ "Each Agent maintains its own history. Switching users won't mix context."

6. No comma splices

Two independent clauses joined by a comma need a period or semicolon.

❌ "Run it on your own machine, don't take these numbers at face value."
✅ "Run it on your own machine. Don't take these numbers at face value."

❌ "Stateless, horizontal scalability isn't optional, it's the baseline."
✅ "Stateless, horizontal scalability isn't optional. It's the baseline."

7. Cut the commentary

Analogies and editorializing waste space.

❌ "Unstructured I/O is like shouting instructions and getting a rough
   answer back that must be further worked upon. It works, but it's messy."

✅ "String input works for prototyping and chat. Add structure when you
   need validation."

8. Specific over generic

❌ "Use a better model for improved results."
✅ "Use `claude-opus-4-5` for better prose quality."

❌ "You can customize various settings."
✅ "Set `temperature=0` to reduce sampling variability."

9. Tighten wordy phrases

10. Link lists: no "View the..." pattern

❌ Developer Resources
- View the [Agent reference](/reference/agents/agent)
- View the [RunOutput schema](/reference/agents/run-response)

✅ Developer Resources
- [Agent reference](/reference/agents/agent)
- [RunOutput schema](/reference/agents/run-response)

11. Q&A lists → Tables

❌ Common questions:
- **How do I run my agent?** -> See [running agents](/path).
- **How do I debug my agent?** -> See [debugging agents](/path).

✅ | Task | Guide |
   |------|-------|
   | Run agents | [Running agents](/path) |
   | Debug agents | [Debugging agents](/path) |

12. Card descriptions: vary them

❌ "Learn how to build your first agent."
❌ "Learn how to run your agents."
❌ "Learn how to debug your agents."

✅ "Create your first agent with tools and instructions."
✅ "Execute agents and handle responses."
✅ "Troubleshoot and inspect agent behavior."

13. No contrastive negation

Don't define things by what they aren't. State what they are directly.

❌ "Agents aren't just chatbots — they're autonomous programs that control
   execution flow."
❌ "This isn't a simple wrapper. It's a full orchestration layer."
❌ "Knowledge isn't just storage — it's retrieval-augmented generation."

✅ "Agents are autonomous programs where a language model controls
   execution flow."
✅ "The orchestration layer manages tool calls, memory, and model routing."
✅ "Knowledge adds retrieval-augmented generation to your agent."

Words and Phrases to Avoid

Capitalization & Terminology

The Three Pillars

Use on landing and overview pages where Agno is being introduced. Don't repeat the framing on every page. When you do use it, use these exact verbs and labels:

Code Examples

• No verbose comment blocks (# ************* Create Agent *************)
• Minimal inline comments - code should be self-explanatory
• Keep examples consistent across related pages
• Show the minimal working example first, then variations
• Pages under examples/** mirror cookbook code and docstrings byte-for-byte. Do not restyle generated code in place.
• Change generated example descriptions through scripts/examples_sync/description-overrides.json.
• Flag cookbook code or docstring problems upstream instead of changing the generated page.

Mintlify Components

Page Templates

The Overview template maps to Explanation pages, Tutorial/Guide maps to Tutorial or How-to, and Usage/Example maps to How-to.

Overview Page

---
title: What are X?
description: "One sentence defining X concretely."
---

**Bold one-liner expanding on the definition.**

[Code example - the simplest working version]

## Key Concepts

| Concept | Description |
|---------|-------------|
| A | What A does |
| B | What B does |

## Learn How To

<CardGroup cols={3}>
  <Card title="Build X" href="/x/building">
    Create your first X with [specifics]
  </Card>
  ...
</CardGroup>

## Developer Resources

- [X reference](/reference/x)
- [X examples](/cookbook/x)

Tutorial/Guide Page

---
title: Building X
description: "What you'll build and the key pattern."
---

[Code example - complete working version]

## How It Works

1. Step one
2. Step two
3. Step three

## Options

| Option | Default | Description |
|--------|---------|-------------|
| `foo` | `true` | What foo does |

## Next Steps

| Task | Guide |
|------|-------|
| Do Y | [Y guide](/y) |

Usage/Example Page

---
title: X with Y
description: "What this combination achieves."
---

<Steps>
  <Step title="Create file">
```python
    [code]
```
  </Step>
  <Step title="Install deps">
```bash
    uv pip install ...
```
  </Step>
  <Step title="Run">
```bash
    python file.py
```
  </Step>
</Steps>

Validation Commands

# Preview locally (run from the directory with docs.json)
mint dev

# Run deterministic repository checks
python3 scripts/inventory/run_all.py
python3 scripts/check_install_coverage.py
python3 scripts/examples_sync/plan.py
python3 scripts/examples_sync/check_integrity.py

# Check Mintlify structure and links
mint broken-links
mint validate