# Write your first article

With your [AI tool connected](/articles/connect-your-ai-tool), writing docs is a conversation. You describe what you want; your agent writes it and saves it to Clayo. You never fill in a form or open an editor.

## Describe what you want

Prompts can be as light or as specific as you like:

```
Write a getting started guide for my product and add it to my docs.
```

```
Add an article explaining how to rotate API keys. Cover the CLI and the dashboard,
and add a warning that old keys stop working immediately.
```

Your agent knows your codebase, so it can document features straight from the source. Point it at code, a changelog entry, or a support thread and ask it to turn that into an article.

## What happens under the hood

Your agent calls Clayo's structured tools: `create_article` to draft, `update_article` to revise, `publish_article` to ship. It picks the collection, writes the body in markdown, and can use Clayo's [formatting directives](/articles/markdown-and-formatting) for callouts, tabs, and videos. You will see it confirm each step, and every article it touches comes back with links you can click.

New articles start as **drafts**. A draft is invisible to the public until you publish it, so you can iterate freely. See [How authoring works](/articles/how-authoring-works) for the full draft and publish model.

## Preview before you publish

Every draft has a preview link that your agent includes when it creates or updates an article. It renders the page exactly as your live site will, and it is only visible to signed-in members of your project. Open it, read it like a customer would, then ask for changes in plain language:

```
Tighten the intro, and move the troubleshooting section to the end.
```

## Warnings, not errors

If an article uses a directive Clayo does not recognize, or an attribute has a typo, the save still succeeds. Clayo returns warnings to your agent instead of rejecting the write, so a small mistake never loses your work. Your agent will usually fix warnings on its own; you can also ask it to check:

```
Any warnings on the last article? Fix them.
```

## A good first hour

A useful pattern for a brand new docs site:

1. Ask for a getting started guide and publish it.
2. Ask your agent to propose a structure: `Suggest sections and collections for my product's docs.` See [Organize with sections and collections](/articles/sections-and-collections).
3. Have it draft the five articles your support inbox already answers weekly.

## Next step

Time to go live: [Publish and view your docs](/articles/publish-your-docs).