agentleFS
onyx-dot-apponyx-dot-app/onyx-foss/.agents/skills/docs-writing/SKILL.md

docs-writing

Skill320 starsChanged 8 days agoMITView on GitHub

Write, rewrite, audit, or review a page of the Onyx customer docs (the Mintlify site in `documentation/`). Use for new pages, release refreshes, screenshot updates, connector and provider guides, API guides, and docs quality reviews. Covers audience, source-of-truth checks against the onyx repo, ASD-STE100 prose rules, Mintlify page patterns, screenshot capture, and the checks to run before a PR.

15 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

19 rules. 0 are common, 12 are distinctive, and 7 are very specific to this project.

  • 0

    Common

    Most of the 15 edited versions we read keep these.

  • 12

    Distinctive

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every page here is customer-facing.

    line 8
  2. Distinctive:

    Do not document from memory or from the old page.

    line 21
  3. Very specific:

    If a running stack is available, confirm the flow in the UI (http://localhost:3000, admin_user@example.com / TestPassword123!).

    line 35
  4. Distinctive:

    Remove content you cannot verify.

    line 41
  5. Distinctive:

    Use the current product names.

    line 45
  6. Distinctive:

    Use the exact label the UI shows, in bold, for anything the reader clicks or types into: Admin Panel → Connectors,

    line 57
  7. Distinctive:

    Follow ASD-STE100 Simplified Technical English:

    line 62
  8. Distinctive:

    Put the outcome, the prerequisites, and the shortest correct path first.

    line 69
  9. Distinctive:

    Write so that a section quoted alone still answers the reader's question.

    line 84
  10. Very specific:

    Keep description generic to the capability, not to the one vendor the UI shows today.

    line 99
  11. Very specific:

    Every page must be in docs.json or reachable by a redirects entry.

    line 100
  12. Very specific:

    Use <Steps> / <Step title="..."> for procedures.

    line 104
  13. Very specific:

    Use shared snippets from snippets/ instead of repeating a block: navigate-to-ai-models.mdx, standard-ai-model-configs.mdx, …

    line 106
  14. Distinctive:

    Keep the existing path and filename when you replace a screenshot so the MDX does not change.

    line 137
  15. Very specific:

    When a PR changes UI, recapture its screenshots in the same PR.

    line 139
  16. Distinctive:

    Add media only when text cannot show the flow.

    line 149
  17. Very specific:

    every src="/assets/..." on the changed pages resolves to a file (logos and icons come from web/lib/opal.

    line 165
  18. Distinctive:

    no secrets, license files, or local URLs in the diff.

    line 168
  19. Distinctive:

    When you finish a page or a review, state: the reader and page type, the structural changes, the files or UI routes you used to verify each …

    line 200

“Common” is measured: kept by at least 6 in 10 of the 15 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Onyx docs writing

Every page here is customer-facing. The reader is an Onyx user, admin, or developer who wants to do one thing with the product. Write for that reader, not for the Onyx team.

1. Before you write

Name the reader and the page type

Pick one dominant reader for the page: end user, admin, developer, or operator who deploys Onyx. Pick one Diataxis type per page: tutorial, how-to, reference, or explanation. If two readers or two types compete, split the page or link out.

Ground every claim in source truth

Do not document from memory or from the old page. Check the code in this repo, in this order:

ClaimWhere to verify
What a feature does, what it touches, edition gating.agents/feature-map/components/<component>.md (find it via PATHS.md or INDEX.md; read GLOSSARY.md first, Onyx overloads Persona, Tool, Agent, turn)
UI labels, menu names, button textweb/src/i18n/messages/en.json, then the component under web/src/
Admin routes and tier per routeweb/src/lib/admin-routes.ts
Connector credential fields and form labelsweb/src/lib/credentials/constants.ts, web/src/lib/connectors/connectors.tsx
Permission-sync support per sourcebackend/ee/onyx/external_permissions/sync_params.py
Env vars, defaultsbackend/onyx/configs/app_configs.py and the config module that reads the var
API request and response shapesthe Pydantic models on the route, not the prose of an old guide
Route permissionsrequire_permission(...) on the FastAPI route
Release and version factsgit tags and release/vX.Y branches

If a running stack is available, confirm the flow in the UI (http://localhost:3000, admin_user@example.com / TestPassword123!). Code beats the old page; the running UI beats code when they disagree.

Business, legal, and infrastructure claims (subprocessors, compliance, SLAs, Cloud defaults, pricing, release cadence) are not verifiable from code. Leave them as they are and list them as open questions for the page owner. Do not guess.

Remove content you cannot verify. Do not keep it with a caveat.

Terminology

Use the current product names. One word for one idea, the same word on every page.

UseDo not use
AgentAssistant, Persona
Plugin / ActionTool (except in API field names)
ConnectorIntegration, data source (as a product noun)
Admin Paneladmin dashboard, settings page
OpenSearchVespa
Community Edition, Business, Enterprise, Onyx CloudEE, paid tier (undefined)
Document Set, User Group, Indexing Statusad-hoc variants

Use the exact label the UI shows, in bold, for anything the reader clicks or types into: Admin Panel → Connectors, Save API Key.

2. Prose rules

Follow ASD-STE100 Simplified Technical English:

  • Short sentences. 20 words or fewer for an instruction, 25 for a description.
  • Active voice, second person for instructions: "Click Connect", not "Connect should be clicked".
  • One topic per paragraph. One idea per sentence.
  • Approved words only; each word has one meaning. Do not vary wording for style.
  • Present tense for stable behaviour. Dates for historical events.
  • Put the outcome, the prerequisites, and the shortest correct path first. Advanced options, alternatives, and limits come after the happy path unless safety requires them earlier.

Avoid:

  • marketing language, hype, adjectives and adverbs that carry no fact,
  • metaphors, cliches, colloquialisms, clever headings,
  • unsupported claims, performance numbers without a source,
  • repeated information, summary or conclusion setup phrases,
  • meta-commentary about the docs or about AI,
  • em dashes (use a period, comma, colon, or parentheses),
  • vague references ("this", "it", "the above") where a section can be read alone,
  • internal implementation detail (module names, Celery queues, tables) unless an admin needs it to operate the product.

Write so that a section quoted alone still answers the reader's question. Name the feature and the page in the sentence, not only in the heading.

3. Mintlify page patterns

Frontmatter

---
title: "Document Processing"
description: "Configure document processing settings and options"
icon: "file-lines"
---

Keep description generic to the capability, not to the one vendor the UI shows today. Every page must be in docs.json or reachable by a redirects entry. Removed pages get a redirect, never a dead URL.

Structure

  • Use <Steps> / <Step title="..."> for procedures. Numbered Markdown lists fail the format-docs pre-commit hook.
  • Use shared snippets from snippets/ instead of repeating a block: navigate-to-ai-models.mdx, standard-ai-model-configs.mdx, enterprise-edition-info.mdx, business-edition-info.mdx, contact-us.mdx.
  • Tier gating: import the matching *-edition-info.mdx snippet at the top of a Business or Enterprise page. Say "Onyx Cloud includes every Business and Enterprise feature" only through the snippet, not in new prose.
  • Callouts (<Note>, <Tip>, <Warning>, <Info>) only when they change what the reader does. A <Warning> states the condition and the consequence.
  • Tables for parameters, env vars, and option lists. Bullets for unordered facts.
  • Links use descriptive anchor text and site-relative paths (/admins/connectors/overview).

Page shapes that work here

  • Connector page: what gets indexed, prerequisites in the source system, credential steps (vendor console), Onyx steps (Admin Panel → Connectors → New [Source] Account, Document Access), permission sync if supported, limits and troubleshooting.
  • Model provider / gateway page: short "Guide" intro, <NavigateToAiModels />, the Connect card steps with exact field names, <StandardAiModelConfigs />, final Connect.
  • Admin feature page: overview of the capability (generic), where it lives in the Admin Panel, the steps, what changes for users, tier note.
  • API guide: the shortest working request with real field names, then the contract table, then edge cases. Endpoint reference pages are generated from the OpenAPI spec; do not hand edit them (see developers/api_reference).

4. Images and video

  • Format: WebP for images (ffmpeg -i in.png -c:v libwebp -quality 90 out.webp), MP4 for motion. No PNG, GIF, or JPG in assets/ unless a vendor logo requires it.
  • Markup: <img className="rounded-image" src="/assets/<area>/<page>/<name>.webp" alt="..." />. Video: <video className="rounded-image" src="/assets/.../name.mp4" autoPlay muted loop playsInline aria-label="..." />.
  • Keep the existing path and filename when you replace a screenshot so the MDX does not change. Delete the asset file when you delete the image.
  • When a PR changes UI, recapture its screenshots in the same PR. Agents can use Playwright against http://localhost:3000 with the admin login in the root AGENTS.md.
  • Capture Onyx UI shots on a local stack: light theme, 1440x900 viewport at 2x device scale, admin user, seeded data that looks real (a connector, an agent, a chat), no personal data. Admin forms scroll in an inner container, so grow the viewport instead of fullPage. Hide the Next.js dev overlay (nextjs-portal) before every shot.
  • Business and Enterprise pages need a license on the stack. Upload it through Admin Panel → Billing; never commit it.
  • Vendor-console screenshots (Google Cloud, Atlassian, Slack) stay unless the vendor flow changed.
  • Add media only when text cannot show the flow. Every image has alt text that says what it shows.

5. Checks before you open a PR

Run from documentation/:

scripts/generate.sh                      # builds the opal SVGs and openapi.json (not committed)
python3 scripts/format_docs.py --write   # formats MDX and runs mintlify broken-links
python3 scripts/format_docs.py --check   # what the pre-commit hook runs
pre-commit run --files <changed files>

Also confirm:

  • every src="/assets/..." on the changed pages resolves to a file (logos and icons come from web/lib/opal; add new ones to scripts/generated_assets.json, not as SVG files),
  • docs.json lists new pages and has a redirect for each removed page,
  • the page renders in mint dev with no MDX error,
  • no secrets, license files, or local URLs in the diff.

prettier rewrites docs.json on commit, so a commit that touches it fails once: re-add and commit again.

6. Review rubric

Score 0 to 2 per row. Publish at 16/20 or higher with no zero.

Dimension2 means
Audience fitPrimary reader and goal are explicit
Task successSteps are complete, in order, and success is recognizable
Content typeOne Diataxis type per page or section
AccuracyEvery claim traced to code, the feature map, or the running UI
StructureHeadings, Steps, tables, and links form a clear map
ExamplesComplete, realistic, copyable, no secrets
TerminologyCurrent product names, used the same way everywhere
RetrievabilityEach section stands alone
MaintenanceEvergreen wording; volatile facts (versions, dates) are explicit
StyleSTE: short, active, reader-centred, no filler

7. Full-site audits

For a release refresh of many pages, use the tooling in audit/:

  • python3 audit/build_manifest.py writes audit/manifest.json: every page, its nav group, feature-map components, and image references.
  • audit/CHECKLIST.md is the per-page review unit for a fan-out of agents (one page group per agent; copy first, image verdicts reported, screenshots recaptured in a second pass).

8. What to report

When you finish a page or a review, state: the reader and page type, the structural changes, the files or UI routes you used to verify each claim, and every claim you could not verify.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.