| name | osprotocol-docwriter |
| description | Write, edit, review, and triage documentation pages for the OS Protocol website (apps/web/content/docs/). Use when creating new doc pages, rewriting placeholders, reviewing existing pages for accuracy, or triaging pages (rewrite/deprecate/roadmap). Triggers on: writing docs, doc page, MDX, placeholder page, documentation triage, rewrite page, update docs, content/docs.
|
/osprotocol-docwriter — OS Protocol Documentation Writer
Guide for writing and maintaining documentation pages in apps/web/content/docs/.
Workflow
1. Verify the source of truth
Before writing any doc page, read the corresponding TypeScript file in packages/schema/. The types are the protocol. The doc page documents them — it does not invent content.
- Interface page → read the
.ts file (e.g., packages/schema/system/env.ts for system/env.mdx)
- Domain index page → read the domain's
index.ts barrel file
- Concept page → read relevant schema files + consult
osprotocol-guide agent
If there is no corresponding .ts file, the page has no schema backing. Unless it's a concept page, it should be eliminated — not rewritten. See inventory.md for elimination criteria.
2. Choose the right template
| Page type | Template | Example |
|---|
| Interface page (@experimental or stable) | See templates.md | runs/timeout.mdx |
| Domain index page | See templates.md | system/index.mdx |
| Concept page | No strict template — but follow conventions | concepts/agent-loop.mdx |
3. Write following conventions
Read conventions.md for the full style guide. Key rules:
- Import paths must be real and verifiable (
osprotocol/system/env)
- TypeScript interfaces must match the schema exactly — copy from source, don't paraphrase
- Mermaid diagrams when they clarify flow or state, not for decoration
- No "Coming soon", no generic bullet lists, no marketing language
4. Update navigation
After any structural change (add, remove, move pages), update apps/web/content/docs/meta.json. See conventions.md for rules.
5. Validate
After writing, verify:
- The import path exists in
packages/schema/package.json exports
- All type names match the schema exactly
- Links to other pages use correct paths
- Frontmatter has title and description
meta.json reflects the current page structure
Reference Files
What This Skill Is NOT
- Not for answering protocol questions → use
osprotocol-guide agent
- Not for implementing protocol interfaces → use
/develop (planned)
- Not for writing non-documentation content (blog posts, marketing)
