Docs
Agent setup
Configure coding agents to edit Proa projects with local instructions.
A coding agent in a Proa repository reads the same files you do: AGENTS.md, an optional SKILL.md, and per-page docs Markdown. This page covers writing AGENTS.md, writing a reusable skill, which context an agent needs, and fetching page Markdown.
Writing AGENTS.md
proa new site scaffolds the file by default (pass --no-agents-md to skip it; --agents-md is the explicit spelling of the default):
proa new site my-site
Keep AGENTS.md at the project root. It describes the local project shape, render rules, validation commands, and safe edit boundaries.
# AGENTS.md
## Project Shape
- Pages live in `src/pages/`.
- Shared shells live in `src/layouts/`.
- Reusable render components live in `src/components/`.
- Route metadata, navigation, and shared data live in `src/data/`.
- Keep a component next to the route that owns it. Promote it into
`src/components/` once a second route needs it.
- Keep route handlers, shared components, and content compilation in separate
modules, and keep request-specific data out of globals.
## Rendering Rules
- Use `WebRenderSync` by default.
- Use `WebRender` only when the render body or `render_head` needs `.await`, or the analyzed component declares RSJS query/mutation state.
- Use `html_sync!` for synchronous render trees and `html!` for async-capable render trees.
- Opaque SSR components use no RSJS attribute. An analyzed component uses
`#[rsjs(component)]`; add `client` when it originates signals, event
handlers, queries, mutations, shared-state acquisition, node refs, or
browser work.
- Always annotate a real render-trait impl. Do not use inherent render
shorthand, `async fn render` sugar, or component `clients(...)` allowlists.
- A direct inbound read such as `self.label` can remain live when its parent
supplies a live value. Use `server_only(...)` or `server_attr(...)` only for
an intentional per-render snapshot.
- Keep hot render paths allocation-clean. Prefer borrowed data, static class strings, and stack-allocated class composition.
- Do not build child HTML strings just to concatenate them into a parent.
- In managed documents, set `const ROLE: ComponentRole = ComponentRole::PAGE` on the route page and `LAYOUT` on its ancestors. Use one head outlet. A head hook requires either role; analyzed RSJS impls stay render-only, with roles and hooks on an ordinary SSR wrapper.
## Validation
Run these before handing work back:
```bash
cargo fmt --all
proa check
proa test
proa site check
```
If a render-path change allocates intentionally, explain why.
AGENTS.md binds one project. To carry the same rules into every project an agent touches, write a skill.
Writing a reusable skill
Some agents support reusable SKILL.md files. Use one when you want the Proa authoring rules to follow the agent across projects.
The source repository includes five focused skills:
| Skill | Use it for |
|---|---|
proa-component | Typed server-rendered components and allocation-conscious styling |
proa-island | RSJS signals, handlers, and browser islands |
proa-perf-review | Render-path performance checks |
proa-markdown | Typed Markdown and shared HTML/Markdown content |
proa-docs-api | Retrieving current documentation through HTTP or MCP |
Use your agent's skill installer with that repository, or discover the downloadable instructions and integrity hashes in the public skills index. The authoring skills use the repository's docs/agent/ reference; the API skill works without a source checkout. A skill supplements the owning project's instructions.
For a project-specific skill, start with this outline:
# Proa Site Authoring
Use this skill when adding or changing Proa pages, components, layouts, route handlers, or RSJS islands.
## Rules
- Read the local `AGENTS.md` first.
- Prefer `WebRenderSync` unless the body or head hook must await data, or the component declares RSJS query/mutation state.
- Use `html_sync!` for sync markup and `html!` for async-capable markup.
- Use `#[rsjs(component)]` on an authored render-trait impl for analyzed
participation. Add `client` when the component originates browser behavior.
Keep handlers as named locals when they are more than trivial.
- Do not use inherent render shorthand, `async fn render` sugar, or component
`clients(...)` allowlists.
- Treat direct inbound fields as potentially live. Use explicit server
boundaries only when the component contract intentionally snapshots them.
- Preserve direct parent-child rendering. Do not render children into intermediate `String`s unless a non-hot-path API explicitly requires it.
- Keep classes static where possible. Prefer compile-time class composition and existing project tokens.
- Managed documents need explicit PAGE/LAYOUT roles and one head outlet; put head hooks on ordinary SSR wrappers, outside analyzed RSJS impls.
- After edits, run the validation commands from `AGENTS.md`.
## Context To Fetch
- `/docs/core/html-rendering.md`
- `/docs/core/components.md`
- `/docs/guides/islands.md`
- `/docs/rsjs/handlers.md`
- `/docs/rsjs/signals.md`
- `/docs/rsjs/queries-mutations.md`
- `/docs/guides/performance.md`
Use `/llms-full.txt` only when the task needs broad recall across the whole docs site.
The skill fixes the rules. The next decision is how much documentation to load for a given task.
Which context does an agent need?
Start small. Add more context only when the task needs it.
| Task | Give the agent |
|---|---|
| Create or edit a page | AGENTS.md, /docs/framework/routing.md, /docs/core/components.md |
| Add a reusable component | AGENTS.md, /docs/core/html-rendering.md, /docs/guides/performance.md |
| Add browser interactivity | AGENTS.md, /docs/guides/islands.md, /docs/rsjs/handlers.md, /docs/rsjs/signals.md |
| Add async data | AGENTS.md, /docs/framework/data-loading.md, /docs/core/html-rendering.md |
| Debug a compile error | AGENTS.md, focused page Markdown, compiler output |
| Answer broad questions | /llms-full.txt |
Every row names Markdown files, and every docs route serves one.
Fetching page Markdown
Every docs route exposes Markdown:
curl https://proa.so/docs/agents.md
curl https://proa.so/docs/core/html-rendering.md
curl https://proa.so/docs/rsjs/handlers.md
For persistent project behavior, keep instructions in AGENTS.md or SKILL.md. For one-off retrieval, use page Markdown or /llms-full.txt.
Next steps
- AI consumption
- Fetch docs context for an agent that reads but never edits the project.
- proa new site
- See where pages, layouts, components, and shared data live.
- HTML rendering
- Learn the render traits and macros the rules above refer to.
- Writing performant pages
- Keep the render paths an agent edits free of allocation.