cratis-discoverability
Check Cratis content before publishing for search and AI answers without sacrificing readability. Use when reviewing discoverability, SEO, AEO or GEO; writing fact blocks or download claims; editing package/repo metadata; checking docs titles, descriptions or LLM export budgets; or reviewing founder/company JSON-LD and member profile indexing. Not for page voice and structure (cratis-documentation-writing), llms.txt design (cratis-llm-friendly-documentation), distribution plans (cratis-developer-marketing) or length decisions (cratis-content-length).
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- cratis-discoverability
- license
- MIT
- description
- Check Cratis content before publishing for search and AI answers without sacrificing readability. Use when reviewing discoverability, SEO, AEO or GEO; writing fact blocks or download claims; editing package/repo metadata; checking docs titles, descriptions or LLM export budgets; or reviewing founder/company JSON-LD and member profile indexing. Not for page voice and structure (cratis-documentation-writing), llms.txt design (cratis-llm-friendly-documentation), distribution plans (cratis-developer-marketing) or length decisions (cratis-content-length).
02 资源文件 7
- 许可证LICENSE201 B
- 参考文档references/entities.md4.3 KB
- 参考文档references/facts-and-adoption.md3.5 KB
- 参考文档references/package-metadata.md3.7 KB
- 参考文档references/page-checklist.md5.7 KB
- 参考文档references/structured-data.md3.3 KB
- 脚本scripts/verify-discoverability.mjs6.0 KB
03 SKILL.md 正文
<!-- cratis-ai-managed: skills/cratis-discoverability/SKILL.md -->
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
descriptionis written by hand as one self-contained definition or outcome sentence. Tutorials, getting-started pages and explanations followwriting-cratis-docs(scenario first); the definition lives in thedescription, and one definition sentence may follow the opening scenario where it reads naturally.writing-cratis-docswins on voice and structure. Product index pages open with the definition sentence. Reference pages stay terse: title is the exact name plus its product, no question headings, no intro. 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 measurellms.txt/llms-small.txtbytes 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
lastUpdatedonly for real changes, link the owning docs pages withhttps://www.cratis.io/..., keepdescriptionapart from the cardexcerpt. - 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 inBRAND.md,MESSAGING.mdandSITE.md. - README. The H1 may be the product name ("Cratis <Product>"). 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.
PackageProjectUrlandhomepagepoint at the docs page, not only at GitHub. Readreferences/package-metadata.mdwhen editing package fields, GitHub About, Docker Hub descriptions, analyzer help links, template messages or README footers. Check these surfaces together; Authors and Company areCratis.
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 them only where they read naturally (concept pages, FAQs, comparisons, blog), never on reference pages or tutorial steps.
- Padding to a word count: there is no minimum length; a complete page is done.
- Apex
https://cratis.io/links: the docs host ishttps://www.cratis.io. - A description that repeats the title or a sibling page's description.
04 同仓库更多 Skills
cratis-writing-voice-and-cadence
Review and revise existing prose so it reads as written by a person, by finding overused constructions and stock phrasing in one piece and structural sameness across a batch, then fixing both with specifics instead of injected variety, without changing any technical claim. Flags are editing prompts and never a verdict on who wrote something. Use when reviewing or rewriting documentation, release notes, pull request descriptions, posts or reviews for voice. Do not use for technical accuracy review, original drafting, authorship detection, or as a reason to touch approved copy without authorization.
cratis-technical-examples
Design and verify developer-facing code samples, tutorial projects, and documentation snippets against real Cratis APIs. Use when adding or reviewing a runnable example, multi-client snippet, sample app, command/output pair, or migration before/after code. Do not invent API shapes or treat rendering as a compilation check.
cratis-release-notes
Draft or review developer-facing release notes and migration guidance from verified changes for a specific Cratis product version. Use for GitHub releases, upgrade guides, and release announcements; not for deciding release authority, publishing, or selecting a version label.
cratis-llm-friendly-documentation
Design or review machine-readable documentation indexes, Markdown mirrors and bounded product/topic exports for AI assistants. Use for llms.txt, llms-full.txt, per-product context sets, and documentation retrieval quality. Do not treat public exports as system instructions or promise crawler adoption.
cratis-documentation-writing
Plan, write, and improve user-centered Cratis documentation with a clear reader journey and one primary Diátaxis purpose per page. Use for product docs, tutorials, how-to guides, reference, explanations, and documentation reviews. For executable examples use cratis-technical-examples; for release notes use cratis-release-notes. Do not invent APIs or publish content.