Discoverability before you publish
Discoverability is a property of good content: a clear definition, an honest title, one name per
thing and working links. The always-on rule is discoverability.md;
this skill is the procedure to run on the finished draft. If a fix makes the page worse to read,
drop the fix and say so.
Procedure
- Name the content type: docs page, blog post, landing page, README, package/repo metadata or member profile.
- Name the reader's one job and, for docs, the page type (tutorial, how-to, reference, explanation).
- Apply the checks for that type below, including facts, adoption claims and privacy without waiting for a separate request. Fix the draft; do not annotate it.
- For a built site, run the checker and fix errors; warnings are judgment calls to report.
- Report what was changed, what was left alone and why.
Read references/page-checklist.md when checking a page, including docs lint baselines and LLM export budgets.
Checks by content type
- Docs page. The
description is written by hand as one self-contained
definition or outcome sentence. Follow writing-cratis-docs for the page's purpose, voice and
structure; it takes precedence over discoverability suggestions. A scenario can help a tutorial
or explanation, but is not a required opener. Product index pages should make the product's
purpose clear near the beginning without forcing a definition into the first sentence.
Reference pages stay terse: title is the exact name plus its product, headings support lookup,
and introductory context appears only where needed to use the entry. Titles are unique across
the site and name the product ("Chronicle projections"). Keep
description and duplicate-title lint baselines at 0; never raise a baseline to pass. Check
rendered titles and measure llms.txt / llms-small.txt bytes against the site budgets.
- Blog post. The title states the topic in the words a reader would search. The intro gives the
conclusion in two sentences. Show the named author and date, add
lastUpdated only for real
changes, link the owning docs pages with https://www.cratis.io/..., keep description apart
from the card excerpt.
- Landing page. One primary term in the title, the
<h1> or the first paragraph, and a
one-sentence definition above the fold. Brand lines stay; pair them with a category term in the
title and description. Respect the claim gate in BRAND.md, MESSAGING.md and SITE.md.
- README. The H1 may be the product name ("Cratis "). The first sentence defines the product in 15-35 plain
nouns, with no logo-only or metaphor opener. Links are absolute; link the docs page.
- Package metadata. One sentence naming what the package is and which Cratis product it belongs
to, identical to the README opener.
PackageProjectUrl and homepage point at the docs page, not
only at GitHub. Read references/package-metadata.md when editing package fields, GitHub About,
Docker Hub descriptions, analyzer help links, template messages or README footers. Check these
surfaces together; Authors and Company are Cratis.
Fact blocks and adoption claims
For each entity page, assemble one sourced "at a glance" block from verifiable facts, with dates
for counts. Read references/facts-and-adoption.md when selecting facts or calculating downloads:
identify entry packages and continuation predecessors, exclude sub-packages and overlapping
shared dependencies, round down to a stated threshold, and publish the month and registries.
Downloads are never users or customers. Omit unsupported claims instead of inventing customers,
user counts, benchmarks, certifications, prices or competitor comparisons. Keep shared guidance
generic; do not copy private integration names, legal entity details or factual counts into it.
Names
Use the canonical names, one per concept, and the first-mention rule. Read
references/entities.md when naming a product, writing a definition sentence or filling sameAs.
Do not invent a name, URL, maturity word or claim that the references do not state.
Structured data
Describe only what is visible on the page, one @graph per page, stable @ids. Add no HowTo and
no new FAQPage. Read references/structured-data.md for the patterns and what each page type
gets. Use only public, owner-approved founder/company facts. Do not name other people in
structured data; never add personal data or Person entities for community members. Member
profiles are noindex; check profile and CV routes, rendered robots directives and JSON-LD.
Without approved public founder facts, reference the organization by @id instead.
Checking a built site
For a built static site (Astro dist/ or a plain-HTML repository root), run with Node.js:
node <skill-directory>/scripts/verify-discoverability.mjs --root <dir> --site <https://host>.
It reports <html lang>, title, description, canonical host, <h1> count, JSON-LD parse errors,
robots.txt, the sitemap and llms.txt structure. Errors exit 1; warnings do not. Pass
--warn-only to downgrade errors and --require-llms where the site ships llms.txt.
Read scripts/verify-discoverability.mjs only when changing the checker.
Pitfalls
- Question headings everywhere: use a question only when it expresses the reader's actual question
more clearly than a subject or action heading. Do not impose one heading form across page types.
- Padding to a word count: there is no minimum length; a complete page is done.
- Apex
https://cratis.io/ links: the docs host is https://www.cratis.io.
- A description that repeats the title or a sibling page's description.
1---2name: cratis-discoverability3description: Use when checking Cratis search discoverability, metadata, adoption claims, structured data or indexing before publication. Not for page voice, export architecture, distribution strategy or content length.4license: MIT5metadata:6 source: https://skillmd.com/skills/cratis/cratis-discoverability7---89# Discoverability before you publish1011Discoverability is a property of good content: a clear definition, an honest title, one name per12thing and working links. The always-on rule is [discoverability.md](../../rules/discoverability.md);13this skill is the procedure to run on the finished draft. If a fix makes the page worse to read,14drop the fix and say so.1516## Procedure17181. Name the content type: docs page, blog post, landing page, README, package/repo metadata or member profile.192. Name the reader's one job and, for docs, the page type (tutorial, how-to, reference, explanation).203. Apply the checks for that type below, including facts, adoption claims and privacy without waiting for a separate request. Fix the draft; do not annotate it.214. For a built site, run the checker and fix errors; warnings are judgment calls to report.225. Report what was changed, what was left alone and why.2324Read `references/page-checklist.md` when checking a page, including docs lint baselines and LLM export budgets.2526## Checks by content type2728- **Docs page.** The `description` is written by hand as one self-contained29 definition or outcome sentence. Follow `writing-cratis-docs` for the page's purpose, voice and30 structure; it takes precedence over discoverability suggestions. A scenario can help a tutorial31 or explanation, but is not a required opener. Product index pages should make the product's32 purpose clear near the beginning without forcing a definition into the first sentence.33 Reference pages stay terse: title is the exact name plus its product, headings support lookup,34 and introductory context appears only where needed to use the entry. Titles are unique across35 the site and name the product ("Chronicle projections"). Keep36 description and duplicate-title lint baselines at 0; never raise a baseline to pass. Check37 rendered titles and measure `llms.txt` / `llms-small.txt` bytes against the site budgets.38- **Blog post.** The title states the topic in the words a reader would search. The intro gives the39 conclusion in two sentences. Show the named author and date, add `lastUpdated` only for real40 changes, link the owning docs pages with `https://www.cratis.io/...`, keep `description` apart41 from the card `excerpt`.42- **Landing page.** One primary term in the title, the `<h1>` or the first paragraph, and a43 one-sentence definition above the fold. Brand lines stay; pair them with a category term in the44 title and description. Respect the claim gate in `BRAND.md`, `MESSAGING.md` and `SITE.md`.45- **README.** The H1 may be the product name ("Cratis <Product>"). The first sentence defines the product in 15-35 plain46 nouns, with no logo-only or metaphor opener. Links are absolute; link the docs page.47- **Package metadata.** One sentence naming what the package is and which Cratis product it belongs48 to, identical to the README opener. `PackageProjectUrl` and `homepage` point at the docs page, not49 only at GitHub. Read `references/package-metadata.md` when editing package fields, GitHub About,50 Docker Hub descriptions, analyzer help links, template messages or README footers. Check these51 surfaces together; Authors and Company are `Cratis`.5253## Fact blocks and adoption claims5455For each entity page, assemble one sourced "at a glance" block from verifiable facts, with dates56for counts. Read `references/facts-and-adoption.md` when selecting facts or calculating downloads:57identify entry packages and continuation predecessors, exclude sub-packages and overlapping58shared dependencies, round down to a stated threshold, and publish the month and registries.59Downloads are never users or customers. Omit unsupported claims instead of inventing customers,60user counts, benchmarks, certifications, prices or competitor comparisons. Keep shared guidance61generic; do not copy private integration names, legal entity details or factual counts into it.6263## Names6465Use the canonical names, one per concept, and the first-mention rule. Read66`references/entities.md` when naming a product, writing a definition sentence or filling `sameAs`.67Do not invent a name, URL, maturity word or claim that the references do not state.6869## Structured data7071Describe only what is visible on the page, one `@graph` per page, stable `@id`s. Add no `HowTo` and72no new `FAQPage`. Read `references/structured-data.md` for the patterns and what each page type73gets. Use only public, owner-approved founder/company facts. Do not name other people in74structured data; never add personal data or `Person` entities for community members. Member75profiles are `noindex`; check profile and CV routes, rendered robots directives and JSON-LD.76Without approved public founder facts, reference the organization by `@id` instead.7778## Checking a built site7980For a built static site (Astro `dist/` or a plain-HTML repository root), run with Node.js:81`node <skill-directory>/scripts/verify-discoverability.mjs --root <dir> --site <https://host>`.82It reports `<html lang>`, title, description, canonical host, `<h1>` count, JSON-LD parse errors,83`robots.txt`, the sitemap and `llms.txt` structure. Errors exit 1; warnings do not. Pass84`--warn-only` to downgrade errors and `--require-llms` where the site ships `llms.txt`.85Read `scripts/verify-discoverability.mjs` only when changing the checker.8687## Pitfalls8889- Question headings everywhere: use a question only when it expresses the reader's actual question90 more clearly than a subject or action heading. Do not impose one heading form across page types.91- Padding to a word count: there is no minimum length; a complete page is done.92- Apex `https://cratis.io/` links: the docs host is `https://www.cratis.io`.93- A description that repeats the title or a sibling page's description.