shio-docs-write
Skill3 starsChanged 8 days agoApache-2.0View on GitHub
How to write or change a page of Shio's end-user documentation (shio-site/docs, Astro Starlight, served at shio.viglet.org/docs) so it reads as one coherent guide. Applies the shared docs-writing skill (Diátaxis, templates, style guide, reader's checklist) with Shio's paths, glossary, house style and gates. Use when a feature ships with a docs update (step 3 of shio-roadmap-docs), when a docs page is written, restructured or reviewed, or when a docs-style lint failure needs fixing. Trigger words: docs page, documentação, shio-site/docs, docs-style, Diátaxis, rewrite page.
In this repository14 other files it gives its agents.
- agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- roadkeepSkill
- shio-agent-surfaceSkill
- shio-build-testSkill
- shio-console-reviewSkill
- shio-console-uiSkill
- shio-content-apiSkill
- shio-content-filesSkill
- shio-databaseSkill
- shio-docs-syncSkill
- shio-rendererSkill
- shio-replication-testSkill
- shio-roadmap-docsSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 74
Every user-facing ship records its verdict in COVERAGE.md (✅ / 🧩 / 🔒, with the page and anchor) in the same commit as the page, then pnpm …
- Very specific: line 88
Never pipe a gate into grep (agents.md, SH354/SH788): redirect, then read the log.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Writing a Shio docs page
Apply docs-writing first. The shared skill (~/.claude/skills/docs-writing) has the
method, the page templates and the style guide; this file has only what is specific to
Shio, and wins where the two differ. Generated by docs-setup (SH1402); a gap here is
fixed in docs-setup, then regenerated.
Where a feature is documented, and whether it needs a page at all, is decided first by
shio-roadmap-docs (§ end-user documentation). Whether a page matches the code is
shio-docs-sync. This skill is how the page is written.
Where the pages are
- Pages:
shio-site/docs/src/content/docs/,.md, or.mdxwhen a page uses components.COVERAGE.mdsits beside them and is not a page (content.config.tsexcludes it). - Navigation: the
sidebarinshio-site/docs/astro.config.mjs, grouped under four hubs by who does the job:agent-builds-it.mdx,curator-approves-it.mdx,cda-delivers-it.mdx,run-it.mdx. A new page needs a sidebar row and a card on its hub, or it builds as an unlisted route nobody reaches. - A hub's landing text is what a block's changes usually move; a per-feature edit rarely touches it, so check it whenever a page's opening promise changes.
Framework components (Starlight)
- Steps:
<Steps>around an ordered list; callouts::::note,:::tip,:::caution,:::danger; tabs:<Tabs><TabItem label>; cards:<CardGrid><LinkCard>; keys:<kbd>Ctrl</kbd>. - Components need
.mdxand an import from@astrojs/starlight/components. Renaming.mdto.mdxkeeps the route;docs-links.test.mjsreads both.
Product name and links
- The product is Viglet Shio in every sentence and heading, not only the first: a bare
Shio is allowed only inside code, commands and link targets, and as the console labels
Shio Native and Shio Package.
scripts/full-names.test.mjsfails a page otherwise, and it reads line by line, so keepViglet Shioon one line. - Internal links are root-absolute
/docs/<slug>/#anchor, neverhttps://shio.viglet.org/docs. - Public code links point at
openviglet/shio.
Glossary
| Term | Means | Avoid |
| post | Any content item in Shio | entry, article, document |
| post type | The schema a post follows | content type (unless quoting the console's Content type filter, or a MIME type) |
| section | A post composed into a page by its layout | block, component (as a content term) |
| page | A post a site serves at a friendly URL | |
| site, folder | Where posts live; a folder belongs to one site | directory |
| draft / publish | The unpublished row, and the explicit act that makes it live | save live, push live |
| curator | The person who reviews and approves | the human, the user (as an actor) |
| agent | The coding agent driving MCP, files or the API | the AI, the bot |
| Visual Editor | Editing on the rendered page | Universal Editor (Adobe AEM's product name), WYSIWYG |
| layout, region, theme | The page structure posts are rendered through | |
| blueprint, pattern | An appliable starting point; a captured set of sections | recipe, snippet |
| review queue | Where agent changes wait for a curator | inbox |
| friendly URL | A post's address segment | slug (outside code) |
| Content Delivery API (CDA) | The read API a front end uses | delivery endpoint |
House style that differs from docs-writing
- No em dash in published prose (SH929; held for the site by
ai-writing.test.mjs, and for these pages by the docs-style lint). - A person is named by the role, not "the human" (SH705,
actor-vocabulary.test.mjs). - Numbers that the build measures (token figures, tool counts) are never typed by hand;
shio-roadmap-docsnames the generated sources.
Coverage
Every user-facing ship records its verdict in COVERAGE.md (✅ / 🧩 / 🔒, with the page and
anchor) in the same commit as the page, then pnpm run coverage:mirror. Keep an anchor
that COVERAGE or another page links to, or update the link in the same change.
Gates, in order
pnpm --filter shio-site test: includesscripts/docs-style.test.mjs(the mechanical style rules, SH1401) andscripts/docs-links.test.mjs(every/docslink and#anchorresolves).pnpm test: the JS gate; readshio-js-test.log.pnpm conformance:docs: names, versions and coverage against the code; readshio-conformance-docs.log.pnpm --filter shio-site build: Starlight fails on an unknown sidebar id.
Never pipe a gate into grep (agents.md, SH354/SH788): redirect, then read the log.
Debt
BASELINE in shio-site/scripts/docs-style.test.mjs lists the pages that still break a
style rule. When you rewrite a page, remove its entries in the same commit; the lint fails
on an entry that is paid. The rewrites are filed in roadkeep Block R (SH1403 to SH1409,
largest pages first).
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
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.

