agentleFS
openvigletopenviglet/shio/.claude/skills/shio-docs-write/SKILL.md

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.

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
  1. Very specific:

    Every user-facing ship records its verdict in COVERAGE.md (✅ / 🧩 / 🔒, with the page and anchor) in the same commit as the page, then pnpm …

    line 74
  2. Very specific:

    Never pipe a gate into grep (agents.md, SH354/SH788): redirect, then read the log.

    line 88

≈ “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.

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

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 .mdx when a page uses components. COVERAGE.md sits beside them and is not a page (content.config.ts excludes it).
  • Navigation: the sidebar in shio-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 .mdx and an import from @astrojs/starlight/components. Renaming .md to .mdx keeps the route; docs-links.test.mjs reads 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.mjs fails a page otherwise, and it reads line by line, so keep Viglet Shio on one line.
  • Internal links are root-absolute /docs/<slug>/#anchor, never https://shio.viglet.org/docs.
  • Public code links point at openviglet/shio.

Glossary

TermMeansAvoid
postAny content item in Shioentry, article, document
post typeThe schema a post followscontent type (unless quoting the console's Content type filter, or a MIME type)
sectionA post composed into a page by its layoutblock, component (as a content term)
pageA post a site serves at a friendly URL
site, folderWhere posts live; a folder belongs to one sitedirectory
draft / publishThe unpublished row, and the explicit act that makes it livesave live, push live
curatorThe person who reviews and approvesthe human, the user (as an actor)
agentThe coding agent driving MCP, files or the APIthe AI, the bot
Visual EditorEditing on the rendered pageUniversal Editor (Adobe AEM's product name), WYSIWYG
layout, region, themeThe page structure posts are rendered through
blueprint, patternAn appliable starting point; a captured set of sectionsrecipe, snippet
review queueWhere agent changes wait for a curatorinbox
friendly URLA post's address segmentslug (outside code)
Content Delivery API (CDA)The read API a front end usesdelivery 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-docs names 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

  1. pnpm --filter shio-site test: includes scripts/docs-style.test.mjs (the mechanical style rules, SH1401) and scripts/docs-links.test.mjs (every /docs link and #anchor resolves).
  2. pnpm test: the JS gate; read shio-js-test.log.
  3. pnpm conformance:docs: names, versions and coverage against the code; read shio-conformance-docs.log.
  4. 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).

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.