sections guides

Guides

Active contributors: Sagar Narayan, Eno Reyes, Andy Taylor

Purpose

docs/guides/ is the recipe section. Where cli/ and web/ document what something is and how to configure it, guides/ shows how to use it for a specific outcome. The Mintlify navigation puts everything here under a separate "Guides" tab in docs/docs.json.

Directory layout

docs/guides/
├── building/             # Building plugins, droid-exec tutorial, droid-vps setup
├── droid-exec/           # Recipes for headless droid (code review, refactor passes, doc automation, GitHub Actions)
├── hooks/                # Recipes for hooks (formatting, validation, doc sync, git workflows, logging, notifications, session automation, testing)
├── power-user/           # Setup checklist, memory management, rules & conventions, prompt crafting, token efficiency, evaluating context compression
└── skills/               # Skill recipes (frontend integration, service integration, data querying, internal tools, vibe coding, AI data analyst, product management, browser, automated QA)

Power-user guides

docs/guides/power-user/ is the most-recommended starting point for engineers who already have droid running:

Page	Topic
setup-checklist.mdx	The opinionated initial setup
memory-management.mdx	What droid remembers, where, and for how long
rules-conventions.mdx	Writing AGENTS.md and convention files that droid will respect
prompt-crafting.mdx	Effective prompt patterns
token-efficiency.mdx	Reducing context cost
evaluating-context-compression.mdx	Comparing different compression strategies

Skills

docs/guides/skills/ has one recipe per skill, plus the automated-qa.mdx page that's also linked into the main "Capabilities" group of the Docs tab:

• frontend-ui-integration.mdx
• service-integration.mdx
• data-querying.mdx
• internal-tools.mdx
• vibe-coding.mdx
• ai-data-analyst.mdx
• product-management.mdx (~24 KB — largest skill recipe)
• browser.mdx
• automated-qa.mdx

The skills system itself is documented at docs/cli/configuration/skills.mdx.

Hooks

docs/guides/hooks/ covers recipe usage of the hook system. The hook reference (events, payload schemas, return contracts) is at docs/reference/hooks-reference.mdx. The how-to-write-a-hook overview is at docs/cli/configuration/hooks-guide.mdx.

Page	Recipe
auto-formatting.mdx	Run formatters automatically
code-validation.mdx	Validate generated code (lint, typecheck) before accepting changes
documentation-sync.mdx	Keep docs in sync with code changes
git-workflows.mdx	Branch and commit hygiene
logging-analytics.mdx	Forward droid events to your logging stack
notifications.mdx	Push notifications on droid events
session-automation.mdx	Per-session lifecycle automation
testing-automation.mdx	Automatically run tests during droid loops

droid-exec recipes

docs/guides/droid-exec/ has recipes for using headless droid in CI, scripts, and one-off automation:

Page	Recipe
code-review.mdx	Run code review headlessly
refactor-imports.mdx	Automated import refactor pass
refactor-error-messages.mdx	Standardize error messages across a codebase
refactor-fix-lint.mdx	Automated lint-fix pass
document-automation.mdx	Automate documentation chores
github-actions.mdx	Wire droid-exec into GitHub Actions

The droid-exec overview is docs/cli/droid-exec/overview.mdx. The full tutorial is docs/guides/building/droid-exec-tutorial.mdx.

Building

docs/guides/building/ covers building reusable artifacts:

• building-plugins.mdx — packaging skills/hooks/droids/slash-commands as a plugin
• droid-exec-tutorial.mdx — end-to-end droid-exec walkthrough
• droid-vps-setup.mdx — provisioning a VPS as a droid runner

Integration points

• Skills guides cross-link to docs/cli/configuration/skills.mdx (system reference).
• Hook guides cross-link to docs/cli/configuration/hooks-guide.mdx and docs/reference/hooks-reference.mdx.
• droid-exec recipes cross-link to docs/cli/droid-exec/overview.mdx.
• The "Building" guides cross-link to docs/cli/configuration/plugins.mdx and the enterprise plugin registry.

Entry points for modification

• New skill/hook/droid-exec recipe → add an MDX file in the matching subfolder, add to the right group under the "Guides" tab in docs/docs.json.
• Cross-recipe topic → consider whether it belongs in power-user/ (general patterns) or one of the skill/hook/droid-exec subfolders (recipe-specific).
• The "Guides" tab navigation is intentionally flatter than the Docs tab — keep one level of grouping unless a section grows past ~10 pages.