---
id: guide.write-with-agents
title: Write with agents
summary: Use your existing coding agent with project guidance, templates, and
  provider-free documentation tools.
type: explanation
area: authoring
subarea: authoring-writing
audiences:
  - authors
canonical: /author/agents
---

# Write with agents

> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)

Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)

Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Overview

**Updated: 2026-10-19.**

Use your existing coding agent to write and revise Shoalrun documentation. Your agent supplies its model and evidence-gathering tools; Shoalrun supplies templates, canonical guidance, project discovery, and isolated snapshot validation. You review factual claims, accept changes, and decide when to publish.

## Choose a writing task

Start with [Use your coding agent](https://www.shoalrun.com/author/coding-agent.md) to draft a new page. For working-tree edits, follow [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md). Existing checked-plan clients can continue using [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md).

Project discovery does not require a selected page. Search by topic to find the relevant pages, then read project instructions, supporting sources, and reviewed examples before editing. No additional authoring provider key is required.

## Review the result

Snapshot validation checks a separate capture and reports findings, coverage, and freshness. Review the diff, sources, and built HTML and Markdown before accepting the edit. Compiler success does not establish factual accuracy or writing quality. Use `docs review` and `docs preview` to inspect the captured result and its freshness. The portable authoring skill follows this working-tree workflow. Independent author trials remain a separate release gate.

## Shared writing guidance

[Design templates](https://www.shoalrun.com/author/design-templates.md) and [Design a writing guide](https://www.shoalrun.com/author/design-writing-guides.md) explain how to give your agent useful project conventions. The [example writing guide](https://www.shoalrun.com/author/writing-style.md) is a starting point to adapt.

## Related reading

### Related topics

- [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md) — Start with the agent authoring workflow. (Status: experimental.)

- [Use your coding agent](https://www.shoalrun.com/author/coding-agent.md) — Choose the authoring workflow that fits how you work.