Documentation Agent Guide

Internal guide for maintaining and improving Instructor documentation

PublishedFeb 1, 2026

Loading actions...

5 minBeginnerprompt19 files

Skill content

Main instructions and any bundled files for this skill.

markdown

Additional Files (18)

AGENT.md - Documentation

Commands

Serve docs locally: uv run mkdocs serve
Build docs: ./build_mkdocs.sh or uv run mkdocs build
Install doc deps: uv pip install -e ".[docs]"
Test examples: uv run pytest docs/ --examples

Structure

Core docs: concepts/, integrations/, examples/
Learning path: getting-started.md → learning/ → tutorials/
API reference: Auto-generated from docstrings via mkdocstrings
Blog: blog/posts/ for announcements and deep-dives
Templates: templates/ for new docs (provider, concept, cookbook)

Writing Guidelines

Reading level: Grade 10 (from .cursor/rules)
Code examples: Must be runnable with complete imports
Progressive complexity: Simple → advanced concepts
Provider docs: Follow templates/ patterns
Navigation: Update mkdocs.yml for new pages

Pull Request (PR) Formatting

Use Conventional Commits formatting for PR titles so they are consistent and easy to scan. Treat the PR title as the message we would use for a squash merge commit.

PR Title Format

Use:

<type>(<scope>): <short summary>

Rules:

Keep it under ~70 characters when you can.
Use the imperative mood (for example, “add”, “fix”, “update”).
Do not end with a period.
If it includes a breaking change, add ! after the type or scope (for example, feat(docs)!:).

Good examples:

docs(agents): add conventional commit PR title guidelines
docs(mkdocs): fix broken link in validation tutorial
docs(examples): update youtube clips snippet
chore(docs): refresh docs build commands

Common types:

docs: documentation-only changes
fix: bug fix
feat: new feature
test: add or update tests
chore: maintenance work (build scripts, tooling, repo hygiene)
ci: CI pipeline changes

Suggested docs scopes:

docs, mkdocs, blog, examples, integrations, tutorials, agents

PR Description Guidelines

Keep PR descriptions short and actionable:

What: What changed, in 1–3 sentences.
Why: Why this change is needed (link issues when possible).
Changes: 3–7 bullet points with the main edits.
Testing: What you ran (or why you did not run anything).
Docs impact: Call out page moves, redirects, or nav updates.

If the PR was authored by Cursor, include:

This PR was written by [Cursor](https://cursor.com)

Key Files

mkdocs.yml - Site configuration and navigation
hooks/ - Custom processing (hide_lines.py removes # <%hide%> markers)
overrides/ - Custom theme elements
javascripts/ - Client-side enhancements

Contents

View Original Source

Related Skills

General

PromptBeginner5 minmarkdown

Untitled Skill

191

Jan 12, 2026

General

PromptBeginner5 minmarkdown

Frontend Typescript Linting.mdc

TypeScript and ESLint rules that MUST be followed when creating, modifying, or reviewing any file under apps/frontend/, including .ts, .tsx, .js, and .jsx files. Also apply when discussing frontend li...

153

Feb 15, 2026

General

PromptBeginner5 minmarkdown

2. Apply Deepthink Protocol (reason about dependencies

risks

125

Jan 15, 2026